aurak/docs/tests/playwright-agent-map.md

Playwright 三 Agent 应用指南

三个 Agent：Generator（录制生成） · Planner（规划编排） · Healer（自我修复）

---

一、三 Agent 的本质区别

Agent	命令	作用	适合谁用
Generator	npx playwright codegen	录制浏览器操作，自动生成 .spec.ts 脚本	初学者、快速原型
Planner	npx playwright codegen --target test	编排多步测试流程，指定截图/断言点	测试设计者
Healer	npx playwright test --trace on	失败时自动重试 + 记录完整 DOM 快照和网络日志	CI、调试排查

---

二、当前测试脚本 vs Playwright Agent 使用对照

脚本                         Generator   Planner     Healer       测试层面
────────────────────────────────────────────────────────────────────────
test-systematic.mjs            ❌         ❌         ❌          API + 原生 Playwright
test-full-coverage.mjs         ❌         ❌         ❌          纯 API（无 UI）
test-assessment-smoke.mjs      ❌         ❌         ❌          API + 原生 Playwright
test-e2e-assessment-full-flow  ❌         ❌         ❌          API + 原生 Playwright
test-p2-advanced.mjs           ❌         ❌         ❌          纯 API
test-concurrent-assessments    ❌         ❌         ❌          纯 API
test-user-lifecycle.mjs        ❌         ❌         ❌          API + 原生 Playwright
test-permission-flow.mjs       ❌         ❌         ❌          API + 原生 Playwright
test-multiround.mjs            ❌         ❌         ❌          原生 Playwright
exam-organizer.mjs             ❌         ❌         ❌          API + 原生 Playwright

现状: 所有脚本都用 chromium.launch({ headless: true }) 手写，没有用 @playwright/test 框架， 也没有用三个 Agent 的任何功能。

---

三、各 Phase 应该怎么用 Playwright Agent

Phase 0 — 系统测试（回归用）

阶段: 每次代码变更后必跑
策略: 已有脚本完全覆盖，保持现状
Agent 使用: 不需要

Phase 1 — 新功能开发时的 UI 测试

┌──────────────────────────────────────────────────────────────────┐
│  Generator 应用场景                                               │
│                                                                  │
│  开发完一个新页面/功能后：                                        │
│                                                                  │
│  $ npx playwright codegen http://localhost:13001                 │
│                                                                  │
│  1. 浏览器自动打开，操作你想测试的流程                             │
│  2. 右侧代码面板同步生成 Playwright 脚本                          │
│  3. 点击 "Copy" 复制到测试文件                                    │
│  4. 去掉 `page.close()` 等冗余行                                  │
│  5. 加入你的断言 (expect)                                         │
│                                                                  │
│  生成示例:                                                        │
│  await page.goto('/assessment');                                  │
│  await page.click('text=AI协作技巧-对话测评');                     │
│  await page.click('text=开始专业评估');                            │
│  await page.waitForSelector('text=问题 1');                       │
│  expect(await page.textContent('body')).toContain('问题 1');      │
└──────────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────────┐
│  Planner 应用场景                                                 │
│                                                                  │
│  需要编排多步骤、多断言的复杂测试场景时：                          │
│                                                                  │
│  $ npx playwright codegen --target test -o tests/assess.spec.ts  │
│                                                                  │
│  此模式会生成 @playwright/test 格式的代码，包含：                  │
│  - test.describe 分组                                            │
│  - test() 用例函数                                               │
│  - expect() 断言                                                 │
│  - 自动截图点                                                    │
│                                                                  │
│  适合场景: 考核全流程（选模板→答题→看结果）                       │
│            管理员配置（创建模板→创建用户→分配权限）                │
└──────────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────────┐
│  Healer 应用场景                                                  │
│                                                                  │
│  当 UI 测试在 CI 中因未知原因失败时：                              │
│                                                                  │
│  $ npx playwright test --trace on                                │
│                                                                  │
│  Healer 自动做 3 件事:                                            │
│  1. 自动重试最多 2 次（防 flaky）                                  │
│  2. 失败时保存 Trace 文件（含 DOM 快照 + 网络日志 + 控制台输出）    │
│  3. 用 `trace.playwright.dev` 可交互式回放每一步                    │
│                                                                  │
│  查看 Trace:                                                      │
│  $ npx playwright show-trace test-results/**/trace.zip           │
│                                                                  │
│  在 Trace Viewer 中可以看到:                                      │
│  - 页面截图时间线（每步操作前后的截图）                             │
│  - Console 输出（包括 error/warning）                              │
│  - 网络请求（API 返回内容和状态码）                                 │
│  - DOM 快照（操作瞬间的 HTML）                                     │
└──────────────────────────────────────────────────────────────────┘

