Playwright Best Practices

This skill provides comprehensive guidance for all aspects of Playwright test development, from writing new tests to debugging and maintaining existing test suites.

Activity-Based Reference Guide

Consult these references based on what you're doing:

Writing New Tests

When to use

Creating new test files, writing test cases, implementing test scenarios

Activity

Reference Files

Writing E2E tests

test-suite-structure.md

,

locators.md

,

assertions-waiting.md

Writing component tests

component-testing.md

,

test-suite-structure.md

Writing API tests

api-testing.md

,

test-suite-structure.md

Writing GraphQL tests

graphql-testing.md

,

api-testing.md

Writing visual regression tests

visual-regression.md

,

canvas-webgl.md

Structuring test code with POM

page-object-model.md

,

test-suite-structure.md

Setting up test data/fixtures

fixtures-hooks.md

,

test-data.md

Handling authentication

authentication.md

,

authentication-flows.md

Testing date/time features

clock-mocking.md

Testing file upload/download

file-operations.md

,

file-upload-download.md

Testing forms/validation

forms-validation.md

Testing drag and drop

drag-drop.md

Testing accessibility

accessibility.md

Testing security (XSS, CSRF)

security-testing.md

Using test annotations

annotations.md

Using test tags

test-tags.md

Testing iframes

iframes.md

Testing canvas/WebGL

canvas-webgl.md

Internationalization (i18n)

i18n.md

Testing Electron apps

electron.md

Testing browser extensions

browser-extensions.md

Mobile & Responsive Testing

When to use

Testing mobile devices, touch interactions, responsive layouts

Activity

Reference Files

Device emulation

mobile-testing.md

Touch gestures (swipe, tap)

mobile-testing.md

Viewport/breakpoint testing

mobile-testing.md

Mobile-specific UI

mobile-testing.md

,

locators.md

Real-Time & Browser APIs

When to use

Testing WebSockets, geolocation, permissions, multi-tab flows

Activity

Reference Files

WebSocket/real-time testing

websockets.md

Geolocation mocking

browser-apis.md

Permission handling

browser-apis.md

Clipboard testing

browser-apis.md

Camera/microphone mocking

browser-apis.md

Multi-tab/popup flows

multi-context.md

OAuth popup handling

third-party.md

,

multi-context.md

Debugging & Troubleshooting

When to use

Test failures, element not found, timeouts, unexpected behavior

Activity

Reference Files

Debugging test failures

debugging.md

,

assertions-waiting.md

Fixing flaky tests

flaky-tests.md

,

debugging.md

,

assertions-waiting.md

Debugging flaky parallel runs

flaky-tests.md

,

performance.md

,

fixtures-hooks.md

Ensuring test isolation / avoiding state leak

flaky-tests.md

,

fixtures-hooks.md

,

performance.md

Fixing selector issues

locators.md

,

debugging.md

Investigating timeout issues

assertions-waiting.md

,

debugging.md

Using trace viewer

debugging.md

Debugging race conditions

flaky-tests.md

,

debugging.md

,

assertions-waiting.md

Debugging console/JS errors

console-errors.md

,

debugging.md

Error & Edge Case Testing

When to use

Testing error states, offline mode, network failures, validation

Activity

Reference Files

Error boundary testing

error-testing.md

Network failure simulation

error-testing.md

,

network-advanced.md

Offline mode testing

error-testing.md

,

service-workers.md

Service worker testing

service-workers.md

Loading state testing

error-testing.md

Form validation testing

error-testing.md

Multi-User & Collaboration Testing

When to use

Testing features involving multiple users, roles, or real-time collaboration

Activity

Reference Files

Multiple users in one test

multi-user.md

Real-time collaboration

multi-user.md

,

websockets.md

Role-based access testing

multi-user.md

Concurrent action testing

multi-user.md

Architecture Decisions

When to use

Choosing test patterns, deciding between approaches, planning test architecture

Activity

Reference Files

POM vs fixtures decision

pom-vs-fixtures.md

Test type selection

test-architecture.md

Mock vs real services

when-to-mock.md

Test suite structure

test-suite-structure.md

Framework-Specific Testing

When to use

