Skill: alirezarezvani/cs-playwright-pro (version 1.0.0)

--- name: "playwright-pro" 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." --- # 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: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 | ## 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. ### 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: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 - **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) ```bash export TESTRAIL_URL="https://your-instance.testrail.io" export TESTRAIL_USER="[REDACTED_SECRET]" 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.

path: CLAUDE.md
content: # Playwright Pro — Agent Context

You are working in a project with the Playwright Pro plugin installed. Follow these rules for all test-related work.

## Golden Rules (Non-Negotiable)

1. **`getByRole()` over CSS/XPath** — resilient to markup changes, mirrors how users see the page
2. **Never `page.waitForTimeout()`** — use `expect(locator).toBeVisible()` or `page.waitForURL()`
3. **Web-first assertions** — `expect(locator)` auto-retries; `expect(await locator.textContent())` does not
4. **Isolate every test** — no shared state, no execution-order dependencies
5. **`baseURL` in config** — zero hardcoded URLs in tests
6. **Retries: `2` in CI, `0` locally** — surface flakiness where it matters
7. **Traces: `'on-first-retry'`** — rich debugging without CI slowdown
8. **Fixtures over globals** — share state via `test.extend()`, not module-level variables
9. **One behavior per test** — multiple related `expect()` calls are fine
10. **Mock external services only** — never mock your own app

## Locator Priority

Always use the first option that works:

```typescript
page.getByRole('button', { name: 'Submit' })        // 1. Role (default)
page.getByLabel('Email address')                     // 2. Label (form fields)
page.getByText('Welcome back')                       // 3. Text (non-interactive)
page.getByPlaceholder('Search...')                    // 4. Placeholder
page.getByAltText('Company logo')                    // 5. Alt text (images)
page.getByTitle('Close dialog')                      // 6. Title attribute
page.getByTestId('checkout-summary')                 // 7. Test ID (last semantic)
page.locator('.legacy-widget')                       // 8. CSS (last resort)
```

## How to Use This Plugin

### Generating Tests

When generating tests, always:

1. Use the `Explore` subagent to scan the project structure first
2. Check `playwright.config.ts` for `testDir`, `baseURL`, and project settings
3. Load relevant templates from `templates/` directory
4. Match the project's language (check for `tsconfig.json` → TypeScript, else JavaScript)
5. Place tests in the configured `testDir` (default: `tests/` or `e2e/`)
6. Include a descriptive test name that explains the behavior being verified

### Reviewing Tests

When reviewing, check against:

1. All 10 golden rules above
2. The anti-patterns in `skills/review/anti-patterns.md`
3. Missing edge cases (empty state, error state, loading state)
4. Proper use of fixtures for shared setup

### Fixing Flaky Tests

When fixing flaky tests:

1. Categorize first: timing, isolation, environment, or infrastructure
2. Use `npx playwright test <file> --repeat-each=10` to reproduce
3. Use `--trace=on` for every attempt
4. Apply the targeted fix from `skills/fix/flaky-taxonomy.md`

### Using Built-in Commands

Leverage Claude Code's built-in capabilities:

- **Large migrations**: Use `/batch` for parallel file-by-file conversion
- **Post-generation cleanup**: Use `/simplify` after generating a test suite
- **Debugging sessions**: Use `/debug` alongside `/pw:fix` for trace analysis
- **Code review**: Use `/review` for general code quality, `/pw:review` for Playwright-specific

### Integrations

- **TestRail**: Configured via `TESTRAIL_URL`, `TESTRAIL_USER`, `TESTRAIL_API_KEY` env vars
- **BrowserStack**: Configured via `BROWSERSTACK_USERNAME`, `BROWSERSTACK_ACCESS_KEY` env vars
- Both are optional. The plugin works fully without them.

## File Conventions

- Test files: `*.spec.ts` or `*.spec.js`
- Page objects: `*.page.ts` in a `pages/` directory
- Fixtures: `fixtures.ts` or `fixtures/` directory
- Test data: `test-data/` directory with JSON/factory files


path: hooks/detect-playwright.sh
content: #!/usr/bin/env bash
# Session start hook: detects if the project uses Playwright.
# Outputs context hint for Claude if playwright.config exists.

set -euo pipefail

# Check for Playwright config in current directory or common locations
PW_CONFIG=""
for config in playwright.config.ts playwright.config.js playwright.config.mjs; do
    if [[ -f "$config" ]]; then
        PW_CONFIG="$config"
        break
    fi
done

if [[ -z "$PW_CONFIG" ]]; then
    exit 0
fi

# Count existing test files
TEST_COUNT=$(find . -name "*.spec.ts" -o -name "*.spec.js" -o -name "*.test.ts" -o -name "*.test.js" 2>/dev/null | grep -v node_modules | wc -l | tr -d ' ')

echo "🎭 Playwright detected ($PW_CONFIG) — $TEST_COUNT test files found. Use /pw: commands for testing workflows."


path: hooks/hooks.json
content: {
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/validate-test.sh"
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/detect-playwright.sh"
          }
        ]
      }
    ]
  }
}


path: integrations/browserstack-mcp/package.json
content: {
  "name": "@pw/browserstack-mcp",
  "version": "1.0.0",
  "description": "MCP server for BrowserStack integration with Playwright Pro",
  "type": "module",
  "main": "src/index.ts",
  "scripts": {
    "start": "tsx src/index.ts",
    "build": "tsc"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.0.0"
  },
  "devDependencies": {
    "tsx": "^4.0.0",
    "typescript": "^5.0.0"
  }
}


path: integrations/browserstack-mcp/tsconfig.json
content: {
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "strict": true,
    "outDir": "dist",
    "rootDir": "src",
    "declaration": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*"]
}


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)