| name | playwright-best-practices |
| description | Write, debug, and maintain Playwright tests — flaky tests, Page Object Model, locators/waits, fixtures, network mocking, auth, CI/CD. Covers E2E, component, API, visual, a11y, and extension testing. |
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.