Testing React, Angular, Vue, or Next.js applications

Activity

Reference Files

Testing React apps

react.md

Testing Angular apps

angular.md

Testing Vue/Nuxt apps

vue.md

Testing Next.js apps

nextjs.md

Refactoring & Maintenance

When to use

Improving existing tests, code review, reducing duplication

Activity

Reference Files

Refactoring to Page Object Model

page-object-model.md

,

test-suite-structure.md

Improving test organization

test-suite-structure.md

,

page-object-model.md

Extracting common setup/teardown

fixtures-hooks.md

Replacing brittle selectors

locators.md

Removing explicit waits

assertions-waiting.md

Creating test data factories

test-data.md

Configuration setup

configuration.md

Infrastructure & Configuration

When to use

Setting up projects, configuring CI/CD, optimizing performance

Activity

Reference Files

Configuring Playwright project

configuration.md

,

projects-dependencies.md

Setting up CI/CD pipelines

ci-cd.md

,

github-actions.md

GitHub Actions setup

github-actions.md

GitLab CI setup

gitlab.md

Other CI providers

other-providers.md

Docker/container setup

docker.md

Global setup & teardown

global-setup.md

Project dependencies

projects-dependencies.md

Optimizing test performance

performance.md

,

test-suite-structure.md

Configuring parallel execution

parallel-sharding.md

,

performance.md

Isolating test data between workers

fixtures-hooks.md

,

performance.md

Test coverage

test-coverage.md

Test reporting/artifacts

reporting.md

Advanced Patterns

When to use

