Developer
e12d5aafbf
删除: FEATURE_SUMMARY.md / QUICK_START.md / STARTUP.md
INTERNAL_DEPLOYMENT_GUIDE.md / INTERNAL_DEPLOYMENT_SUMMARY.md
start-server.bat / start-web.bat / .dockerignore
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
210 lines
10 KiB
Markdown
210 lines
10 KiB
Markdown
# 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** |
|
||
| 复杂场景编排 | 手写断言 | — | ✅ **结构** | — |
|
||
| 新页面回归 | 手写 | ✅ **快速生成** | — | ✅ **自愈** |
|