playwright

name	playwright
description	Write, run, and maintain reliable end-to-end tests with Playwright. Use for test generation, CI integration, trace debugging, and cross-browser validation.
disable-model-invocation	true

Playwright Test Engineering

Current Versions (Verify Before Use)

npx playwright --version

Check Playwright releases for the latest version.

Core Principles

1. Tests should be deterministic. No random data, no time-based assertions, no shared state.
2. Prefer user-visible selectors. Use getByRole, getByText, getByLabel over CSS selectors.
3. One assertion per test. Test one thing. If it fails, you know exactly what broke.
4. Traces are for debugging, not primary detection. A failing test should explain itself; traces help when it doesn't.
5. 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

Official Resources

• Playwright docs
• Best practices
• API reference
• Trace viewer
• CI configuration