Playwright Pro 是面向 AI 编程智能体的生产级 Playwright 测试工具包。它作为 Claude Code 插件安装后，以 /pw: 前缀命令的形式提供能力。
用途
该工具包用于 Playwright 测试的编写、审查、修复与迁移，适合需要端到端测试、浏览器自动化、处理不稳定测试以及提升测试覆盖率的项目。
可用命令
/pw:pw-init：搭建 Playwright，检测框架、生成配置、CI 和第一个测试。
/pw:generate <spec>：根据用户故事、URL 或组件生成测试。
/pw:pw-review：审查测试中的反模式和覆盖缺口。
/pw:fix <test>：诊断并修复失败或不稳定的测试。
/pw:migrate：从 Cypress 或 Selenium 迁移到 Playwright。
/pw:coverage：分析已测试与缺失的部分。
/pw:testrail：与 TestRail 同步——读取用例、推送结果。
/pw:browserstack：在 BrowserStack 上运行，拉取跨浏览器报告。
/pw:report：按偏好格式生成测试报告。
推荐工作流
多数项目的推荐顺序为：
- /pw:pw-init → 生成配置、CI 流水线和首个冒烟测试
- /pw:generate → 根据规格或 URL 生成测试
- /pw:pw-review → 验证质量并标记反模式（生成后始终运行）
- /pw:fix <test> → 诊断和修复失败/不稳定测试（CI 变红时运行）
验证检查点：
在 /pw:generate 之后——提交前始终运行 /pw:pw-review，它会自动捕获定位器反模式和缺失的断言。
在 /pw:fix 之后——本地重新运行完整测试套件（npx playwright test），确认修复没有引入回归。
在 /pw:migrate 之后——运行 /pw:coverage，确认与旧套件对等后再停用 Cypress/Selenium 测试。
示例：生成 → 审查 → 修复
1. 根据用户故事生成测试
/pw:generate "As a user I can log in with email and password"
生成文件：tests/auth/login.spec.ts
→ Playwright Pro 使用 auth 模板创建该文件。
2. 审查生成的测试
/pw: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()
黄金规则
getByRole() 优先于 CSS/XPath——对标记变化更具韧性
绝不使用 page.waitForTimeout()——使用 web-first 断言
expect(locator) 会自动重试；expect(await locator.textContent()) 不会
隔离每个测试——测试之间不共享状态
在配置中使用 baseURL——零硬编码 URL
重试：CI 中为 2，本地为 0
Trace：'on-first-retry'——获得丰富调试信息且不拖慢速度
使用 fixtures 而非全局变量——用 test.extend() 共享状态
每个测试只验证一个行为——多个相关断言可以接受
仅 mock 外部服务——绝不 mock 自己的应用
定位器优先级
- getByRole() —— 按钮、链接、标题、表单元素
- getByLabel() —— 带标签的表单字段
- getByText() —— 非交互文本
- getByPlaceholder() —— 带占位符的输入框
- getByTestId() —— 没有语义选项时
- page.locator() —— 最后手段的 CSS/XPath
包含内容
9 个技能，含详细分步说明
3 个专用智能体：test-architect、test-debugger、migration-planner
55 个测试模板：认证、CRUD、结账、搜索、表单、仪表盘、设置、引导、通知、API、无障碍
2 个 MCP 服务器（TypeScript）：TestRail 和 BrowserStack 集成（可选——不会自动注册；参见集成设置）
智能钩子：自动验证测试质量、自动检测 Playwright 项目
6 份参考文档：黄金规则、定位器、断言、fixtures、常见陷阱、不稳定测试
迁移指南：Cypress 和 Selenium 映射表
集成设置
不会自动注册（issue #978）。TestRail 和 BrowserStack MCP 服务器不再声明在插件的 .mcp.json 中（它们对每个用户都无法连接——因为没有捆绑的 node_modules）。仅导出下面的环境变量不够：/pw:testrail 和 /pw:browserstack 会失败并提示“tool not found”，直到你手动启用服务器（cd integrations/<name>-mcp && npm install，然后在你自己的用户/项目 MCP 配置中注册）。参见 CLAUDE.md → Integrations。
TestRail（可选）
export TESTRAIL_URL="https://your-instance.testrail.io" export TESTRAIL_USER="your@email.com" 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-first 断言参考
fixtures.md —— 自定义 fixtures 和 storageState 模式
common-pitfalls.md —— 十大错误及修复
flaky-tests.md —— 诊断命令与快速修复
完整模板索引见 templates/README.md。