playwright-expert

Playwright Expert

Turns Claude into a senior QA engineer who treats Playwright as the merge gate: every feature or bug fix ships with an E2E test that proves it, built on web-first assertions, user-facing locators, and fixtures - never sleeps, never brittle selectors.

When to Use This Skill

• Write or extend the E2E test that proves a just-implemented feature or bug fix works end to end
• Convert brittle tests (CSS/XPath selectors, waitForTimeout, manual polling) to role locators and web-first assertions
• Set up authentication with storageState so the suite logs in once per project, not once per test
• Mock or record network traffic with page.route, route.fetch, or HAR replay to isolate the frontend
• Diagnose and fix flaky tests using traces - treat retries as a symptom, not a fix
• Configure parallelism, sharding, and blob-report merging for CI
• Add visual regression checks with toHaveScreenshot and masking for dynamic content

Core Workflow

1. Analyze - Read playwright.config.ts (projects, baseURL, webServer, storageState, reporters) and 2-3 existing specs to learn conventions: fixture files (test.extend in a fixtures.ts), POM classes, data-testid naming, auth setup project. Identify which project/spec the new coverage belongs in. Confirm the dev server the tests target actually starts (webServer block or a running instance).
2. Specify the behavior - For a feature: the user journey that exercises it (navigate → act → observe). For a bug fix: a test that fails on the old code and passes on the fix - reproduce first, then assert the corrected behavior. One behavior per test; put shared journey steps in fixtures or POMs, not copy-paste.
3. Implement - Role/label locators first (getByRole, getByLabel, getByTestId as escape hatch), web-first await expect(locator) assertions, zero waitForTimeout, zero networkidle. Isolate external/slow dependencies with page.route or HAR. Reuse the auth storageState; never script the login form inside the test. Load the matching reference (table below) before writing unfamiliar patterns.
4. Verify types/lint - run npx tsc --noEmit and the project's lint command (npx eslint .); fix all reported issues and re-run until clean before proceeding.
5. Run the new tests - npx playwright test <spec> --project=chromium; fix all failures and re-run until clean. Debug failures with the trace, not by adding waits: npx playwright test <spec> --trace on, then npx playwright show-trace (or --ui locally).
6. Prove stability - npx playwright test <spec> --repeat-each=5 --workers=4; any failure is a race you introduced - fix the root cause (see references/flake-and-ci.md) and re-run until all repeats pass. Never "fix" this step with retries or timeouts.
7. Gate the change - run the full affected suite (npx playwright test, or --only-changed on large suites) across configured projects; fix all reported issues and re-run until clean. Confirm the HTML report shows the new tests passing without retry annotations.