Phase 2 — 调试已有测试失败

当前脚本（chromium.launch 模式）不支持 Healer 自动重试，
因为 autofix/healing 是 @playwright/test 框架的特性。

如果要在现有脚本中用 Healer，需要改成 @playwright/test 格式：

  // 当前写法（无 Healer）
  const browser = await chromium.launch({ headless: true });
  const page = await browser.newPage();

  // 改写成 @playwright/test（带 Healer）
  import { test, expect } from '@playwright/test';
  
  test('考核全流程', async ({ page }) => {
    await page.goto('/assessment');
    // 失败时自动重试 2 次
    // 失败时自动保存 trace.zip
    // 失败时自动截图
  });

Phase 3 — 编写新测试的标准流程

Step 1: Generator 录制
  $ npx playwright codegen http://localhost:13001
  → 操作界面 → 复制生成的代码

Step 2: Planner 编排  
  将复制代码粘贴到 .spec.ts 文件
  加入 describe/test/expect 结构
  设置截图断言点

Step 3: Healer 验证
  $ npx playwright test --trace on
  → 自动运行所有测试
  → 失败自动重试
  → 失败生成 Trace
  → 用 show-trace 分析

---

四、现有脚本改用 @playwright/test 的改造方案

改造收益:
  ✅ 自动重试（flaky 测试不误报）
  ✅ Trace Viewer（失败时全量调试信息）
  ✅ HTML Report（可视化测试报告）
  ✅ 并行执行（多 worker 加速）
  ✅ 内置 expect 断言库

改造成本:
  ⏱ 每个脚本约 15 分钟改造时间
  🔧 需要创建 playwright.config.ts
  📁 测试文件需迁到 tests/ 目录

关键改动点:
  1. import { chromium } from 'playwright'
     → import { test, expect } from '@playwright/test'
  
  2. const browser = await chromium.launch({ headless: true })
     → test('name', async ({ page }) => { ... })
  
  3. 自定义 assert() 函数
     → expect(actual).toBe(expected)
  
  4. 无自动重试
     → test.retries(2) 或 playwright.config.ts 中全局配置

配置文件 playwright.config.ts:
  export default defineConfig({
    testDir: './tests',
    retries: 2,              ← Healer: 失败重试
    trace: 'on-first-retry', ← Healer: 首次重试时生成 Trace
    screenshot: 'on',        ← Healer: 每次操作截图
    workers: 4,              ← Planner: 并发执行
    reporter: 'html',        ← Planner: HTML 报告
  });

---

五、总结对照表

场景	当前做法	用 Generator	用 Planner	用 Healer
回归测试 142项	test-systematic.mjs	❌	❌	❌
烟雾测试	test-assessment-smoke.mjs	❌	❌	❌
端到端考核流程	test-e2e-assessment-full-flow.mjs	❌	❌	❌
编写新 UI 测试	手写 locator	✅ 录制	✅ 编排	—
调试 CI 失败	看日志	—	—	✅ Trace
复杂场景编排	手写断言	—	✅ 结构	—
新页面回归	手写	✅ 快速生成	—	✅ 自愈