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