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:
- 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
1---2name: playwright-best-practices3description: Provides comprehensive guidance for writing, debugging, and maintaining Playwright tests in TypeScript. Use when writing Playwright tests, fixing flaky tests, debugging failures, implementing Page Object Model, configuring CI/CD, optimizing performance, mocking APIs, handling authentication or OAuth, testing accessibility (axe-core), file uploads/downloads, date/time mocking, WebSockets, geolocation, permissions, multi-tab/popup flows, mobile/responsive layouts, touch gestures, GraphQL, error handling, offline mode, multi-user collaboration, third-party services (payments, email verification), console error monitoring, global setup/teardown, test annotations (skip, fixme, slow), project dependencies, security testing (XSS, CSRF, auth), performance budgets (Web Vitals, Lighthouse), iframes, component testing, canvas/WebGL, service workers/PWA, test coverage, i18n/localization, Electron apps, or browser extension testing. Covers E2E, component, API, visual, accessibility, security, Electron, and extension testi4license: MIT5---67# Playwright Best Practices89This skill provides comprehensive guidance for all aspects of Playwright test development, from writing new tests to debugging and maintaining existing test suites.1011## Activity-Based Reference Guide1213Consult these references based on what you're doing:1415### Writing New Tests1617**When to use**: Creating new test files, writing test cases, implementing test scenarios1819| Activity | Reference Files |20| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |21| **Writing E2E tests** | [test-organization.md](references/test-organization.md), [locators.md](references/locators.md), [assertions-waiting.md](references/assertions-waiting.md) |22| **Writing component tests** | [component-testing.md](references/component-testing.md), [test-organization.md](references/test-organization.md) |23| **Writing API tests** | [test-organization.md](references/test-organization.md), [assertions-waiting.md](references/assertions-waiting.md) |24| **Writing visual regression tests** | [test-organization.md](references/test-organization.md), [canvas-webgl.md](references/canvas-webgl.md) |25| **Structuring test code with POM** | [page-object-model.md](references/page-object-model.md), [test-organization.md](references/test-organization.md) |26| **Setting up test data/fixtures** | [fixtures-hooks.md](references/fixtures-hooks.md), [test-data.md](references/test-data.md) |27| **Handling authentication** | [fixtures-hooks.md](references/fixtures-hooks.md), [third-party.md](references/third-party.md) |28| **Testing date/time features** | [clock-mocking.md](references/clock-mocking.md) |29| **Testing file upload/download** | [file-operations.md](references/file-operations.md) |30| **Testing accessibility** | [accessibility.md](references/accessibility.md) |31| **Testing security (XSS, CSRF)** | [security-testing.md](references/security-testing.md) |32| **Using test annotations** | [annotations.md](references/annotations.md) |33| **Testing iframes** | [iframes.md](references/iframes.md) |34| **Testing canvas/WebGL** | [canvas-webgl.md](references/canvas-webgl.md) |35| **Internationalization (i18n)** | [i18n.md](references/i18n.md) |36| **Testing Electron apps** | [electron.md](references/electron.md) |37| **Testing browser extensions** | [browser-extensions.md](references/browser-extensions.md) |3839### Mobile & Responsive Testing4041**When to use**: Testing mobile devices, touch interactions, responsive layouts4243| Activity | Reference Files |44| ------------------------------- | ---------------------------------------------------------------------------------------- |45| **Device emulation** | [mobile-testing.md](references/mobile-testing.md) |46| **Touch gestures (swipe, tap)** | [mobile-testing.md](references/mobile-testing.md) |47| **Viewport/breakpoint testing** | [mobile-testing.md](references/mobile-testing.md) |48| **Mobile-specific UI** | [mobile-testing.md](references/mobile-testing.md), [locators.md](references/locators.md) |4950### Real-Time & Browser APIs5152**When to use**: Testing WebSockets, geolocation, permissions, multi-tab flows5354| Activity | Reference Files |55| ------------------------------- | -------------------------------------------------------------------------------------------- |56| **WebSocket/real-time testing** | [websockets.md](references/websockets.md) |57| **Geolocation mocking** | [browser-apis.md](references/browser-apis.md) |58| **Permission handling** | [browser-apis.md](references/browser-apis.md) |59| **Clipboard testing** | [browser-apis.md](references/browser-apis.md) |60| **Camera/microphone mocking** | [browser-apis.md](references/browser-apis.md) |61| **Multi-tab/popup flows** | [multi-context.md](references/multi-context.md) |62| **OAuth popup handling** | [third-party.md](references/third-party.md), [multi-context.md](references/multi-context.md) |6364### Debugging & Troubleshooting6566**When to use**: Test failures, element not found, timeouts, unexpected behavior6768| Activity | Reference Files |69| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |70| **Debugging test failures** | [debugging.md](references/debugging.md), [assertions-waiting.md](references/assertions-waiting.md) |71| **Fixing flaky tests** | [flaky-tests.md](references/flaky-tests.md), [debugging.md](references/debugging.md), [assertions-waiting.md](references/assertions-waiting.md) |72| **Debugging flaky parallel runs** | [flaky-tests.md](references/flaky-tests.md), [performance.md](references/performance.md), [fixtures-hooks.md](references/fixtures-hooks.md) |73| **Ensuring test isolation / avoiding state leak** | [flaky-tests.md](references/flaky-tests.md), [fixtures-hooks.md](references/fixtures-hooks.md), [performance.md](references/performance.md) |74| **Fixing selector issues** | [locators.md](references/locators.md), [debugging.md](references/debugging.md) |75| **Investigating timeout issues** | [assertions-waiting.md](references/assertions-waiting.md), [debugging.md](references/debugging.md) |76| **Using trace viewer** | [debugging.md](references/debugging.md) |77| **Debugging race conditions** | [flaky-tests.md](references/flaky-tests.md), [debugging.md](references/debugging.md), [assertions-waiting.md](references/assertions-waiting.md) |78| **Debugging console/JS errors** | [console-errors.md](references/console-errors.md), [debugging.md](references/debugging.md) |7980### Error & Edge Case Testing8182**When to use**: Testing error states, offline mode, network failures, validation8384| Activity | Reference Files |85| ------------------------------ | ------------------------------------------------------------------------------------------------------ |86| **Error boundary testing** | [error-testing.md](references/error-testing.md) |87| **Network failure simulation** | [error-testing.md](references/error-testing.md), [network-advanced.md](references/network-advanced.md) |88| **Offline mode testing** | [error-testing.md](references/error-testing.md), [service-workers.md](references/service-workers.md) |89| **Service worker testing** | [service-workers.md](references/service-workers.md) |90| **Loading state testing** | [error-testing.md](references/error-testing.md) |91| **Form validation testing** | [error-testing.md](references/error-testing.md) |9293### Multi-User & Collaboration Testing9495**When to use**: Testing features involving multiple users, roles, or real-time collaboration9697| Activity | Reference Files |98| ------------------------------ | ------------------------------------------------------------------------------------ |99| **Multiple users in one test** | [multi-user.md](references/multi-user.md) |100| **Real-time collaboration** | [multi-user.md](references/multi-user.md), [websockets.md](references/websockets.md) |101| **Role-based access testing** | [multi-user.md](references/multi-user.md) |102| **Concurrent action testing** | [multi-user.md](references/multi-user.md) |103104### Refactoring & Maintenance105106**When to use**: Improving existing tests, code review, reducing duplication107108| Activity | Reference Files |109| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |110| **Refactoring to Page Object Model** | [page-object-model.md](references/page-object-model.md), [test-organization.md](references/test-organization.md) |111| **Improving test organization** | [test-organization.md](references/test-organization.md), [page-object-model.md](references/page-object-model.md) |112| **Extracting common setup/teardown** | [fixtures-hooks.md](references/fixtures-hooks.md) |113| **Replacing brittle selectors** | [locators.md](references/locators.md) |114| **Removing explicit waits** | [assertions-waiting.md](references/assertions-waiting.md) |115| **Creating test data factories** | [test-data.md](references/test-data.md) |116117### Infrastructure & Configuration118119**When to use**: Setting up projects, configuring CI/CD, optimizing performance120121| Activity | Reference Files |122| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |123| **Configuring Playwright project** | [test-organization.md](references/test-organization.md), [projects-dependencies.md](references/projects-dependencies.md) |124| **Setting up CI/CD pipelines** | [ci-cd.md](references/ci-cd.md), [performance.md](references/performance.md) |125| **Global setup & teardown** | [global-setup.md](references/global-setup.md) |126| **Project dependencies** | [projects-dependencies.md](references/projects-dependencies.md) |127| **Optimizing test performance** | [performance.md](references/performance.md), [test-organization.md](references/test-organization.md) |128| **Configuring parallel execution** | [performance.md](references/performance.md) |129| **Isolating test data between workers** | [fixtures-hooks.md](references/fixtures-hooks.md), [performance.md](references/performance.md) |130| **Test coverage** | [test-coverage.md](references/test-coverage.md) |131132### Advanced Patterns133134**When to use**: Complex scenarios, API mocking, network interception135136| Activity | Reference Files |137| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |138| **Mocking API responses** | [test-organization.md](references/test-organization.md), [network-advanced.md](references/network-advanced.md) |139| **Network interception** | [network-advanced.md](references/network-advanced.md), [assertions-waiting.md](references/assertions-waiting.md) |140| **GraphQL mocking** | [network-advanced.md](references/network-advanced.md) |141| **HAR recording/playback** | [network-advanced.md](references/network-advanced.md) |142| **Custom fixtures** | [fixtures-hooks.md](references/fixtures-hooks.md) |143| **Advanced waiting strategies** | [assertions-waiting.md](references/assertions-waiting.md) |144| **OAuth/SSO mocking** | [third-party.md](references/third-party.md), [multi-context.md](references/multi-context.md) |145| **Payment gateway mocking** | [third-party.md](references/third-party.md) |146| **Email/SMS verification mocking** | [third-party.md](references/third-party.md) |147| **Failing on console errors** | [console-errors.md](references/console-errors.md) |148| **Security testing (XSS, CSRF)** | [security-testing.md](references/security-testing.md) |149| **Performance budgets & Web Vitals** | [performance-testing.md](references/performance-testing.md) |150| **Lighthouse integration** | [performance-testing.md](references/performance-testing.md) |151| **Test annotations (skip, fixme)** | [annotations.md](references/annotations.md) |152| **Test steps for reporting** | [annotations.md](references/annotations.md) |153154## Quick Decision Tree155156```157What are you doing?158│159├─ Writing a new test?160│ ├─ E2E test → test-organization.md, locators.md, assertions-waiting.md161│ ├─ Component test → component-testing.md162│ ├─ API test → test-organization.md, assertions-waiting.md163│ ├─ Visual/canvas test → canvas-webgl.md, test-organization.md164│ ├─ Accessibility test → accessibility.md165│ ├─ Mobile/responsive test → mobile-testing.md166│ ├─ i18n/locale test → i18n.md167│ ├─ Electron app test → electron.md168│ ├─ Browser extension test → browser-extensions.md169│ └─ Multi-user test → multi-user.md170│171├─ Testing specific features?172│ ├─ File upload/download → file-operations.md173│ ├─ Date/time dependent → clock-mocking.md174│ ├─ WebSocket/real-time → websockets.md175│ ├─ Geolocation/permissions → browser-apis.md176│ ├─ OAuth/SSO mocking → third-party.md, multi-context.md177│ ├─ Payments/email/SMS → third-party.md178│ ├─ iFrames → iframes.md179│ ├─ Canvas/WebGL/charts → canvas-webgl.md180│ ├─ Service workers/PWA → service-workers.md181│ ├─ i18n/localization → i18n.md182│ ├─ Security (XSS, CSRF) → security-testing.md183│ └─ Performance/Web Vitals → performance-testing.md184│185├─ Test is failing/flaky?186│ ├─ Flaky test investigation → flaky-tests.md187│ ├─ Element not found → locators.md, debugging.md188│ ├─ Timeout issues → assertions-waiting.md, debugging.md189│ ├─ Race conditions → flaky-tests.md, debugging.md190│ ├─ Flaky only with multiple workers → flaky-tests.md, performance.md191│ ├─ State leak / isolation → flaky-tests.md, fixtures-hooks.md192│ ├─ Console/JS errors → console-errors.md, debugging.md193│ └─ General debugging → debugging.md194│195├─ Testing error scenarios?196│ ├─ Network failures → error-testing.md, network-advanced.md197│ ├─ Offline (unexpected) → error-testing.md198│ ├─ Offline-first/PWA → service-workers.md199│ ├─ Error boundaries → error-testing.md200│ └─ Form validation → error-testing.md201│202├─ Refactoring existing code?203│ ├─ Implementing POM → page-object-model.md204│ ├─ Improving selectors → locators.md205│ ├─ Extracting fixtures → fixtures-hooks.md206│ └─ Creating data factories → test-data.md207│208├─ Setting up infrastructure?209│ ├─ CI/CD → ci-cd.md210│ ├─ Global setup/teardown → global-setup.md211│ ├─ Project dependencies → projects-dependencies.md212│ ├─ Test performance → performance.md213│ ├─ Test coverage → test-coverage.md214│ └─ Project config → test-organization.md, projects-dependencies.md215│216└─ Organizing tests?217 ├─ Skip/fixme/slow tests → annotations.md218 ├─ Test steps → annotations.md219 └─ Conditional execution → annotations.md220```221222## Test Validation Loop223224After writing or modifying tests:2252261. **Run tests**: `npx playwright test --reporter=list`2272. **If tests fail**:228 - Review error output and trace (`npx playwright show-trace`)229 - Fix locators, waits, or assertions230 - Re-run tests2313. **Only proceed when all tests pass**2324. **Run multiple times** for critical tests: `npx playwright test --repeat-each=5`
mediar-ai