playwright-pro

Playwright Pro

面向 AI 编码 Agent 的生产级 Playwright 测试工具包。

可用命令

作为 Claude Code 插件安装后，以下命令可通过 /pw: 调用：

命令	功能
/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	按你偏好的格式生成测试报告

快速开始工作流

大多数项目推荐的操作顺序：

1. /pw:pw-init          → scaffolds config, CI pipeline, and a first smoke test
2. /pw:generate      → generates tests from your spec or URL
3. /pw:pw-review        → validates quality and flags anti-patterns      ← always run after generate
4. /pw:fix <test>    → diagnoses and repairs any failing/flaky tests  ← run when CI turns red

验证检查点：

• 执行 /pw:generate 之后，提交前务必运行 /pw:pw-review；它会自动发现定位器反模式和缺失的断言。
• 执行 /pw:fix 之后，在本地重新运行完整测试套件（npx playwright test），确认修复没有引入回归。
• 执行 /pw:migrate 之后，运行 /pw:coverage，确认与旧测试套件的覆盖一致，然后再下线 Cypress/Selenium 测试。

示例：生成 → 审查 → 修复

# 1. Generate tests from a user story
/pw:generate "As a user I can log in with email and password"

# Generated: tests/auth/login.spec.ts
# → Playwright Pro creates the file using the auth template.

# 2. Review the generated tests
/pw:pw-review tests/auth/login.spec.ts

# → Flags: one test used page.locator('input[type=password]') — suggests getByLabel('Password')
# → Fix applied automatically.

# 3. Run locally to confirm
npx playwright test tests/auth/login.spec.ts --headed

# 4. If a test is flaky in CI, diagnose it
/pw:fix tests/auth/login.spec.ts
# → Identifies missing web-first assertion; replaces waitForTimeout(2000) with expect(locator).toBeVisible()

黄金法则

1. 优先使用 getByRole()，而非 CSS/XPath——对标记变化更具韧性
2. 永远不要使用 page.waitForTimeout()——改用面向 Web 的断言
3. expect(locator) 会自动重试；expect(await locator.textContent()) 不会
4. 隔离每个测试——测试之间不共享状态
5. 在配置中设置 baseURL——不硬编码任何 URL
6. 重试次数：CI 中为 2，本地为 0
7. Trace 设置为 'on-first-retry'——在不拖慢速度的前提下获得丰富的调试信息
8. 优先使用 Fixture 而非全局变量——用 test.extend() 共享状态
9. 每个测试只验证一个行为——多个相关断言是可以的
10. 仅 Mock 外部服务——永远不要 Mock 你自己的应用

定位器优先级

1. getByRole()        — buttons, links, headings, form elements
2. getByLabel()       — form fields with labels
3. getByText()        — non-interactive text
4. getByPlaceholder() — inputs with placeholder
5. getByTestId()      — when no semantic option exists
6. page.locator()     — CSS/XPath as last resort

包含内容

• 9 个技能，附带详细的分步说明
• 3 个专用 Agent：test-architect、test-debugger、migration-planner
• 55 个测试模板：认证、CRUD、结账、搜索、表单、仪表盘、设置、新手引导、通知、API、无障碍
• 2 个 MCP 服务（TypeScript）：TestRail 和 BrowserStack 集成 （可选——不会自动注册；参见集成设置）
• 智能钩子：自动校验测试质量，自动检测 Playwright 项目
• 6 份参考文档：黄金法则、定位器、断言、Fixture、常见陷阱、不稳定测试
• 迁移指南：Cypress 和 Selenium 的映射表

集成设置

不会自动注册（issue #978）。 TestRail 和 BrowserStack MCP 服务已不再声明在插件的 .mcp.json 中（它们对所有用户都无法连接，因为没有打包 node_modules）。仅导出下方的环境变量是不够的：在你手动启用该服务之前（cd integrations/<name>-mcp && npm install，然后将其注册到你自己的用户/项目 MCP 配置中），/pw:testrail / /pw:browserstack 会因"找不到工具"而失败。请参阅 CLAUDE.md → Integrations。

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 —— 自定义 Fixture 和 storageState 模式
• common-pitfalls.md —— 十大常见错误及修复方法
• flaky-tests.md —— 诊断命令和快速修复

完整的模板索引请参阅 templates/README.md。