Playwright

Overview

Playwright is a browser automation framework for Node.js and Python supporting Chromium, Firefox, and WebKit with a single API. It provides auto-waiting, web-first assertions, and full test isolation for reliable end-to-end testing.

When to use: Browser automation, web scraping, screenshot/PDF generation, API testing, configuring Playwright Test, troubleshooting Playwright errors, stealth mode and anti-bot bypass.

When NOT to use: Simple HTTP requests (use fetch), unit testing (use Vitest/Jest), serverless scraping at scale (consider Cloudflare Browser Rendering). For E2E test architecture (Page Object Models, CI sharding, test organization, authentication patterns), use the e2e-testing skill.

Quick Reference

Pattern	API / Config	Key Points
Basic test	`test('name', async ({ page }) => {})`	Auto-wait, web-first assertions, test isolation
Locator	`page.getByRole()` / `page.locator()`	Prefer role/label/text selectors over CSS
Assertion	`expect(locator).toBeVisible()`	Auto-retrying, configurable timeout
API testing	`request` fixture / `apiRequestContext`	Send HTTP requests, validate responses
Aria snapshot	`expect(locator).toMatchAriaSnapshot()`	Validate accessibility tree structure via YAML
Class assertion	`expect(locator).toContainClass('active')`	Match individual CSS class names (v1.52+)
Visible filter	`locator.filter({ visible: true })`	Match only visible elements (v1.51+)
Test step	`test.step('name', async (step) => {})`	Timeout, skip, and attachments (v1.50+)
Stealth mode	`playwright-extra` + stealth plugin	Patches 20+ detection vectors
Authenticated session	`context.cookies()` + `addCookies()`	Save/restore cookies and IndexedDB for persistence
Screenshot	`page.screenshot({ fullPage: true })`	Wait for key elements to load first
PDF generation	`page.pdf({ format: 'A4' })`	Chromium only, set `printBackground: true`
Clock API	`page.clock`	Freeze, fast-forward, or simulate time in tests
A11y assertions	`toHaveAccessibleName`, `toHaveRole`	Native assertions without axe-core dependency
Viewport assertion	`expect(locator).toBeInViewport()`	Assert element is within the visible viewport
Changed tests only	`--only-changed=$GITHUB_BASE_REF`	Run only test files changed since base branch
Docker	`mcr.microsoft.com/playwright:v1.58.2-noble`	Use `--init --ipc=host` flags
Debug methods	`page.consoleMessages()` / `page.requests()` (v1.56+)	No event listeners needed
Speedboard	HTML reporter (v1.57+)	Identifies slow tests and bottlenecks
Playwright Agents	`npx playwright init-agents`	Planner, generator, healer for LLM-driven testing
Flaky test detection	`--fail-on-flaky-tests` (v1.50+)	Exit code 1 on flaky tests in CI
Modify live responses	`route.fetch()` + `route.fulfill()`	Intercept real response, tweak JSON, return it
Soft assertions	`expect.soft(locator)`	Don't stop test on failure, report all at end
Retry block	`expect(async () => {}).toPass()`	Default timeout is 0 (forever) — always set one
Custom matchers	`expect.extend()` / `mergeExpects()`	Define or combine custom assertion methods
Actionability matrix	Per-action auto-wait checks	click: all 5 checks, fill: 3, focus/blur: none
Test modifiers	`test.fixme()` / `test.fail()` / `test.slow()`	fixme=skip+track, fail=assert failure, slow=3x
Parallel modes	`test.describe.configure({ mode: 'serial' })`	serial, parallel, or default per-describe block
Teardown projects	`teardown` option on setup projects	Auto-cleanup after all dependents finish

Common Mistakes

Mistake	Correct Pattern
Using CSS selectors over role selectors	Prefer `getByRole`, `getByLabel`, `getByText` for resilience
Not closing browser	Always `await browser.close()` in `finally` block
Using `setTimeout` for waits	Use locator auto-wait or `waitForLoadState`
`page.pause()` left in CI code	Guard with `if (!process.env.CI)` — hangs CI indefinitely
Clicking without waiting	Use `locator().click()` with built-in auto-wait
Shared state between tests	Each test gets fresh context via fixtures
Testing implementation details	Assert user-visible behavior, not DOM structure
Hardcoded waits for dynamic content	Wait for selector appearance or content stabilization
Missing `await` on assertions	All `expect()` assertions return promises — must be awaited
Same user agent for all scraping	Rotate user agents for high-volume scraping
Using `setTimeout` for time-dependent tests	Use `page.clock` API to freeze/fast-forward time
Installing axe-core for simple a11y checks	Use native `toHaveAccessibleName`/`toHaveRole` assertions
Using `toPass()` without explicit timeout	Always pass `{ timeout: 10_000 }` — default is 0 (forever)
Service worker silently blocking `page.route()`	Set `serviceWorkers: 'block'` in context config when using MSW
Using `fill()` for autocomplete/debounce inputs	Use `pressSequentially()` with optional delay for per-keystroke handling
`storageState` losing sessionStorage	`storageState` only saves cookies + localStorage — inject sessionStorage via `addInitScript()`

Delegation

Selector troubleshooting: Use Explore agent
Test pattern review: Use Task agent
Code review: Delegate to code-reviewer agent

For E2E test architecture, Page Object Model patterns, CI sharding strategies, authentication flows, visual regression workflows, or test organization, use the e2e-testing skill.

playwright

Playwright

Overview

Quick Reference

Common Mistakes

Delegation

References