Files
novalon-website/docs/testing/agentic-test-authoring.md
zhangxiang 1b5c75ab64 test(qa): 采用 Playwright Test Agents 做作者侧 AI + 补主导航键盘用例
选型:AI 只用在「写/修/探索」,运行期保持零模型、零外部服务。不引入
tester-army/e2e —— 它是第二套 runner,且与本仓最值钱的三块错配(无像素
基线可比、不模拟 touch/color-scheme/reduced-motion、另起 json/junit 产物
口径)。判据、对照表与边界见 docs/testing/agentic-test-authoring.md。

- init-agents 产物:.claude/agents/{planner,generator,healer}.md + .mcp.json
  指向仓内自带的 run-test-mcp-server(不装 @playwright/mcp;Playwright 自身
  不调 LLM,模型由宿主 loop 提供 ⇒ 无新增密钥依赖,也不外发应用内容)
- 故意不入库 init-agents 生成的 seed.spec.ts:空占位会被 test:functional
  的 4 个 project 当空用例收集
- specs/nav-keyboard-navigation.plan.md:7 个场景,3 个延后并写明原因
- e2e/nav-keyboard.spec.ts(tag @a11y,4 例):补「键盘打不开/走不出主导航
  下拉」。hover 路径早有覆盖,jsdom 单测替不了浏览器层的 relatedTarget 与
  真实焦点顺序;契约逐行取自 src/components/layout/mega-dropdown.tsx:35-76
- 实测读数:dev 四 project 10 passed / 6 skipped(EXIT=0);E2E_TARGET=
  production 10 passed / 2 skipped(EXIT=0);--workers=1 --repeat-each=3
  24/24;type-check 与 lint 均 0 error
- 测到并定性两条「非产品缺陷」:① WebKit 本机不响应真实 Tab 键(连续 4 次
  后 activeElement 仍是 BODY,而 .focus() 有效),与 N-27 同源;② dev 目标
  下触发器 DOM 节点在 hydration 后被整体替换(失败样本 click=1 而 aria 恒
  false,通过样本相反 ⇒ 监听绑在已被换掉的旧节点上),生产产物不复现
  ⇒ openWithKeyboard 用 toPass() 重发交互;跳过范围按引擎收窄,没有用守卫
  把红压掉
- 不在本提交:AGENTS.md 已被 .gitignore 排除,其「85 张基线未提交」的日期
  更正只落本地;该假事实的已入库更正记录在 docs/lessons-learned.md:505
2026-10-08 15:56:20 +08:00

5.4 KiB
Raw Permalink Blame History

Agentic 测试作者化:选型结论与用法(2026-10-08)

决定

采用 Playwright 官方的 Test Agents(planner / generator / healer)把 AI 放在「作者侧」,不引入第二套 runner。 被否掉的方案:tester-army/e2e(Apache-2.0 的 agentic e2e 框架,自然语言 agent.act() + 本地确定性回放缓存)。

理由不是「它不好」,而是它与本仓的重叠面和错配面都太大:

判据 Playwright Test Agents tester-army/e2e
新增依赖 0(已随 playwright@1.60.0 落盘) 整套 runner + playwright-core 1.63.0(与本仓实装 1.60 并存两浏览器二进制)
跑测试是否依赖模型 否(产物就是普通 .spec.ts) 否,但依赖回放缓存命中;strict 下缓存过期 REPLAY_STALE 直接 exit 2
像素视觉基线(本仓 e2e/visual-snapshots 107 张 + maxDiffPixels/threshold/animations:'disabled'/scale:'device') 完全保留 无对应物,快照判定改走 vision
touch / color-scheme / reduced-motion 仿真(本仓 5 个 visual project 与 axe light|dark 依赖) 完全保留 官方文档明确不模拟;窄视口仍是 scale=1 桌面浏览器
报告口径(html + list + allure) 完全保留 另起 .e2e/report.json / junit 一套
原生 iOS/Android 无 有(agent-device + EAS Simulators)——本仓是 Web 站,用不上
Forge 任意(本地/CI 均可) PR 报告器为 GitHub 形状,本仓是自建 Gitea