Complex scenarios, API mocking, network interception Activity Reference Files Mocking API responses test-suite-structure.md , network-advanced.md Network interception network-advanced.md , assertions-waiting.md GraphQL mocking network-advanced.md HAR recording/playback network-advanced.md Custom fixtures fixtures-hooks.md Advanced waiting strategies assertions-waiting.md OAuth/SSO mocking third-party.md , multi-context.md Payment gateway mocking third-party.md Email/SMS verification mocking third-party.md Failing on console errors console-errors.md Security testing (XSS, CSRF) security-testing.md Performance budgets & Web Vitals performance-testing.md Lighthouse integration performance-testing.md Test annotations (skip, fixme) annotations.md Test tags (@smoke, @fast) test-tags.md Test steps for reporting annotations.md Quick Decision Tree What are you doing? │ ├─ Writing a new test? │ ├─ E2E test → core/test-suite-structure.md, core/locators.md, core/assertions-waiting.md │ ├─ Component test → testing-patterns/component-testing.md │ ├─ API test → testing-patterns/api-testing.md, core/test-suite-structure.md │ ├─ GraphQL test → testing-patterns/graphql-testing.md │ ├─ Visual regression → testing-patterns/visual-regression.md │ ├─ Visual/canvas test → testing-patterns/canvas-webgl.md, core/test-suite-structure.md │ ├─ Accessibility test → testing-patterns/accessibility.md │ ├─ Mobile/responsive test → advanced/mobile-testing.md │ ├─ i18n/locale test → testing-patterns/i18n.md │ ├─ Electron app test → testing-patterns/electron.md │ ├─ Browser extension test → testing-patterns/browser-extensions.md │ ├─ Multi-user test → advanced/multi-user.md │ ├─ Form validation test → testing-patterns/forms-validation.md │ └─ Drag and drop test → testing-patterns/drag-drop.md │ ├─ Testing specific features? │ ├─ File upload/download → testing-patterns/file-operations.md, testing-patterns/file-upload-download.md │ ├─ Date/time dependent → advanced/clock-mocking.md │ ├─ WebSocket/real-time → browser-apis/websockets.md │ ├─ Geolocation/permissions → browser-apis/browser-apis.md │ ├─ OAuth/SSO mocking → advanced/third-party.md, advanced/multi-context.md │ ├─ Payments/email/SMS → advanced/third-party.md │ ├─ iFrames → browser-apis/iframes.md │ ├─ Canvas/WebGL/charts → testing-patterns/canvas-webgl.md │ ├─ Service workers/PWA → browser-apis/service-workers.md │ ├─ i18n/localization → testing-patterns/i18n.md │ ├─ Security (XSS, CSRF) → testing-patterns/security-testing.md │ └─ Performance/Web Vitals → testing-patterns/performance-testing.md │ ├─ Architecture decisions? │ ├─ POM vs fixtures → architecture/pom-vs-fixtures.md │ ├─ Test type selection → architecture/test-architecture.md │ ├─ Mock vs real services → architecture/when-to-mock.md │ └─ Test suite structure → core/test-suite-structure.md │ ├─ Framework-specific testing? │ ├─ React app → frameworks/react.md │ ├─ Angular app → frameworks/angular.md │ ├─ Vue/Nuxt app → frameworks/vue.md │ └─ Next.js app → frameworks/nextjs.md │ ├─ Authentication testing? │ ├─ Basic auth patterns → advanced/authentication.md │ └─ Complex flows (MFA, reset) → advanced/authentication-flows.md │ ├─ Test is failing/flaky? │ ├─ Flaky test investigation → debugging/flaky-tests.md │ ├─ Element not found → core/locators.md, debugging/debugging.md │ ├─ Timeout issues → core/assertions-waiting.md, debugging/debugging.md │ ├─ Race conditions → debugging/flaky-tests.md, debugging/debugging.md │ ├─ Flaky only with multiple workers → debugging/flaky-tests.md, infrastructure-ci-cd/performance.md │ ├─ State leak / isolation → debugging/flaky-tests.md, core/fixtures-hooks.md │ ├─ Console/JS errors → debugging/console-errors.md, debugging/debugging.md │ └─ General debugging → debugging/debugging.md │ ├─ Testing error scenarios? │ ├─ Network failures → debugging/error-testing.md, advanced/network-advanced.md │ ├─ Offline (unexpected) → debugging/error-testing.md │ ├─ Offline-first/PWA → browser-apis/service-workers.md │ ├─ Error boundaries → debugging/error-testing.md │ └─ Form validation → testing-patterns/forms-validation.md, debugging/error-testing.md │ ├─ Refactoring existing code? │ ├─ Implementing POM → core/page-object-model.md │ ├─ Improving selectors → core/locators.md │ ├─ Extracting fixtures → core/fixtures-hooks.md │ ├─ Creating data factories → core/test-data.md │ └─ Configuration setup → core/configuration.md │ ├─ Setting up infrastructure? │ ├─ CI/CD → infrastructure-ci-cd/ci-cd.md │ ├─ GitHub Actions → infrastructure-ci-cd/github-actions.md │ ├─ GitLab CI → infrastructure-ci-cd/gitlab.md │ ├─ Other CI providers → infrastructure-ci-cd/other-providers.md │ ├─ Docker/containers → infrastructure-ci-cd/docker.md │ ├─ Sharding/parallel → infrastructure-ci-cd/parallel-sharding.md │ ├─ Reporting/artifacts → infrastructure-ci-cd/reporting.md │ ├─ Global setup/teardown → core/global-setup.md │ ├─ Project dependencies → core/projects-dependencies.md │ ├─ Test performance → infrastructure-ci-cd/performance.md │ ├─ Test coverage → infrastructure-ci-cd/test-coverage.md │ └─ Project config → core/configuration.md, core/projects-dependencies.md │ ├─ Organizing tests? │ ├─ Skip/fixme/slow tests → core/annotations.md │ ├─ Test tags (@smoke, @fast) → core/test-tags.md │ ├─ Filtering tests (--grep) → core/test-tags.md │ ├─ Test steps → core/annotations.md │ └─ Conditional execution → core/annotations.md │ └─ Running subset of tests? ├─ By tag (@smoke, @critical) → core/test-tags.md ├─ Exclude slow/flaky tests → core/test-tags.md ├─ PR vs nightly tests → core/test-tags.md, infrastructure-ci-cd/ci-cd.md └─ Project-specific filtering → core/test-tags.md, core/configuration.md Test Validation Loop After writing or modifying tests: Run tests : npx playwright test --reporter=list If tests fail : Review error output and trace ( npx playwright show-trace ) Fix locators, waits, or assertions Re-run tests Only proceed when all tests pass Run multiple times for critical tests: npx playwright test --repeat-each=5