Playwright Best Practices

Comprehensive guidance for Playwright test development — writing, debugging, and maintaining E2E, component, API, visual, accessibility, security, Electron, and extension tests. Every detail lives in the reference files below; this page only routes you to the right one.

References

Each file is loaded on demand — read one only when the task needs that depth (progressive disclosure).

core/ — the foundation every test relies on

• core/test-suite-structure.md — organizing specs, suites, and API mocking baseline · read when scaffolding a new spec or structuring a suite.
• core/locators.md — stable, user-facing selectors (getByRole/getByLabel/getByText/data-testid) over brittle CSS/XPath · read when picking or fixing selectors.
• core/assertions-waiting.md — web-first assertions and auto-waiting instead of fixed timeouts · read when adding assertions, fixing timeouts, or removing explicit waits.
• core/page-object-model.md — POM structure and refactoring toward it · read when implementing or refactoring to Page Objects.
• core/fixtures-hooks.md — custom fixtures, beforeEach/afterEach, per-worker isolation · read when extracting setup/teardown or isolating data between workers.
• core/test-data.md — test-data factories and seeding · read when creating reusable test data.
• core/configuration.md — playwright.config setup · read when configuring a project.
• core/annotations.md — skip/fixme/slow, conditional execution, test steps · read when annotating or grouping tests for reporting.
• core/test-tags.md — @smoke/@fast/@critical tags and --grep filtering · read when tagging or running a subset of tests.
• core/global-setup.md — global setup & teardown · read when sharing one-time setup across the run.
• core/projects-dependencies.md — projects and project dependencies · read when wiring multi-project or dependent setups.

testing-patterns/ — what kind of test you're writing

• testing-patterns/component-testing.md — component tests · read when testing a component in isolation.
• testing-patterns/api-testing.md — API request testing · read when testing endpoints directly.
• testing-patterns/graphql-testing.md — GraphQL request/mocking · read when testing or mocking GraphQL.
• testing-patterns/visual-regression.md — screenshot/visual regression · read when adding visual snapshots.
• testing-patterns/canvas-webgl.md — canvas/WebGL/chart testing · read when asserting on canvas-rendered UI.
• testing-patterns/accessibility.md — axe-core a11y testing · read when testing accessibility.
• testing-patterns/security-testing.md — XSS/CSRF/auth security tests · read when testing security surfaces.
• testing-patterns/forms-validation.md — form and validation flows · read when testing forms.
• testing-patterns/drag-drop.md — drag-and-drop interactions · read when testing drag/drop.
• testing-patterns/file-operations.md + testing-patterns/file-upload-download.md — file upload/download · read when testing file I/O.
• testing-patterns/i18n.md — internationalization/locale testing · read when testing localized UI.
• testing-patterns/electron.md — Electron app testing · read when testing an Electron app.
• testing-patterns/browser-extensions.md — browser-extension testing · read when testing an extension.
• testing-patterns/performance-testing.md — performance budgets, Web Vitals, Lighthouse · read when asserting on performance.

advanced/ — complex flows, auth, and network

• advanced/authentication.md + advanced/authentication-flows.md — auth setup and complex flows (MFA, reset) · read when handling login/auth state.
• advanced/network-advanced.md — network interception, mocking, HAR record/playback · read when mocking responses or intercepting requests.
• advanced/multi-context.md — multi-tab/popup and OAuth popup flows · read when testing multiple tabs/contexts.
• advanced/multi-user.md — multiple users, roles, real-time collaboration · read when testing multi-user/role scenarios.
• advanced/third-party.md — OAuth/SSO, payments, email/SMS verification · read when integrating third-party services.
• advanced/clock-mocking.md — date/time mocking · read when testing time-dependent behavior.
• advanced/mobile-testing.md — device emulation, touch gestures, viewport/breakpoints · read when testing mobile/responsive layouts.

browser-apis/ — browser capabilities

• browser-apis/browser-apis.md — geolocation, permissions, clipboard, camera/microphone mocking · read when testing browser APIs.
• browser-apis/websockets.md — WebSocket/real-time testing · read when testing live connections.
• browser-apis/iframes.md — iframe testing · read when interacting with iframes.
• browser-apis/service-workers.md — service workers, PWA, offline-first · read when testing SW/PWA behavior.

debugging/ — when a test fails or flakes

• debugging/debugging.md — trace viewer, error context, general debugging · read when investigating any failure.
• debugging/flaky-tests.md — flakiness, race conditions, isolation, state leaks, parallel-run flakiness · read when a test is flaky.
• debugging/console-errors.md — console/JS error monitoring, fail-on-console-error · read when watching console output.
• debugging/error-testing.md — error boundaries, network failures, offline, loading/validation states · read when testing error/edge cases.

architecture/ — choosing the right approach

• architecture/pom-vs-fixtures.md — POM vs fixtures decision · read when deciding how to structure shared logic.
• architecture/test-architecture.md — test-type selection · read when planning what to test at which level.
• architecture/when-to-mock.md — mock vs real services · read when deciding to mock or hit the real thing.

frameworks/ — framework-specific guidance

• frameworks/react.md · frameworks/angular.md · frameworks/vue.md · frameworks/nextjs.md — read the one matching the app under test.

infrastructure-ci-cd/ — running tests at scale

• infrastructure-ci-cd/ci-cd.md — CI/CD pipeline setup · read when wiring tests into CI.
• infrastructure-ci-cd/github-actions.md · infrastructure-ci-cd/gitlab.md · infrastructure-ci-cd/other-providers.md — provider-specific CI config · read for your provider.
• infrastructure-ci-cd/docker.md — containerized runs · read when running in Docker.
• infrastructure-ci-cd/parallel-sharding.md — parallel execution and sharding · read when scaling out the run.
• infrastructure-ci-cd/performance.md — test-suite performance and worker isolation · read when speeding up the suite.
• infrastructure-ci-cd/test-coverage.md — coverage collection · read when measuring coverage.
• infrastructure-ci-cd/reporting.md — reporters and artifacts · read when configuring reports/artifacts.

Validation loop

After writing or modifying tests: run npx playwright test --reporter=list; on failure, inspect the trace (npx playwright show-trace), fix locators/waits/assertions, and re-run; only proceed when green; for critical tests, confirm stability with npx playwright test --repeat-each=5.