playwright

---

name: playwright description: End-to-end testing framework for modern web apps -- browser automation, visual regression, and cross-browser testing layer: domain category: testing triggers:

• "playwright test"
• "e2e test"
• "browser test"
• "visual regression"
• "cross-browser test" inputs:
• target: Page, component, or user flow to test
• browsers: chromium | firefox | webkit | all (default: chromium) outputs:
• testFiles: Playwright test specs
• testResults: Pass/fail with traces and screenshots linksTo: [test, test-ui, testing-patterns, chrome-devtools] linkedFrom: [test, ship] riskLevel: low memoryReadPolicy: selective memoryWritePolicy: selective sideEffects:
• Creates test files and generates screenshots/trace files
• Launches browser processes

---

Playwright

End-to-end testing framework for modern web apps. Supports Chromium, Firefox, and WebKit with a single API. Auto-waits for elements, intercepts network, and captures traces for debugging.

When to Use

• Testing critical user flows across real browsers
• Visual regression testing with screenshot comparison
• Network mocking for deterministic API responses
• Component testing with @playwright/experimental-ct-react

Key Patterns

Page Object Model

Encapsulate page interactions in classes. Tests call loginPage.signIn(user) instead of raw selectors. Keeps tests readable and selectors maintainable in one place.

Locator Strategies

Prefer resilient locators: getByRole > getByLabel > getByText > getByTestId. Avoid CSS/XPath -- they break on DOM changes.

Assertions with Auto-Retry

Use expect(locator) assertions -- they auto-retry until timeout. await expect(page.getByText('Success')).toBeVisible(). Never use waitForTimeout.

Visual Comparison

await expect(page).toHaveScreenshot('name.png') captures and diffs screenshots. Use maxDiffPixelRatio for tolerance. Update baselines with --update-snapshots.

Network Mocking

await page.route('**/api/users', route => route.fulfill({ json: mockData })) intercepts requests. Use route.abort() to simulate failures.

Multi-Browser Testing

Configure projects in playwright.config.ts to run across browsers. Each project specifies a browser and viewport. CI runs all; local dev targets one.

Fixtures and Hooks

Use test.beforeEach for shared setup. Custom fixtures extend test for reusable context like authenticated pages or seeded databases.

Parallel Execution

Tests run in parallel by default. Use test.describe.serial only when order matters. Isolate state to avoid flakes.

Trace Viewer

npx playwright show-trace trace.zip replays execution with DOM snapshots, network log, and console. Enable with trace: 'on-first-retry'.

Component Testing

@playwright/experimental-ct-react mounts components in a real browser for testing interactive elements needing real DOM, CSS, and browser APIs.

Anti-Patterns

1. waitForTimeout over locator assertions -- Flaky. Use auto-retrying expect.
2. CSS/XPath over semantic locators -- Brittle. Prefer getByRole, getByTestId.
3. Shared mutable state -- Tests must be independent. Use beforeEach for setup.
4. Testing third-party UI -- Mock OAuth popups and captchas at the network layer.
5. Skipping webServer config -- Let Playwright manage your dev server for reliable CI.
6. Giant test files -- Split by feature. One describe per user flow.