playwright-best-practices

SKILL.md

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