Playwright Pro

Production-grade Playwright testing toolkit for AI coding agents.

Note: This skill may create or modify files in your project. It will ask before writing.

Sub-commands

/playwright-pro with no argument shows this overview. With a sub-command as its first argument, read skills/<sub-command>/SKILL.md from this skill's directory and follow it, passing the remaining arguments. Sub-commands: fix, generate, init, migrate, report, review.

Quick Start Workflow

The recommended sequence for most projects:

1. /playwright-pro init          -> scaffolds config, CI pipeline, and a first smoke test
2. /playwright-pro generate      -> generates tests from your spec or URL
3. /playwright-pro review        -> validates quality and flags anti-patterns      <- always run after generate
4. /playwright-pro fix <test>    -> diagnoses and repairs any failing/flaky tests  <- run when CI turns red

Validation checkpoints:

• After /playwright-pro generate -- always run /playwright-pro review before committing
• After /playwright-pro fix -- re-run the full suite locally (npx playwright test)
• After /playwright-pro migrate -- run both suites and compare test counts and results before decommissioning old tests

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

• 6 sub-commands with detailed step-by-step instructions
• 55 test templates: auth, CRUD, checkout, search, forms, dashboard, settings, onboarding, notifications, API, accessibility
• 6 reference docs: golden rules, locators, assertions, fixtures, pitfalls, flaky tests
• Migration guides: Cypress and Selenium mapping tables

Quick Reference

See references/ 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.