playwright-pro

# 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

```bash
# 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

1. `getByRole()` over CSS/XPath — resilient to markup changes
2. Never `page.waitForTimeout()` — use web-first assertions
3. `expect(locator)` auto-retries; `expect(await locator.textContent())` does not
4. Isolate every test — no shared state between tests
5. `baseURL` in config — zero hardcoded URLs
6. Retries: `2` in CI, `0` locally
7. Traces: `'on-first-retry'` — rich debugging without slowdown
8. Fixtures over globals — `test.extend()` for shared state
9. One behavior per test — multiple related assertions are fine
10. 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)
```bash
export TESTRAIL_URL="https://your-instance.testrail.io"
export TESTRAIL_USER="your@email.com"
export TESTRAIL_API_KEY="your-api-key"
```

### BrowserStack (Optional)
```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.

{
  "format": "aiskill/v1",
  "skill": {
    "name": "playwright-pro",
    "slug": "playwright-pw",
    "version": "1.0.0",
    "description": "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.",
    "category": "Development",
    "tags": [
      "testing",
      "agents",
      "automation"
    ],
    "platforms": [
      "chatgpt",
      "claude-code",
      "cursor"
    ],
    "tested_environment": "Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and compatible agents",
    "license": "MIT"
  },
  "prompts": {
    "system": "# Playwright Pro\r\n\r\nProduction-grade Playwright testing toolkit for AI coding agents.\r\n\r\n## Available Commands\r\n\r\nWhen installed as a Claude Code plugin, these are available as `/pw:` commands:\r\n\r\n| Command | What it does |\r\n|---|---|\r\n| `/pw:pw-init` | Set up Playwright — detects framework, generates config, CI, first test |\r\n| `/pw:generate <spec>` | Generate tests from user story, URL, or component |\r\n| `/pw:pw-review` | Review tests for anti-patterns and coverage gaps |\r\n| `/pw:fix <test>` | Diagnose and fix failing or flaky tests |\r\n| `/pw:migrate` | Migrate from Cypress or Selenium to Playwright |\r\n| `/pw:coverage` | Analyze what's tested vs. what's missing |\r\n| `/pw:testrail` | Sync with TestRail — read cases, push results |\r\n| `/pw:browserstack` | Run on BrowserStack, pull cross-browser reports |\r\n| `/pw:report` | Generate test report in your preferred format |\r\n\r\n## Quick Start Workflow\r\n\r\nThe recommended sequence for most projects:\r\n\r\n```\r\n1. /pw:pw-init          → scaffolds config, CI pipeline, and a first smoke test\r\n2. /pw:generate      → generates tests from your spec or URL\r\n3. /pw:pw-review        → validates quality and flags anti-patterns      ← always run after generate\r\n4. /pw:fix <test>    → diagnoses and repairs any failing/flaky tests  ← run when CI turns red\r\n```\r\n\r\n**Validation checkpoints:**\r\n- After `/pw:generate` — always run `/pw:pw-review` before committing; it catches locator anti-patterns and missing assertions automatically.\r\n- After `/pw:fix` — re-run the full suite locally (`npx playwright test`) to confirm the fix doesn't introduce regressions.\r\n- After `/pw:migrate` — run `/pw:coverage` to confirm parity with the old suite before decommissioning Cypress/Selenium tests.\r\n\r\n### Example: Generate → Review → Fix\r\n\r\n```bash\r\n# 1. Generate tests from a user story\r\n/pw:generate \"As a user I can log in with email and password\"\r\n\r\n# Generated: tests/auth/login.spec.ts\r\n# → Playwright Pro creates the file using the auth template.\r\n\r\n# 2. Review the generated tests\r\n/pw:pw-review tests/auth/login.spec.ts\r\n\r\n# → Flags: one test used page.locator('input[type=password]') — suggests getByLabel('Password')\r\n# → Fix applied automatically.\r\n\r\n# 3. Run locally to confirm\r\nnpx playwright test tests/auth/login.spec.ts --headed\r\n\r\n# 4. If a test is flaky in CI, diagnose it\r\n/pw:fix tests/auth/login.spec.ts\r\n# → Identifies missing web-first assertion; replaces waitForTimeout(2000) with expect(locator).toBeVisible()\r\n```\r\n\r\n## Golden Rules\r\n\r\n1. `getByRole()` over CSS/XPath — resilient to markup changes\r\n2. Never `page.waitForTimeout()` — use web-first assertions\r\n3. `expect(locator)` auto-retries; `expect(await locator.textContent())` does not\r\n4. Isolate every test — no shared state between tests\r\n5. `baseURL` in config — zero hardcoded URLs\r\n6. Retries: `2` in CI, `0` locally\r\n7. Traces: `'on-first-retry'` — rich debugging without slowdown\r\n8. Fixtures over globals — `test.extend()` for shared state\r\n9. One behavior per test — multiple related assertions are fine\r\n10. Mock external services only — never mock your own app\r\n\r\n## Locator Priority\r\n\r\n```\r\n1. getByRole()        — buttons, links, headings, form elements\r\n2. getByLabel()       — form fields with labels\r\n3. getByText()        — non-interactive text\r\n4. getByPlaceholder() — inputs with placeholder\r\n5. getByTestId()      — when no semantic option exists\r\n6. page.locator()     — CSS/XPath as last resort\r\n```\r\n\r\n## What's Included\r\n\r\n- **9 skills** with detailed step-by-step instructions\r\n- **3 specialized agents**: test-architect, test-debugger, migration-planner\r\n- **55 test templates**: auth, CRUD, checkout, search, forms, dashboard, settings, onboarding, notifications, API, accessibility\r\n- **2 MCP servers** (TypeScript): TestRail and BrowserStack integrations *(optional — not auto-registered; see Integration Setup)*\r\n- **Smart hooks**: auto-validate test quality, auto-detect Playwright projects\r\n- **6 reference docs**: golden rules, locators, assertions, fixtures, pitfalls, flaky tests\r\n- **Migration guides**: Cypress and Selenium mapping tables\r\n\r\n## Integration Setup\r\n\r\n> **Not auto-registered (issue #978).** The TestRail and BrowserStack MCP servers\r\n> are no longer declared in the plugin's `.mcp.json` (they failed to connect for\r\n> every user — no bundled `node_modules`). Exporting the env vars below is not\r\n> enough: `/pw:testrail` / `/pw:browserstack` fail with \"tool not found\" until you\r\n> enable the server manually (`cd integrations/<name>-mcp && npm install`, then\r\n> register it in your own user/project MCP config). See `CLAUDE.md` → Integrations.\r\n\r\n### TestRail (Optional)\r\n```bash\r\nexport TESTRAIL_URL=\"https://your-instance.testrail.io\"\r\nexport TESTRAIL_USER=\"your@email.com\"\r\nexport TESTRAIL_API_KEY=\"your-api-key\"\r\n```\r\n\r\n### BrowserStack (Optional)\r\n```bash\r\nexport BROWSERSTACK_USERNAME=\"your-username\"\r\nexport BROWSERSTACK_ACCESS_KEY=\"your-access-key\"\r\n```\r\n\r\n## Quick Reference\r\n\r\nSee `reference/` directory for:\r\n- `golden-rules.md` — The 10 non-negotiable rules\r\n- `locators.md` — Complete locator priority with cheat sheet\r\n- `assertions.md` — Web-first assertions reference\r\n- `fixtures.md` — Custom fixtures and storageState patterns\r\n- `common-pitfalls.md` — Top 10 mistakes and fixes\r\n- `flaky-tests.md` — Diagnosis commands and quick fixes\r\n\r\nSee `templates/README.md` for the full template index.",
    "user_template": ""
  },
  "variables": [],
  "install": {
    "steps": [
      {
        "title": "Download & unzip",
        "detail": "Download the .zip package from SkillVault and unzip it. The playwright-pw/ folder contains SKILL.md plus any companion scripts, references and assets."
      },
      {
        "title": "Copy into your agent skills directory",
        "detail": "Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code), .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or reload the session."
      },
      {
        "title": "Use it",
        "detail": "Describe the task in natural language; the agent loads the skill automatically when the request matches the skill description."
      }
    ]
  },
  "usage": {
    "steps": []
  },
  "metadata": {
    "author": "SkillVault",
    "source": "https://skillvault.top/skills/playwright-pw",
    "exported_at": "2026-11-03T07:43:59.484Z"
  }
}

