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 |
/pw:pw-init |
Set up Playwright — detects framework, generates config, CI, first test |
/pw:generate <spec> |
Generate tests from user story, URL, or component |
/pw: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:
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
Validation checkpoints:
- After
/pw:generate — always run /pw: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
# 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()
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
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
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 (optional — not auto-registered; see Integration Setup)
- 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
Not auto-registered (issue #978). The TestRail and BrowserStack MCP servers
are no longer declared in the plugin's .mcp.json (they failed to connect for
every user — no bundled node_modules). Exporting the env vars below is not
enough: /pw:testrail / /pw:browserstack fail with "tool not found" until you
enable the server manually (cd integrations/<name>-mcp && npm install, then
register it in your own user/project MCP config). See CLAUDE.md → Integrations.
TestRail (Optional)
export TESTRAIL_URL="https://your-instance.testrail.io"
export TESTRAIL_USER="your@email.com"
export TESTRAIL_API_KEY="your-api-key"
BrowserStack (Optional)
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.
1---2name: "playwright-pro"3description: "Production-grade Playwright testing toolkit. Use when the user mentions Playwright tests, end-to-end testing, browser automation, fixing flaky tests, test migration, CI/CD testing, or test suites. Generate tests, fix flaky failures, migrate from Cypress/Selenium, sync with TestRail, run on BrowserStack. 55 templates, 3 agents, smart reporting."4disable-model-invocation: true # skill-optimizer5metadata:6 source: https://skillmd.com/skills/slipcast-dev/playwright-pro7---89# Playwright Pro1011Production-grade Playwright testing toolkit for AI coding agents.1213## Available Commands1415When installed as a Claude Code plugin, these are available as `/pw:` commands:1617| Command | What it does |18|---|---|19| `/pw:pw-init` | Set up Playwright — detects framework, generates config, CI, first test |20| `/pw:generate <spec>` | Generate tests from user story, URL, or component |21| `/pw:pw-review` | Review tests for anti-patterns and coverage gaps |22| `/pw:fix <test>` | Diagnose and fix failing or flaky tests |23| `/pw:migrate` | Migrate from Cypress or Selenium to Playwright |24| `/pw:coverage` | Analyze what's tested vs. what's missing |25| `/pw:testrail` | Sync with TestRail — read cases, push results |26| `/pw:browserstack` | Run on BrowserStack, pull cross-browser reports |27| `/pw:report` | Generate test report in your preferred format |2829## Quick Start Workflow3031The recommended sequence for most projects:3233```341. /pw:pw-init → scaffolds config, CI pipeline, and a first smoke test352. /pw:generate → generates tests from your spec or URL363. /pw:pw-review → validates quality and flags anti-patterns ← always run after generate374. /pw:fix <test> → diagnoses and repairs any failing/flaky tests ← run when CI turns red38```3940**Validation checkpoints:**41- After `/pw:generate` — always run `/pw:pw-review` before committing; it catches locator anti-patterns and missing assertions automatically.42- After `/pw:fix` — re-run the full suite locally (`npx playwright test`) to confirm the fix doesn't introduce regressions.43- After `/pw:migrate` — run `/pw:coverage` to confirm parity with the old suite before decommissioning Cypress/Selenium tests.4445### Example: Generate → Review → Fix4647```bash48# 1. Generate tests from a user story49/pw:generate "As a user I can log in with email and password"5051# Generated: tests/auth/login.spec.ts52# → Playwright Pro creates the file using the auth template.5354# 2. Review the generated tests55/pw:pw-review tests/auth/login.spec.ts5657# → Flags: one test used page.locator('input[type=password]') — suggests getByLabel('Password')58# → Fix applied automatically.5960# 3. Run locally to confirm61npx playwright test tests/auth/login.spec.ts --headed6263# 4. If a test is flaky in CI, diagnose it64/pw:fix tests/auth/login.spec.ts65# → Identifies missing web-first assertion; replaces waitForTimeout(2000) with expect(locator).toBeVisible()66```6768## Golden Rules69701. `getByRole()` over CSS/XPath — resilient to markup changes712. Never `page.waitForTimeout()` — use web-first assertions723. `expect(locator)` auto-retries; `expect(await locator.textContent())` does not734. Isolate every test — no shared state between tests745. `baseURL` in config — zero hardcoded URLs756. Retries: `2` in CI, `0` locally767. Traces: `'on-first-retry'` — rich debugging without slowdown778. Fixtures over globals — `test.extend()` for shared state789. One behavior per test — multiple related assertions are fine7910. Mock external services only — never mock your own app8081## Locator Priority8283```841. getByRole() — buttons, links, headings, form elements852. getByLabel() — form fields with labels863. getByText() — non-interactive text874. getByPlaceholder() — inputs with placeholder885. getByTestId() — when no semantic option exists896. page.locator() — CSS/XPath as last resort90```9192## What's Included9394- **9 skills** with detailed step-by-step instructions95- **3 specialized agents**: test-architect, test-debugger, migration-planner96- **55 test templates**: auth, CRUD, checkout, search, forms, dashboard, settings, onboarding, notifications, API, accessibility97- **2 MCP servers** (TypeScript): TestRail and BrowserStack integrations *(optional — not auto-registered; see Integration Setup)*98- **Smart hooks**: auto-validate test quality, auto-detect Playwright projects99- **6 reference docs**: golden rules, locators, assertions, fixtures, pitfalls, flaky tests100- **Migration guides**: Cypress and Selenium mapping tables101102## Integration Setup103104> **Not auto-registered (issue #978).** The TestRail and BrowserStack MCP servers105> are no longer declared in the plugin's `.mcp.json` (they failed to connect for106> every user — no bundled `node_modules`). Exporting the env vars below is not107> enough: `/pw:testrail` / `/pw:browserstack` fail with "tool not found" until you108> enable the server manually (`cd integrations/<name>-mcp && npm install`, then109> register it in your own user/project MCP config). See `CLAUDE.md` → Integrations.110111### TestRail (Optional)112```bash113export TESTRAIL_URL="https://your-instance.testrail.io"114export TESTRAIL_USER="your@email.com"115export TESTRAIL_API_KEY="your-api-key"116```117118### BrowserStack (Optional)119```bash120export BROWSERSTACK_USERNAME="your-username"121export BROWSERSTACK_ACCESS_KEY="your-access-key"122```123124## Quick Reference125126See `reference/` directory for:127- `golden-rules.md` — The 10 non-negotiable rules128- `locators.md` — Complete locator priority with cheat sheet129- `assertions.md` — Web-first assertions reference130- `fixtures.md` — Custom fixtures and storageState patterns131- `common-pitfalls.md` — Top 10 mistakes and fixes132- `flaky-tests.md` — Diagnosis commands and quick fixes133134See `templates/README.md` for the full template index.