Playwright Test Agents — planner / generator / healer 交付协议

你现在运行 playwright-test-agents 技能。目标：让 coding agent 一条命令给一个可以打开的 web 应用 落一份人类可读的测试计划 + 可执行的 Playwright e2e 用例 + 一份带 trace 的 HTML 报告，UI 变了以后 自动修好挂掉的用例。

底层直接用 Microsoft 官方 @playwright/test（v1.56+ 内置 init-agents 三-agent 组合），无 wrapper。 全程本地，agent 推理走用户已在用的 coding IDE 订阅（主推 Claude Code，备胎 VS Code + Copilot）， 无第三方 API key、无 Clawvard 后端调用、无本地模型推理。

前置条件

• Node ≥ 20（node -v）
• 一个带 Playwright agent 循环的 IDE：主推 Claude Code (--loop=claude)，备胎 VS Code + Copilot (--loop=vscode)。
• 一个可以打开的 web 应用 URL。本文档全程用 Playwright 官方公开 demo https://demo.playwright.dev/todomvc， 换成你自己的站点时把 baseURL 和 popularTask 里的 URL 换掉即可。
• 磁盘约 250 MB（@playwright/test npm 包 ~80 MB + Chromium binary ~170 MB）。

安装（一次性）

mkdir e2e && cd e2e
npm init -y
npm i -D @playwright/test
npx playwright install chromium        # 只装 Chromium；不要 --with-deps，也不要 firefox / webkit

install chromium 覆盖 headless 模式所需的一切；本课程不需要系统包（--with-deps 会拉一大堆 libnss3 / libx11 系统 apt 包，Docker/CI 之外的桌面机没必要）。

三-agent 落地：npx playwright init-agents

npx playwright init-agents --loop=claude    # 主推
# 或
npx playwright init-agents --loop=vscode    # 备胎：VS Code + Copilot

这条命令写入三份 agent 配置：

• planner — 打开你的 URL，识别可测行为，写 ./specs/*.md（人类可读，先给你审）
• generator — 读 ./specs/*.md，翻成 ./tests/*.spec.ts 并跑绿
• healer — 用例挂掉时读 failure + 页面结构，只改锁定器（selector / role locator / testid）， 不改断言逻辑，再跑一次

主推与备胎的区别只是"哪个 IDE 里的 agent 在推理"：Claude Code 里就是 Claude；VS Code 里就是 Copilot。行为、产物、SOP 命令完全一致。主推路径不可用（比如学员不装 Claude Code）时直接切 --loop=vscode。

资源与并发红线

• --workers=1 或 --workers=2。demo 站点 + agent 读 trace 时，单 worker 更稳。
• 全程 headless（headless: true）。不要 --headed；trace viewer 打开 trace.zip 就能"回放"整次跑。
• 每次运行只跑一个 project（例：{ name: "chromium" }）；不要一次跑 chromium + firefox + webkit。
• 磁盘峰值 ~500 MB（node_modules + Chromium + 一次 trace/report），内存峰值 ~600 MB。

推荐 playwright.config.ts

import { defineConfig, devices } from "@playwright/test";

export default defineConfig({
  testDir: "./tests",
  fullyParallel: false,
  workers: 1,
  reporter: [["html", { open: "never" }], ["list"]],
  use: {
    baseURL: "https://demo.playwright.dev",   // 换成你自己的站点
    headless: true,
    trace: "on",
    screenshot: "only-on-failure",
  },
  projects: [{ name: "chromium", use: { ...devices["Desktop Chrome"] } }],
});

trace: "on" 会让每次跑都保留一份可回放的 trace.zip；healer 读 trace 比读堆栈更有效。

两个 popularTask 的 canonical 流程

任务 1 · 从零生成完整 e2e（planner → generator）

1. npm init -y && npm i -D @playwright/test && npx playwright install chromium
2. npx playwright init-agents --loop=claude（或 --loop=vscode）
3. 在 IDE 里让 planner agent 打开 https://demo.playwright.dev/todomvc、探页面、把可测行为分类 写进 ./specs/todomvc.md（新增 / 勾选 / 编辑 / 过滤 / 清空 5 类场景）。
4. 让 generator agent 把这份 spec 翻成 ./tests/todomvc.spec.ts，跑 npx playwright test --workers=1 --reporter=html，落 ./playwright-report/。
5. 交付：./specs/todomvc.md、./tests/todomvc.spec.ts、./playwright-report/index.html， 并附一句话说明每个 test case 对应 spec 里的哪条计划。

canonical 参考产物见 example/：

• example/specs/todomvc.md
• example/tests/todomvc.spec.ts（8 test cases 全绿）
• example/report/report.png（HTML report 首页）
• example/report/trace.png（trace viewer 时间线）

任务 2 · 故意改坏 selector，让 healer 修好

1. 沿用任务 1 的 ./tests/todomvc.spec.ts，把某条用例的 selector 从 .new-todo 改成 .new-todo-BROKEN，保存。
2. 跑 npx playwright test --workers=1 --reporter=html，用例挂掉；trace.zip 与 test-failed-*.png 存进 ./before/。
3. 在 IDE 里让 healer agent 读 failure + 当前页面结构，把 selector 改回可用状态。 healer 只动锁定器，不动断言逻辑。
4. 再跑一次，用例复绿，test-finished-*.png 存进 ./after/。
5. 交付：./heal-report.md（改坏的 diff + healer 修好的 diff + before/after 截图）。

canonical 参考产物见 example/：

• example/heal/todomvc-add.spec.before.ts（改坏后的 spec）
• example/heal/todomvc-add.spec.after.ts（healer 修好后的 spec；单行 selector 改动）
• example/heal/before.png（挂掉时空白 todo 列表）
• example/heal/after.png（healer 后 3 个 todo 正确落位）

红线

• 不要新造 wrapper 或私有 CLI 包装。直接 @playwright/test v1.56+ 官方 API。
• 不要 --headed 常驻，不要在 config 里同时列 chromium + firefox + webkit。
• 不要 npx playwright install --with-deps。学员桌面机不需要 apt 依赖包。
• 不要把课程 SOP 指向任何第三方推理 relay；agent 推理完全走用户 IDE 订阅。
• 换目标站点：把 baseURL 与 spec 里的 URL 一起改；planner 是从 URL 探页面的，别只改一半。

学习完成后

告诉用户：

我已经学会了 playwright-test-agents。给我一个可以打开的 web 站点 URL，我一条 npx playwright init-agents 拉起 planner → generator → healer：写一份人类可读的 测试计划、把它落成 .spec.ts、跑绿、留 HTML 报告 + trace；等 UI 改动把 selector 打断， healer 会读 failure + 当前页面结构，改一行 selector 让用例复绿。全程本地跑、headless、 单 worker，无第三方 API key。