format: aiskill/v1
skill:
  name: playwright-pro
  slug: playwright-pw
  version: 1.0.0
  description: >-
    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.
  category: Development
  tags:
    - testing
    - agents
    - automation
  platforms:
    - chatgpt
    - claude-code
    - cursor
  tested_environment: >-
    Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and
    compatible agents
  license: MIT
prompts:
  system: "# Playwright Pro\r\n\r\nProduction-grade Playwright testing toolkit for AI coding agents.\r\n\r\n## Available Commands\r\n\r\nWhen installed as a Claude Code plugin, these are available as `/pw:` commands:\r\n\r\n| Command | What it does |\r\n|---|---|\r\n| `/pw:pw-init` | Set up Playwright — detects framework, generates config, CI, first test |\r\n| `/pw:generate <spec>` | Generate tests from user story, URL, or component |\r\n| `/pw:pw-review` | Review tests for anti-patterns and coverage gaps |\r\n| `/pw:fix <test>` | Diagnose and fix failing or flaky tests |\r\n| `/pw:migrate` | Migrate from Cypress or Selenium to Playwright |\r\n| `/pw:coverage` | Analyze what's tested vs. what's missing |\r\n| `/pw:testrail` | Sync with TestRail — read cases, push results |\r\n| `/pw:browserstack` | Run on BrowserStack, pull cross-browser reports |\r\n| `/pw:report` | Generate test report in your preferred format |\r\n\r\n## Quick Start Workflow\r\n\r\nThe recommended sequence for most projects:\r\n\r\n```\r\n1. /pw:pw-init          → scaffolds config, CI pipeline, and a first smoke test\r\n2. /pw:generate      → generates tests from your spec or URL\r\n3. /pw:pw-review        → validates quality and flags anti-patterns      ← always run after generate\r\n4. /pw:fix <test>    → diagnoses and repairs any failing/flaky tests  ← run when CI turns red\r\n```\r\n\r\n**Validation checkpoints:**\r\n- After `/pw:generate` — always run `/pw:pw-review` before committing; it catches locator anti-patterns and missing assertions automatically.\r\n- After `/pw:fix` — re-run the full suite locally (`npx playwright test`) to confirm the fix doesn't introduce regressions.\r\n- After `/pw:migrate` — run `/pw:coverage` to confirm parity with the old suite before decommissioning Cypress/Selenium tests.\r\n\r\n### Example: Generate → Review → Fix\r\n\r\n```bash\r\n# 1. Generate tests from a user story\r\n/pw:generate \"As a user I can log in with email and password\"\r\n\r\n# Generated: tests/auth/login.spec.ts\r\n# → Playwright Pro creates the file using the auth template.\r\n\r\n# 2. Review the generated tests\r\n/pw:pw-review tests/auth/login.spec.ts\r\n\r\n# → Flags: one test used page.locator('input[type=password]') — suggests getByLabel('Password')\r\n# → Fix applied automatically.\r\n\r\n# 3. Run locally to confirm\r\nnpx playwright test tests/auth/login.spec.ts --headed\r\n\r\n# 4. If a test is flaky in CI, diagnose it\r\n/pw:fix tests/auth/login.spec.ts\r\n# → Identifies missing web-first assertion; replaces waitForTimeout(2000) with expect(locator).toBeVisible()\r\n```\r\n\r\n## Golden Rules\r\n\r\n1. `getByRole()` over CSS/XPath — resilient to markup changes\r\n2. Never `page.waitForTimeout()` — use web-first assertions\r\n3. `expect(locator)` auto-retries; `expect(await locator.textContent())` does not\r\n4. Isolate every test — no shared state between tests\r\n5. `baseURL` in config — zero hardcoded URLs\r\n6. Retries: `2` in CI, `0` locally\r\n7. Traces: `'on-first-retry'` — rich debugging without slowdown\r\n8. Fixtures over globals — `test.extend()` for shared state\r\n9. One behavior per test — multiple related assertions are fine\r\n10. Mock external services only — never mock your own app\r\n\r\n## Locator Priority\r\n\r\n```\r\n1. getByRole()        — buttons, links, headings, form elements\r\n2. getByLabel()       — form fields with labels\r\n3. getByText()        — non-interactive text\r\n4. getByPlaceholder() — inputs with placeholder\r\n5. getByTestId()      — when no semantic option exists\r\n6. page.locator()     — CSS/XPath as last resort\r\n```\r\n\r\n## What's Included\r\n\r\n- **9 skills** with detailed step-by-step instructions\r\n- **3 specialized agents**: test-architect, test-debugger, migration-planner\r\n- **55 test templates**: auth, CRUD, checkout, search, forms, dashboard, settings, onboarding, notifications, API, accessibility\r\n- **2 MCP servers** (TypeScript): TestRail and BrowserStack integrations *(optional — not auto-registered; see Integration Setup)*\r\n- **Smart hooks**: auto-validate test quality, auto-detect Playwright projects\r\n- **6 reference docs**: golden rules, locators, assertions, fixtures, pitfalls, flaky tests\r\n- **Migration guides**: Cypress and Selenium mapping tables\r\n\r\n## Integration Setup\r\n\r\n> **Not auto-registered (issue #978).** The TestRail and BrowserStack MCP servers\r\n> are no longer declared in the plugin's `.mcp.json` (they failed to connect for\r\n> every user — no bundled `node_modules`). Exporting the env vars below is not\r\n> enough: `/pw:testrail` / `/pw:browserstack` fail with \"tool not found\" until you\r\n> enable the server manually (`cd integrations/<name>-mcp && npm install`, then\r\n> register it in your own user/project MCP config). See `CLAUDE.md` → Integrations.\r\n\r\n### TestRail (Optional)\r\n```bash\r\nexport TESTRAIL_URL=\"https://your-instance.testrail.io\"\r\nexport TESTRAIL_USER=\"your@email.com\"\r\nexport TESTRAIL_API_KEY=\"your-api-key\"\r\n```\r\n\r\n### BrowserStack (Optional)\r\n```bash\r\nexport BROWSERSTACK_USERNAME=\"your-username\"\r\nexport BROWSERSTACK_ACCESS_KEY=\"your-access-key\"\r\n```\r\n\r\n## Quick Reference\r\n\r\nSee `reference/` directory for:\r\n- `golden-rules.md` — The 10 non-negotiable rules\r\n- `locators.md` — Complete locator priority with cheat sheet\r\n- `assertions.md` — Web-first assertions reference\r\n- `fixtures.md` — Custom fixtures and storageState patterns\r\n- `common-pitfalls.md` — Top 10 mistakes and fixes\r\n- `flaky-tests.md` — Diagnosis commands and quick fixes\r\n\r\nSee `templates/README.md` for the full template index."
  user_template: ""
variables: []
install:
  steps:
    - title: Download & unzip
      detail: >-
        Download the .zip package from SkillVault and unzip it. The playwright-pw/ folder contains
        SKILL.md plus any companion scripts, references and assets.
    - title: Copy into your agent skills directory
      detail: >-
        Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code),
        .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or
        reload the session.
    - title: Use it
      detail: >-
        Describe the task in natural language; the agent loads the skill automatically when the
        request matches the skill description.
usage:
  steps: []
metadata:
  author: SkillVault
  source: https://skillvault.top/skills/playwright-pw
  exported_at: "2026-11-03T07:43:59.484Z"