# 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** |
| 复杂场景编排 | 手写断言 | — | ✅ **结构** | — |
| 新页面回归 | 手写 | ✅ **快速生成** | — | ✅ **自愈** |