qa-testing-playwright

QA Testing (Playwright)

Core docs:

• https://playwright.dev/docs/best-practices
• https://playwright.dev/docs/locators
• https://playwright.dev/docs/auth
• https://playwright.dev/docs/api-testing
• https://playwright.dev/docs/test-retries
• https://playwright.dev/docs/test-snapshots
• https://playwright.dev/docs/trace-viewer
• https://playwright.dev/docs/test-sharding
• https://playwright.dev/docs/ci
• https://playwright.dev/docs/pom
• https://playwright.dev/docs/test-agents
• https://playwright.dev/docs/clock
• https://playwright.dev/docs/getting-started-cli
• https://playwright.dev/docs/test-components
• https://playwright.dev/docs/test-parallel#test-locks
• https://playwright.dev/docs/release-notes (check the current version before pinning)

Quick Reference

Defaults

• Keep E2E thin: protect critical user journeys only; push coverage down (unit/integration/contract).
• Locator priority: getByRole → getByLabel/getByText → getByTestId (fallback).
• Waiting: rely on Playwright auto-wait + web-first assertions; no sleeps/time-based waits.
• Isolation: tests must run alone, in parallel, and in any order; eliminate shared mutable state. When a shared resource cannot be isolated (external service, global account setting), declare a named test lock (1.63+: test(title, { lock: 'user-settings' }, fn)) instead of workers: 1 or describe.serial for the whole file.
• Local execution posture: choose one server topology first (shared dev stack or Playwright-managed webServer), then triage with an exact spec or named batch plus --workers=1.
• Flake posture: retries are a debugging tool; treat rerun-pass as a failure signal and fix root cause.
• CI flakes: prefer built-in failOnFlakyTests (1.52+); the custom reporter template is legacy, for pre-1.52 pins only.
• CI posture: smoke gate on PRs; shard/parallelize regression on schedule; always keep artifacts (trace/video/screenshot).
• Oracle posture: assert the user outcome; do not wait on incidental network requests when the visible result can be verified directly.
• AI posture: use Playwright codegen / test agents / MCP for scaffolding and exploration, then harden assertions and fixtures manually.
• Component tests: use the built-in stories/gallery mount('components/X/Story') fixture from @playwright/test (1.62+). The @playwright/experimental-ct-* packages were frozen in 1.63 and the docs now say they are removed; stay on 1.62 until migrated. See references/playwright-patterns.md#component-testing.
• Visual regression: native toHaveScreenshot when one OS/browser baseline set in Docker is enough; a hosted service when designers review diffs or the browser/OS matrix makes committed baselines unmanageable. See references/visual-regression-testing.md.
• Browser MCP: Playwright MCP for test generation + accessibility; Chrome DevTools MCP for performance / network / console debugging. See references/playwright-mcp.md.
• CLI posture: for high-throughput coding agents, prefer the Playwright CLI (npx playwright cli; shell commands) over Playwright MCP — it avoids the MCP protocol's per-call token overhead. Check npx playwright cli --version / release notes for your installed version before relying on it, since CLI availability and flags vary by release. The official docs call it token-efficient without a number; treat any specific token-count figure (e.g. a "tokens/task" comparison) as a claim to verify against your own measurement, not a quotable fact. Use MCP (npx playwright mcp) when persistent browser state and rich introspection are needed.
• Local iteration posture: use npx playwright test --only-changed=main to run only tests affected by uncommitted/branch changes during authoring; it is a heuristic over the import graph, so always run the full suite (or the deploy-gate replay) before merging — never treat --only-changed green as release-ready signal.