Playwright Pro
Production-grade Playwright testing toolkit for AI coding agents.
Available Commands
When installed as a Claude Code plugin, these are available as /pw: commands:
| Command | What it does |
|---|
| INLINECODE1 | Set up Playwright — detects framework, generates config, CI, first test |
| INLINECODE2 |
Generate tests from user story, URL, or component |
|
/pw:review | Review tests for anti-patterns and coverage gaps |
|
/pw:fix <test> | Diagnose and fix failing or flaky tests |
|
/pw:migrate | Migrate from Cypress or Selenium to Playwright |
|
/pw:coverage | Analyze what's tested vs. what's missing |
|
/pw:testrail | Sync with TestRail — read cases, push results |
|
/pw:browserstack | Run on BrowserStack, pull cross-browser reports |
|
/pw:report | Generate test report in your preferred format |
Quick Start Workflow
The recommended sequence for most projects:
CODEBLOCK0
Validation checkpoints:
- - After
/pw:generate — always run /pw:review before committing; it catches locator anti-patterns and missing assertions automatically. - After
/pw:fix — re-run the full suite locally (npx playwright test) to confirm the fix doesn't introduce regressions. - After
/pw:migrate — run /pw:coverage to confirm parity with the old suite before decommissioning Cypress/Selenium tests.
Example: Generate → Review → Fix
CODEBLOCK1
Golden Rules
- 1.
getByRole() over CSS/XPath — resilient to markup changes - Never
page.waitForTimeout() — use web-first assertions - INLINECODE18 auto-retries;
expect(await locator.textContent()) does not - Isolate every test — no shared state between tests
- INLINECODE20 in config — zero hardcoded URLs
- Retries:
2 in CI, 0 locally - Traces:
'on-first-retry' — rich debugging without slowdown - Fixtures over globals —
test.extend() for shared state - One behavior per test — multiple related assertions are fine
- Mock external services only — never mock your own app
Locator Priority
CODEBLOCK2
What's Included
- - 9 skills with detailed step-by-step instructions
- 3 specialized agents: test-architect, test-debugger, migration-planner
- 55 test templates: auth, CRUD, checkout, search, forms, dashboard, settings, onboarding, notifications, API, accessibility
- 2 MCP servers (TypeScript): TestRail and BrowserStack integrations
- Smart hooks: auto-validate test quality, auto-detect Playwright projects
- 6 reference docs: golden rules, locators, assertions, fixtures, pitfalls, flaky tests
- Migration guides: Cypress and Selenium mapping tables
Integration Setup
TestRail (Optional)
CODEBLOCK3
BrowserStack (Optional)
CODEBLOCK4
Quick Reference
See reference/ directory for:
- -
golden-rules.md — The 10 non-negotiable rules - INLINECODE27 — Complete locator priority with cheat sheet
- INLINECODE28 — Web-first assertions reference
- INLINECODE29 — Custom fixtures and storageState patterns
- INLINECODE30 — Top 10 mistakes and fixes
- INLINECODE31 — Diagnosis commands and quick fixes
See templates/README.md for the full template index.
Playwright Pro
面向AI编码代理的生产级Playwright测试工具包。
可用命令
作为Claude Code插件安装后，可通过/pw:命令使用：
| 命令 | 功能说明 |
|---|
| /pw:init | 初始化Playwright — 检测框架、生成配置、CI配置、首个测试 |
| /pw:generate <spec> |
根据用户故事、URL或组件生成测试 |
| /pw:review | 审查测试中的反模式和覆盖缺口 |
| /pw:fix
| 诊断并修复失败或不稳定的测试 |
| /pw:migrate | 从Cypress或Selenium迁移至Playwright |
| /pw:coverage | 分析已测试与缺失部分 |
| /pw:testrail | 与TestRail同步 — 读取用例、推送结果 |
| /pw:browserstack | 在BrowserStack上运行，拉取跨浏览器报告 |
| /pw:report | 以首选格式生成测试报告 |
快速入门工作流
大多数项目的推荐顺序：
- 1. /pw:init → 搭建配置、CI流水线和首个冒烟测试
- /pw:generate → 根据规范或URL生成测试
- /pw:review → 验证质量并标记反模式 ← 每次生成后必须执行
- /pw:fix → 诊断并修复失败/不稳定测试 ← CI变红时执行
验证检查点：
- - 执行/pw:generate后 — 提交前务必运行/pw:review；它会自动捕获定位器反模式和缺失断言。
- 执行/pw:fix后 — 在本地重新运行完整测试套件（npx playwright test）以确认修复未引入回归。
- 执行/pw:migrate后 — 在停用Cypress/Selenium测试前运行/pw:coverage以确认与旧套件功能一致。
示例：生成 → 审查 → 修复
bash
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()
黄金法则
- 1. 优先使用getByRole()而非CSS/XPath — 对标记变更具有弹性
- 绝不使用page.waitForTimeout() — 使用web优先断言
- expect(locator)自动重试；expect(await locator.textContent())不会
- 隔离每个测试 — 测试间不共享状态
- 在配置中使用baseURL — 零硬编码URL
- 重试次数：CI中2次，本地0次
- 追踪：on-first-retry — 丰富调试且不降低速度
- 使用fixture而非全局变量 — 使用test.extend()管理共享状态
- 每个测试一个行为 — 多个相关断言没问题
- 仅模拟外部服务 — 绝不模拟自己的应用
定位器优先级
- 1. getByRole() — 按钮、链接、标题、表单元素
- getByLabel() — 带标签的表单字段
- getByText() — 非交互式文本
- getByPlaceholder() — 带占位符的输入框
- getByTestId() — 无语义选项时使用
- page.locator() — CSS/XPath作为最后手段
包含内容
- - 9项技能，附带详细分步说明
- 3个专业代理：测试架构师、测试调试器、迁移规划器
- 55个测试模板：认证、CRUD、结账、搜索、表单、仪表板、设置、入门引导、通知、API、无障碍
- 2个MCP服务器（TypeScript）：TestRail和BrowserStack集成
- 智能钩子：自动验证测试质量、自动检测Playwright项目
- 6份参考文档：黄金法则、定位器、断言、fixture、常见陷阱、不稳定测试
- 迁移指南：Cypress和Selenium映射表
集成设置
TestRail（可选）
bash
export TESTRAIL_URL=https://your-instance.testrail.io
export TESTRAIL_USER=your@email.com
export TESTRAILAPIKEY=your-api-key
BrowserStack（可选）
bash
export BROWSERSTACK_USERNAME=your-username
export BROWSERSTACKACCESSKEY=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获取完整模板索引。
