Playwright Best Practices

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

Mobile & Responsive Testing

When to use: Testing mobile devices, touch interactions, responsive layouts

Real-Time & Browser APIs

When to use: Testing WebSockets, geolocation, permissions, multi-tab flows

Debugging & Troubleshooting

When to use: Test failures, element not found, timeouts, unexpected behavior

Error & Edge Case Testing

When to use: Testing error states, offline mode, network failures, validation

Multi-User & Collaboration Testing

When to use: Testing features involving multiple users, roles, or real-time collaboration

Architecture Decisions

When to use: Choosing test patterns, deciding between approaches, planning test architecture

Framework-Specific Testing

When to use: Testing React, Angular, Vue, or Next.js applications

Refactoring & Maintenance

When to use: Improving existing tests, code review, reducing duplication

Infrastructure & Configuration

When to use: Setting up projects, configuring CI/​CD, optimizing performance

Advanced Patterns

When to use: Complex scenarios, API mocking, network interception

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:

1. Run tests: npx playwright test --reporter=list
2. If tests fail:
   • Review error output and trace (npx playwright show-trace)
   • Fix locators, waits, or assertions
   • Re-run tests
3. Only proceed when all tests pass
4. Run multiple times for critical tests: npx playwright test --repeat-each=5