Playwright

Playwright Browser Automation

Use this skill to drive a real browser with Playwright: author end-to-end tests, keep selectors and tests robust, intercept and mock network traffic, run suites across parallel workers and in CI, scrape and extract data in headless mode, and check accessibility with snapshot scans. This is a tool skill for one named tool. Test strategy and framework selection belong to qa-methodology; frontend component and architecture design belong to frontend-engineering. This skill owns operating the Playwright tool itself.

Operating contract

1. Read the suite before running. Inspect playwright.config.*, projects, baseURL, webServer, workers, retries, and reporters before running anything. Never assume the test command from the README.
2. Locate by behavior, not layout. Prefer user-facing locators (getByRole, getByLabel, getByText) over CSS/XPath that encode markup. Tests coupled to user-visible behavior survive refactors; tests coupled to structure break on them.
3. Mock at the boundary. Stub external HTTP at page.route() — never by patching in-page code. Mock the dependency under test's edges, never the code under test itself; a test that mocks what it claims to verify proves nothing.
4. Parallelize deliberately. Playwright gives every test an isolated browser context. Tune workers and sharding to the machine and suite, and never let tests share mutable state through globals.
5. Verify at the boundary. A green test is only as strong as its assertions. Assert on user-visible outcomes (visible text, URL, enabled/disabled state), not on implementation details.
6. Keep evidence bounded. Capture traces, screenshots, and video on failure only; summarize JSON reports instead of dumping them; never paste full HTML dumps or session cookies into chat.

The pwrun script

scripts/pwrun is an agent-first smoke harness around a Playwright suite. doctor, inventory, and report work with no node or Playwright installed, so an agent can inspect a suite and triage a CI report anywhere.

scripts/pwrun doctor --json                     # node, @playwright/test, browsers, config availability
scripts/pwrun inventory --json                  # config, projects, spec files in the suite
scripts/pwrun report --report test-results.json --json   # summarize a Playwright JSON report
scripts/pwrun smoke --url http://localhost:3000 --json   # delegate a smoke run to npx playwright test

Exit codes: 0 ok, 1 analysis error, 2 usage error, 127 dependency (node/playwright) missing, 124 delegate timeout. --json on every command; --help works without any toolchain.

For smoke, --config is forwarded to Playwright. The target URL precedence is --url, inherited PW_SMOKE_URL, inherited BASE_URL, then http://localhost:3000; the chosen target is passed to the supplied scaffold as PW_SMOKE_URL. The JSON result separates requested_url from navigation_evidence. The bundled example spec records the URL reached after page.goto(); custom specs need a pwrun-navigation annotation to provide the same runtime evidence. requested_target_origin_observed shows whether any recorded navigation reached the requested origin.

E2E test authoring

• Structure suites with test.describe blocks, test.beforeEach setup, and per-feature fixture files. Keep specs short, focused on one user journey, and readable as prose.
• Use Playwright's web-first assertions (expect(locator).toBeVisible(), .toHaveText(), .toHaveURL()) — they auto-retry until a timeout and are the backbone of stable E2E tests. Avoid manual page.waitForTimeout sleeps.
• Start the app under test with webServer in the config (Playwright starts it, waits for readiness, and tears it down), or reuse an already-running instance via baseURL for smoke passes.
• Authoring patterns, fixtures, and the page-object model: references/01-e2e-authoring.md.

Selector robustness

• Default to role, label, text, and placeholder locators — they describe the page the way a user does. Reserve CSS for layout-adjacent needs (e.g., getByTestId for ids that exist only for tests).
• Chain and filter locators (getByRole('row').filter({ hasText: 'Acme' })) instead of building one long brittle selector. Re-query rather than storing stale element handles.
• Fix flaky tests by finding which selector matched multiple or zero elements, not by adding sleeps or first(). A selector that can match the wrong thing will eventually.
• Selector priority rules and flaky-selector repair flows: references/02-selectors.md.

Network interception and mocking

• Intercept requests with page.route() and fulfill, abort, or continue them. Use this to mock third-party APIs, inject fixtures, emulate offline or slow networks, and block analytics/trackers that pollute tests.
• Mock at the route level with realistic bodies and content types. Never intercept the server the test is supposed to verify, and never route over page.goto navigation the test depends on.
• Capture requests with page.on('request')/page.on('response') to assert on what the app actually sent. Patterns and gotchas: references/03-network-interception-and-mocking.md.

Parallel workers

• workers sets how many parallel processes run specs; fullyParallel lets every spec file run across workers. Scale to CPU count and browser memory, not to "as many as possible".
• Shard suites across CI jobs (--shard=1/4) for large suites. Every test runs in its own browser context, so isolation is default — keep it that way: no shared globals, no shared storage state, no test-order coupling.
• Worker counts, sharding math, and isolation traps: references/04-parallel-workers-and-sharding.md.

CI integration

• Install browsers and OS deps on the runner (npx playwright@1.62.1 install --with-deps), pin the Playwright version, and cache ~/.cache/ms-playwright.
• Configure webServer, retries (retry flaky tests on CI only), and trace: 'on-first-retry' so failures are debuggable. Report with html/json/github and upload artifacts on failure.
• Triage CI failures from the JSON report with scripts/pwrun report --json — it summarizes stats, failing specs, and error messages without opening a browser. Full CI recipes: references/05-ci-integration.md.

Scraping and headless browsing

• Drive the browser API directly (chromium.launch({ headless: true }), newContext, page.goto) to load JavaScript-rendered pages, then extract with locators and innerText/attribute access into structured records — extract, validate, save.
• Respect robots.txt, terms, and rate limits; bound the scrape by page count and delay. For Cloudflare/DDoS-GUARD challenge bypass, route to flaresolverr — this skill does not solve challenges.
• Scraping flows, pagination, and polite extraction: references/06-scraping-and-headless.md.