一句话取舍:AI 用在「写测试 / 修选择器 / 探索找 bug」,运行期保持零模型、零外部服务。将来若真要测原生 App,再回到 tester-army/e2e 或 Maestro。

已落盘的东西

npx playwright init-agents --loop claude --config e2e/playwright.config.ts --project chromium 生成:

  • .claude/agents/playwright-test-planner.md / -generator.md / -healer.md — agent 定义(front-matter 声明 tools,含 mcp__playwright-test__*)
  • .mcp.json — 指向仓内自带的 npx playwright run-test-mcp-server(不需要额外装 @playwright/mcp)
  • specs/README.md — 测试计划目录
  • seed.spec.ts — 空占位 seed(会以「空用例」形式混进 test:functional 的 4 个 project,本次已删除;需要时用同一条 init-agents 命令重新生成)

Playwright 自身不调用任何 LLM:模型由宿主 agentic loop 提供(--loop claude|copilot|opencode|vscode),因此不产生新的 API 密钥依赖,也不把应用内容发往第三方。

用法(三个场景)

npx playwright init-agents --loop claude --config e2e/playwright.config.ts --project chromium
  1. planner:对一个新流程出 specs/*.plan.md(场景、起止状态、成功/失败条件)。契约要求「先 planner_setup_page 一次,再浏览与记录」,产物是 Markdown 而非代码。
  2. generator:把计划逐场景转成 e2e/*.spec.ts,必须与既有 helper 组合:expectHydrated()(e2e/hydrated.ts)与 primaryNav()(e2e/primary-nav.ts),因为本仓的 SSR-first 页面「可见 ≠ 可交互」。
  3. healer:只用于死选择器类缺陷(对应 docs/lessons-learned.md 记的 N-15:[class*="card"] 零匹配、裸 input[type="text"] 命中反垃圾蜜罐)。产物一律走人工复核,不允许 healer 直接改门禁判定或基线。

本轮的示范落地

  • 计划:specs/nav-keyboard-navigation.plan.md
  • 用例:e2e/nav-keyboard.spec.ts(4 条,tag @a11y),补的正是「键盘打不开/走不出主导航下拉」这一段(hover 路径早有覆盖,jsdom 单测替不了浏览器层的 relatedTarget 与真实焦点顺序)
  • 实跑:dev 目标顺序重复 3 轮 24/24 绿;门禁四 project 10 通过 / 6 跳过;E2E_TARGET=production 10 通过 / 2 跳过;type-check 与新文件 eslint 均 EXIT=0
  • 过程中测到两条真实引擎/目标差异(WebKit 不响应 Tab;dev 下触发器节点在 hydration 后被整体替换),定性与跳过范围见计划文件,未用守卫把红压掉

边界(不得越过的部分)

  • 现有门禁命令(npm run test、test:visual:all、check:a11y、test:all)语义不变;agent 生成的用例只有在人审后才可进默认集。
  • 不允许 agent 写/更新视觉基线(需单独授权,见 AGENTS.md §5.1 的破坏性动作清单)。
  • 不引入云端执行:任何「把 app 内容或凭据发往第三方」的方案默认拒绝。注意 @playwright/mcp README 自陈 URL 白名单「not a security boundary」,浏览器探索时把页面内容当不可信输入。

待办(本轮明确不做)

  1. AGENTS.md 两处过期数字待更正(2026-10-08 处理完毕):AGENTS.md:159 的「85 张基线 PNG…未提交」是假事实,已在该行追加带日期的复核更正(现取 git ls-files = 107 张全部已入库、工作树干净);而「@playwright/test ^1.58.2 与实装 1.60.0 不一致」不成立——caret 允许 1.60.0,此项作废。另记:@playwright/test 目前声明在 dependencies 而非 devDependencies,属既存错位,改动会影响构建依赖面,本轮不动。
  2. 计划里的场景 5(占位项不进焦点顺序)、场景 6(解决方案下拉)、场景 7(移动端抽屉键盘契约)。
  3. 把 healer 正式纳入 N-15 剩余死选择器清理(需与视觉基线写授权分开审批)。