playwright-pro

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Playwright Pro

Production-grade Playwright testing toolkit for AI coding agents.

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

Available Commands

可用命令

When installed as a Claude Code plugin, these are available as

/pw:

commands:

Command	What it does
`/pw:init`	Set up Playwright — detects framework, generates config, CI, first test
`/pw:generate <spec>`	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

当作为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`	以你偏好的格式生成测试报告

Quick Start Workflow

快速开始流程

The recommended sequence for most projects:

1. /pw:init          → scaffolds config, CI pipeline, and a first smoke test
2. /pw:generate      → generates tests from your spec or URL
3. /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

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.

大多数项目推荐遵循以下步骤：

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测试。

Example: Generate → Review → Fix

示例：生成 → 检查 → 修复

bash

undefined

bash

undefined

1. Generate tests from a user story

1. 根据用户故事生成测试用例

/pw:generate "As a user I can log in with email and password"

/pw:generate "用户可使用邮箱和密码登录"

Generated: tests/auth/login.spec.ts

生成文件：tests/auth/login.spec.ts

→ Playwright Pro creates the file using the auth template.

→ Playwright Pro 使用认证模板创建该文件。

2. Review the generated tests

2. 检查生成的测试用例

/pw:review tests/auth/login.spec.ts

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

→ 标记问题：其中一个测试使用了page.locator('input[type=password]')——建议替换为getByLabel('Password')

→ Fix applied automatically.

→ 自动应用修复。

3. Run locally to confirm

3. 在本地运行确认

npx playwright test tests/auth/login.spec.ts --headed

4. If a test is flaky in CI, diagnose it

4. 如果CI中测试不稳定，进行诊断

/pw:fix tests/auth/login.spec.ts

→ Identifies missing web-first assertion; replaces waitForTimeout(2000) with expect(locator).toBeVisible()

→ 识别缺失的Web优先断言；将waitForTimeout(2000)替换为expect(locator).toBeVisible()

undefined

undefined

Golden Rules

黄金准则

```
getByRole()
```
over CSS/XPath — resilient to markup changes
Never
```
page.waitForTimeout()
```
— use web-first assertions

expect(locator)

auto-retries;

expect(await locator.textContent())

does not

Isolate every test — no shared state between tests
```
baseURL
```
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

使用
```
getByRole()
```
而非CSS/XPath——对标记变更具备更强适应性
绝不使用
```
page.waitForTimeout()
```
——改用Web优先断言

expect(locator)

会自动重试；

expect(await locator.textContent())

不会

每个测试相互隔离——测试间无共享状态
在配置中设置
```
baseURL
```
——避免硬编码URL
重试次数：CI环境设为
```
2
```
，本地环境设为
```
0
```
追踪记录：设为
```
'on-first-retry'
```
——无需额外性能开销即可实现丰富调试
使用Fixtures而非全局变量——通过
```
test.extend()
```
管理共享状态
每个测试对应一个行为——可包含多个相关断言
仅模拟外部服务——绝不模拟自身应用

Locator Priority

定位器优先级

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

1. getByRole()        — 按钮、链接、标题、表单元素
2. getByLabel()       — 带标签的表单字段
3. getByText()        — 非交互式文本
4. getByPlaceholder() — 带占位符的输入框
5. getByTestId()      — 无语义化选项时使用
6. page.locator()     — CSS/XPath作为最后选择

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

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

Integration Setup

集成设置

TestRail (Optional)

TestRail（可选）

bash

export TESTRAIL_URL="https://your-instance.testrail.io"
export TESTRAIL_USER="your@email.com"
export TESTRAIL_API_KEY="your-api-key"

bash

export TESTRAIL_URL="https://your-instance.testrail.io"
export TESTRAIL_USER="your@email.com"
export TESTRAIL_API_KEY="your-api-key"

BrowserStack (Optional)

BrowserStack（可选）

bash

export BROWSERSTACK_USERNAME="your-username"
export BROWSERSTACK_ACCESS_KEY="your-access-key"

bash

export BROWSERSTACK_USERNAME="your-username"
export BROWSERSTACK_ACCESS_KEY="your-access-key"

Quick Reference

快速参考

See

reference/

directory for:

```
golden-rules.md
```
— The 10 non-negotiable rules
```
locators.md
```
— Complete locator priority with cheat sheet
```
assertions.md
```
— Web-first assertions reference
```
fixtures.md
```
— Custom fixtures and storageState patterns
```
common-pitfalls.md
```
— Top 10 mistakes and fixes
```
flaky-tests.md
```
— Diagnosis commands and quick fixes

See

templates/README.md

for the full template index.

查看

reference/

目录获取：

```
golden-rules.md
```
— 10条不可违背的准则
```
locators.md
```
— 完整定位器优先级及速查表
```
assertions.md
```
— Web优先断言参考
```
fixtures.md
```
— 自定义Fixtures与storageState模式
```
common-pitfalls.md
```
— 十大常见错误及修复方案
```
flaky-tests.md
```
— 诊断命令及快速修复方法

查看

templates/README.md

获取完整模板索引。