playwright

Default output: return only the result, blockers, and required evidence. Omit preambles, process narration, repeated context, confidence scores, and follow-up offers. Use at most five bullets unless a required artifact or schema needs more.

Playwright Test Engineering

Current Versions (Verify Before Use)

npx playwright --version

Check Playwright releases for the latest version.

Core Principles

Tests should be deterministic. No random data, no time-based assertions, no shared state.
Prefer user-visible selectors. Use getByRole, getByText, getByLabel over CSS selectors.
One assertion per test. Test one thing. If it fails, you know exactly what broke.
Traces are for debugging, not primary detection. A failing test should explain itself; traces help when it doesn't.
Parallel by default. Use fully-parallel mode. Tests must be isolated.

Test Writing Checklist

Uses semantic locators (getByRole, getByLabel, getByText)
Avoids waitForTimeout — uses explicit waits (waitForSelector, waitForResponse)
Each test has test.describe grouping
Test data is isolated (no shared accounts, no hardcoded IDs)
API calls are mocked or use test-specific data
Screenshots/traces are captured on failure

Codegen Workflow

# Generate test from user interactions
npx playwright codegen http://localhost:3000

# Run with UI mode for debugging
npx playwright test --ui

# Run with trace viewer
npx playwright test --trace on
npx playwright show-trace test-results/trace.zip

CI Integration

# .github/workflows/playwright.yml
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
  with:
    node-version: 22
- run: npm ci
- run: npx playwright install --with-deps
- run: npx playwright test
- uses: actions/upload-artifact@v4
  if: failure()
  with:
    name: playwright-report
    path: playwright-report/

Common Anti-Patterns

Anti-Pattern	Why It's Wrong	Fix
`page.click('.btn-primary')`	Brittle, no semantic meaning	`page.getByRole('button', { name: 'Submit' }).click()`
`page.waitForTimeout(1000)`	Flaky, slow	`page.waitForResponse('**/api/data')`
Shared test account	State leaks between tests	Isolate data per test
No retries in CI	Network flakes cause failures	`retries: 2` in CI
Screenshots on every run	Wastes storage	`screenshot: 'only-on-failure'`
Hardcoded URLs	Environment-specific breakage	Use `baseURL` config
No visual regression	UI changes break layout	Add `expect(page).toHaveScreenshot()`

Validation Checklist

playwright.config.ts has fullyParallel: true
retries configured for CI (2 for CI, 0 for local)
projects cover required browsers (Chromium minimum, +WebKit for Safari)
Trace configured: trace: 'on-first-retry'
globalSetup handles test data seeding if needed
testResultsDir is in .gitignore

About this skill