playwright-pro

Overview

Playwright automates Chromium, Firefox, and WebKit with a modern async API, built-in waiting, and first-class test runner integration. Its killer feature is auto-waiting: actions wait for elements to be actionable, which eliminates most flakiness that plagues browser automation. This skill covers writing Playwright automation that's fast and reliable.

When to use

• Writing end-to-end tests for web applications
• Automating browser workflows (form filling, data extraction from JS sites)
• Testing across Chromium, Firefox, and WebKit
• Debugging flaky browser tests
• Generating PDFs/screenshots or mocking network responses

Core concepts

Auto-waiting beats sleep. Playwright actions (click, fill, select) automatically wait for the element to be attached, visible, stable, and receiving events. Never use fixed sleep() — use explicit waits (waitForSelector, expect(...).toBeVisible()) tied to actual conditions. Flaky tests are almost always missing waits in disguise.

Locators over selectors. Prefer user-facing locators — getByRole('button', { name: 'Submit' }), getByLabel, getByText — over CSS/XPath. They mirror how users find elements, survive most refactors, and enforce accessibility (if you can't find it by role, screen readers can't either). Reserve CSS for layout-specific cases.

Isolated contexts. Each test gets a fresh browser context (cookies, storage, sessions isolated) — fast and parallelizable, unlike fresh browser instances. Share authenticated state via storage-state files: log in once, save state, reuse across tests — cutting minutes off suites.

Network control. Route interception mocks APIs (page.route → fulfill with fixtures) for deterministic tests independent of backends; request inspection asserts what the app actually sent. Use mocking for speed and stability, but keep a subset of tests hitting real backends to catch integration drift.

Trace viewer for debugging. On failure, capture traces (screenshots, DOM snapshots, network, console per action) — the trace viewer replays exactly what happened. Configure tracing to retain-on-failure; debugging from a trace beats re-running and hoping.

Practical workflow

1. Structure tests by user journey (not by page object ceremony): arrange → act → assert, with test data seeded via API (faster than UI setup) where possible.
2. Write with locators: roles, labels, and text first; add data- testid attributes for elements with no good user-facing handle.
3. Handle the async reality: await every action, assert with auto-retrying expect (not manual polling), and wait for network idle or specific responses after actions that trigger requests.
4. Isolate and parallelize: fresh context per test, storage-state for auth, workers for parallelism — keep suites under minutes, not hours.
5. Debug with traces: reproduce locally with --headed --debug, inspect the trace timeline for the exact failing action and app state.
6. Keep the suite healthy: quarantine genuinely flaky tests with an owner and deadline (never normalize red), and delete tests that assert nothing meaningful.

Common pitfalls

• Fixed sleeps — waitForTimeout(3000) is slow when unnecessary and flaky when insufficient; wait on conditions instead.
• Testing implementation details — asserting on CSS classes or internal state instead of user-visible outcomes; refactors break the suite.
• Shared state between tests — order-dependent tests that pass alone and fail together; isolate via fresh contexts.
• Over-mocking — a suite that mocks everything tests the mocks; balance with real-integration coverage.
• Ignoring the other browsers — Chromium-only testing misses Firefox/WebKit quirks; run the matrix in CI at least for critical paths.
• Screenshots as assertions — pixel comparisons are brittle across environments; assert structure and key visuals, not exact pixels (except dedicated visual-regression setups with controlled baselines).