Playwright 专业版
Playwright Pro
面向 AI 编码 Agent 的生产级 Playwright 测试工具包。
可用命令
安装为 Claude Code 插件后，可通过 /pw: 命令调用：
| 命令 | 功能描述 |
|---|---|
| /pw:init | 初始化 Playwright —— 自动检测框架，生成配置、CI 脚本及首个测试用例 |
| /pw:generate <spec> | 根据用户故事、URL 或组件生成测试 |
| /pw:review | 审查测试用例，检查反模式 (anti-patterns) 和覆盖率缺失 |
| /pw:fix <test> | 诊断并修复失败或不稳定的测试 |
| /pw:migrate | 从 Cypress 或 Selenium 迁移至 Playwright |
| /pw:coverage | 分析已测试内容与缺失内容的对比 |
| /pw:testrail | 与 TestRail 同步 —— 读取用例，推送结果 |
| /pw:browserstack | 在 BrowserStack 上运行，获取跨浏览器报告 |
| /pw:report | 以你偏好的格式生成测试报告 |
快速上手工作流
大多数项目的推荐执行顺序：
1. /pw:init → 构建配置、CI 流水线和首个冒烟测试
2. /pw:generate → 根据你的规格说明或 URL 生成测试
3. /pw:review → 验证质量并标记反模式 ← 生成后务必运行
4. /pw:fix <test> → 诊断并修复任何失败/不稳定的测试 ← CI 报错时运行验证检查点：
- 执行
/pw:generate后 —— 在提交前务必运行/pw:review；它能自动捕捉定位器反模式和缺失的断言。
- 执行
/pw:fix后 —— 在本地重新运行完整套件 (npx playwright test)，确认修复未引入回归问题。
- 执行
/pw:migrate后 —— 运行/pw:coverage确认与旧套件的功能对等，然后再弃用 Cypress/Selenium 测试。
示例：生成 $\rightarrow$ 审查 $\rightarrow$ 修复
# 1. 根据用户故事生成测试
/pw:generate "作为用户，我可以使用电子邮件和密码登录"
已生成: tests/auth/login.spec.ts
→ Playwright Pro 使用 auth 模板创建了该文件。
2. 审查生成的测试
/pw:review tests/auth/login.spec.ts
→ 标记：某个测试使用了 page.locator('input[type=password]') —— 建议使用 getByLabel('Password')
→ 自动应用修复。
3. 本地运行确认
npx playwright test tests/auth/login.spec.ts --headed
4. 如果测试在 CI 中不稳定，进行诊断
/pw:fix tests/auth/login.spec.ts
→ 识别出缺失 Web-first 断言；将 waitForTimeout(2000) 替换为 expect(locator).toBeVisible()
金科玉律 (Golden Rules)
1. 优先使用 getByRole() 而非 CSS/XPath —— 对标记更改更具鲁棒性
2. 严禁使用 page.waitForTimeout() —— 请使用 Web-first 断言
3. expect(locator) 会自动重试；而 expect(await locator.textContent()) 不会
4. 确保每个测试相互隔离 —— 测试之间不得共享状态
5. 在配置中使用 baseURL —— 杜绝硬编码 URL
6. 重试机制：CI 环境设为 2，本地环境设为 0
7. 追踪 (Traces)：设为 'on-first-retry' —— 在不降低速度的情况下提供丰富的调试信息
8. 优先使用 Fixtures 而非全局变量 —— 使用 test.extend() 处理共享状态
9. 每个测试仅验证一种行为 —— 但允许包含多个相关的断言
10. 仅 Mock 外部服务 —— 永远不要 Mock 你自己的应用程序
定位器优先级
1. getByRole() — 按钮、链接、标题、表单元素
2. getByLabe## 包含内容
- 9 项技能：附带详细的分步指南
- 3 个专业 Agent：测试架构师 (test-architect)、测试调试员 (test-debugger)、迁移规划师 (migration-planner)
- 55 个测试模板：涵盖 认证、CRUD、结账、搜索、表单、仪表盘、设置、引导页、通知、API、无障碍访问
- 2 个 MCP 服务器 (TypeScript)：TestRail 和 BrowserStack 集成
- 智能钩子 (Smart hooks)：自动验证测试质量，自动检测 Playwright 项目
- 6 份参考文档：黄金法则、定位器、断言、Fixtures、常见陷阱、不稳定测试 (flaky tests)
- 迁移指南：Cypress 和 Selenium 映射表
集成设置
TestRail (可选)
### BrowserStack (可选)
快速参考
请参阅
reference/ 目录：
golden-rules.md — 10 条不可逾越的黄金法则
locators.md — 完整的定位器优先级及速查表
assertions.md — Web-first 断言参考
fixtures.md — 自定义 Fixtures 和 storageState 模式
common-pitfalls.md — 10 大常见错误及修复方案
flaky-tests.md — 诊断命令与快速修复
完整模板索引请参阅
templates/README.md`。