Playwright Pro
面向 AI 编码代理的生产级 Playwright 测试工具包。
可用命令
安装为 Claude Code 插件后，以下命令可作为 /pw: 命令使用：
| 命令 | 功能说明 |
|---|---|
/pw:init | 初始化 Playwright — 自动检测框架，生成配置、CI 管道和首个测试 |
/pw:generate <spec> | 根据用户故事、URL 或组件生成测试 |
/pw:review | 审查测试，检查反模式和覆盖率缺口 |
/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 → 验证质量并标记反模式 ← 始终在 generate 之后运行
4. /pw:fix <test> → 诊断并修复失败/不稳定测试 ← 当 CI 显示红色时运行
验证检查点：
- 在
/pw:generate之后 — 始终在提交前运行/pw:review；它会自动捕获定位器反模式和缺失的断言。 - 在
/pw:fix之后 — 在本地重新运行完整套件 (npx playwright test)，以确认修复不会引入回归。 - 在
/pw:migrate之后 — 运行/pw:coverage确认与旧套件的一致性，然后再停用 Cypress/Selenium 测试。
示例：生成 → 审查 → 修复
# 1. 根据用户故事生成测试
/pw:generate "作为用户，我可以使用邮箱和密码登录"
# 生成文件：tests/auth/login.spec.ts
# → Playwright Pro 使用认证模板创建该文件。
# 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 优先断言；将 waitForTimeout(2000) 替换为 expect(locator).toBeVisible()
黄金规则
getByRole()优于 CSS/XPath — 对标记更改具有弹性- 绝不使用
page.waitForTimeout()— 使用 Web 优先断言 expect(locator)自动重试；expect(await locator.textContent())不会- 每个测试相互隔离 — 测试之间无共享状态
- 配置中使用
baseURL— 不硬编码 URL - 重试：CI 中
2次，本地0次 - 追踪：
'on-first-retry'— 丰富调试且不拖慢速度 - 使用 Fixtures 而非全局变量 — 用
test.extend()管理共享状态 - 每个测试一个行为 — 多个相关断言是可以的
- 仅模拟外部服务 — 绝不模拟你自己的应用
定位器优先级
1. getByRole() — 按钮、链接、标题、表单元素
2. getByLabel() — 带标签的表单字段
3. getByText() — 非交互文本
4. getByPlaceholder() — 带占位符的输入框
5. getByTestId() — 当没有语义选项时
6. page.locator() — CSS/XPath 作为最后手段
包含内容
- 9 个技能，提供详细的逐步说明
- 3 个专门代理：测试架构师、测试调试器、迁移规划器
- 55 个测试模板：认证、CRUD、结账、搜索、表单、仪表盘、设置、入门引导、通知、API、无障碍
- 2 个 MCP 服务器（TypeScript）：TestRail 和 BrowserStack 集成
- 智能钩子：自动验证测试质量、自动检测 Playwright 项目
- 6 份参考文档：黄金规则、定位器、断言、fixtures、常见陷阱、不稳定测试
- 迁移指南：Cypress 和 Selenium 映射表
集成设置
TestRail（可选）
export TESTRAIL_URL="https://your-instance.testrail.io"
export TESTRAIL_USER="[email protected]"
export TESTRAIL_API_KEY="your-api-key"
BrowserStack（可选）
export BROWSERSTACK_USERNAME="your-username"
export BROWSERSTACK_ACCESS_KEY="your-access-key"
快速参考
查看 reference/ 目录中的文件：
golden-rules.md— 10 条不可妥协的规则locators.md— 完整的定位器优先级及速查表assertions.md— Web 优先断言参考fixtures.md— 自定义 fixtures 和 storageState 模式common-pitfalls.md— 前 10 个常见错误及其修复flaky-tests.md— 诊断命令和快速修复
查看 templates/README.md 获取完整模板索引。
何时使用
在需要指导或自动化 playwright-pro 相关操作时使用此技能。