mediar-ai/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

| Activity | Reference Files | | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | Writing E2E tests | test-organization.md, locators.md, assertions-waiting.md | | Writing component tests | component-testing.md, test-organization.md | | Writing API tests | test-organization.md, assertions-waiting.md | | Writing visual regression tests | test-organization.md, canvas-webgl.md | | Structuring test code with POM | page-object-model.md, test-organization.md | | Setting up test data/fixtures | fixtures-hooks.md, test-data.md | | Handling authentication | fixtures-hooks.md, third-party.md | | Testing date/time features | clock-mocking.md | | Testing file upload/download | file-operations.md | | Testing accessibility | accessibility.md | | Testing security (XSS, CSRF) | security-testing.md | | Using test annotations | annotations.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 |

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-organization.md | | Improving test organization | test-organization.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 |

Infrastructure & Configuration

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

| Activity | Reference Files | | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | Configuring Playwright project | test-organization.md, projects-dependencies.md | | Setting up CI/CD pipelines | ci-cd.md, performance.md | | Global setup & teardown | global-setup.md | | Project dependencies | projects-dependencies.md | | Optimizing test performance | performance.md, test-organization.md | | Configuring parallel execution | performance.md | | Isolating test data between workers | fixtures-hooks.md, performance.md | | Test coverage | test-coverage.md |

Advanced Patterns

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

| Activity | Reference Files | | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------- | | Mocking API responses | test-organization.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 steps for reporting | annotations.md |

Quick Decision Tree

What are you doing?
│
├─ Writing a new test?
│  ├─ E2E test → test-organization.md, locators.md, assertions-waiting.md
│  ├─ Component test → component-testing.md
│  ├─ API test → test-organization.md, assertions-waiting.md
│  ├─ Visual/canvas test → canvas-webgl.md, test-organization.md
│  ├─ Accessibility test → accessibility.md
│  ├─ Mobile/responsive test → mobile-testing.md
│  ├─ i18n/locale test → i18n.md
│  ├─ Electron app test → electron.md
│  ├─ Browser extension test → browser-extensions.md
│  └─ Multi-user test → multi-user.md
│
├─ Testing specific features?
│  ├─ File upload/download → file-operations.md
│  ├─ Date/time dependent → clock-mocking.md
│  ├─ WebSocket/real-time → websockets.md
│  ├─ Geolocation/permissions → browser-apis.md
│  ├─ OAuth/SSO mocking → third-party.md, multi-context.md
│  ├─ Payments/email/SMS → third-party.md
│  ├─ iFrames → iframes.md
│  ├─ Canvas/WebGL/charts → canvas-webgl.md
│  ├─ Service workers/PWA → service-workers.md
│  ├─ i18n/localization → i18n.md
│  ├─ Security (XSS, CSRF) → security-testing.md
│  └─ Performance/Web Vitals → performance-testing.md
│
├─ Test is failing/flaky?
│  ├─ Flaky test investigation → flaky-tests.md
│  ├─ Element not found → locators.md, debugging.md
│  ├─ Timeout issues → assertions-waiting.md, debugging.md
│  ├─ Race conditions → flaky-tests.md, debugging.md
│  ├─ Flaky only with multiple workers → flaky-tests.md, performance.md
│  ├─ State leak / isolation → flaky-tests.md, fixtures-hooks.md
│  ├─ Console/JS errors → console-errors.md, debugging.md
│  └─ General debugging → debugging.md
│
├─ Testing error scenarios?
│  ├─ Network failures → error-testing.md, network-advanced.md
│  ├─ Offline (unexpected) → error-testing.md
│  ├─ Offline-first/PWA → service-workers.md
│  ├─ Error boundaries → error-testing.md
│  └─ Form validation → error-testing.md
│
├─ Refactoring existing code?
│  ├─ Implementing POM → page-object-model.md
│  ├─ Improving selectors → locators.md
│  ├─ Extracting fixtures → fixtures-hooks.md
│  └─ Creating data factories → test-data.md
│
├─ Setting up infrastructure?
│  ├─ CI/CD → ci-cd.md
│  ├─ Global setup/teardown → global-setup.md
│  ├─ Project dependencies → projects-dependencies.md
│  ├─ Test performance → performance.md
│  ├─ Test coverage → test-coverage.md
│  └─ Project config → test-organization.md, projects-dependencies.md
│
└─ Organizing tests?
   ├─ Skip/fixme/slow tests → annotations.md
   ├─ Test steps → annotations.md
   └─ Conditional execution → annotations.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