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

61 lines
5.4 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 密钥依赖,也不把应用内容发往第三方**。
## 用法(三个场景)
```bash
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 剩余死选择器清理(需与视觉基线写授权分开审批)。