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
1---
2name: playwright-best-practices
3description: 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), test tags (@smoke, @fast, @critical, filtering with --grep), 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 testing.
4license: MIT
5metadata:
6 source: https://skillmd.com/skills/currents-dev/playwright-best-practices
7 author: currents.dev
8 version: "1.2"
9---
10
11# Playwright Best Practices
12
13This skill provides comprehensive guidance for all aspects of Playwright test development, from writing new tests to debugging and maintaining existing test suites.
14
15## Activity-Based Reference Guide
16
17Consult these references based on what you're doing:
18
19### Writing New Tests
20
21**When to use**: Creating new test files, writing test cases, implementing test scenarios
22
23| Activity | Reference Files |
24| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
25| **Writing E2E tests** | [test-suite-structure.md](core/test-suite-structure.md), [locators.md](core/locators.md), [assertions-waiting.md](core/assertions-waiting.md) |
26| **Writing component tests** | [component-testing.md](testing-patterns/component-testing.md), [test-suite-structure.md](core/test-suite-structure.md) |
27| **Writing API tests** | [api-testing.md](testing-patterns/api-testing.md), [test-suite-structure.md](core/test-suite-structure.md) |
28| **Writing GraphQL tests** | [graphql-testing.md](testing-patterns/graphql-testing.md), [api-testing.md](testing-patterns/api-testing.md) |
29| **Writing visual regression tests** | [visual-regression.md](testing-patterns/visual-regression.md), [canvas-webgl.md](testing-patterns/canvas-webgl.md) |
30| **Structuring test code with POM** | [page-object-model.md](core/page-object-model.md), [test-suite-structure.md](core/test-suite-structure.md) |
31| **Setting up test data/fixtures** | [fixtures-hooks.md](core/fixtures-hooks.md), [test-data.md](core/test-data.md) |
32| **Handling authentication** | [authentication.md](advanced/authentication.md), [authentication-flows.md](advanced/authentication-flows.md) |
33| **Testing date/time features** | [clock-mocking.md](advanced/clock-mocking.md) |
34| **Testing file upload/download** | [file-operations.md](testing-patterns/file-operations.md), [file-upload-download.md](testing-patterns/file-upload-download.md) |
35| **Testing forms/validation** | [forms-validation.md](testing-patterns/forms-validation.md) |
36| **Testing drag and drop** | [drag-drop.md](testing-patterns/drag-drop.md) |
37| **Testing accessibility** | [accessibility.md](testing-patterns/accessibility.md) |
38| **Testing security (XSS, CSRF)** | [security-testing.md](testing-patterns/security-testing.md) |
39| **Using test annotations** | [annotations.md](core/annotations.md) |
40| **Using test tags** | [test-tags.md](core/test-tags.md) |
41| **Testing iframes** | [iframes.md](browser-apis/iframes.md) |
42| **Testing canvas/WebGL** | [canvas-webgl.md](testing-patterns/canvas-webgl.md) |
43| **Internationalization (i18n)** | [i18n.md](testing-patterns/i18n.md) |
44| **Testing Electron apps** | [electron.md](testing-patterns/electron.md) |
45| **Testing browser extensions** | [browser-extensions.md](testing-patterns/browser-extensions.md) |
46
47### Mobile & Responsive Testing
48
49**When to use**: Testing mobile devices, touch interactions, responsive layouts
50
51| Activity | Reference Files |
52| ------------------------------- | -------------------------------------------------------------------------------- |
53| **Device emulation** | [mobile-testing.md](advanced/mobile-testing.md) |
54| **Touch gestures (swipe, tap)** | [mobile-testing.md](advanced/mobile-testing.md) |
55| **Viewport/breakpoint testing** | [mobile-testing.md](advanced/mobile-testing.md) |
56| **Mobile-specific UI** | [mobile-testing.md](advanced/mobile-testing.md), [locators.md](core/locators.md) |
57
58### Real-Time & Browser APIs
59
60**When to use**: Testing WebSockets, geolocation, permissions, multi-tab flows
61
62| Activity | Reference Files |
63| ------------------------------- | ---------------------------------------------------------------------------------------- |
64| **WebSocket/real-time testing** | [websockets.md](browser-apis/websockets.md) |
65| **Geolocation mocking** | [browser-apis.md](browser-apis/browser-apis.md) |
66| **Permission handling** | [browser-apis.md](browser-apis/browser-apis.md) |
67| **Clipboard testing** | [browser-apis.md](browser-apis/browser-apis.md) |
68| **Camera/microphone mocking** | [browser-apis.md](browser-apis/browser-apis.md) |
69| **Multi-tab/popup flows** | [multi-context.md](advanced/multi-context.md) |
70| **OAuth popup handling** | [third-party.md](advanced/third-party.md), [multi-context.md](advanced/multi-context.md) |
71
72### Debugging & Troubleshooting
73
74**When to use**: Test failures, element not found, timeouts, unexpected behavior
75
76| Activity | Reference Files |
77| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
78| **Debugging test failures** | [debugging.md](debugging/debugging.md), [assertions-waiting.md](core/assertions-waiting.md) |
79| **Fixing flaky tests** | [flaky-tests.md](debugging/flaky-tests.md), [debugging.md](debugging/debugging.md), [assertions-waiting.md](core/assertions-waiting.md) |
80| **Debugging flaky parallel runs** | [flaky-tests.md](debugging/flaky-tests.md), [performance.md](infrastructure-ci-cd/performance.md), [fixtures-hooks.md](core/fixtures-hooks.md) |
81| **Ensuring test isolation / avoiding state leak** | [flaky-tests.md](debugging/flaky-tests.md), [fixtures-hooks.md](core/fixtures-hooks.md), [performance.md](infrastructure-ci-cd/performance.md) |
82| **Fixing selector issues** | [locators.md](core/locators.md), [debugging.md](debugging/debugging.md) |
83| **Investigating timeout issues** | [assertions-waiting.md](core/assertions-waiting.md), [debugging.md](debugging/debugging.md) |
84| **Using trace viewer** | [debugging.md](debugging/debugging.md) |
85| **Debugging race conditions** | [flaky-tests.md](debugging/flaky-tests.md), [debugging.md](debugging/debugging.md), [assertions-waiting.md](core/assertions-waiting.md) |
86| **Debugging console/JS errors** | [console-errors.md](debugging/console-errors.md), [debugging.md](debugging/debugging.md) |
87
88### Error & Edge Case Testing
89
90**When to use**: Testing error states, offline mode, network failures, validation
91
92| Activity | Reference Files |
93| ------------------------------ | ----------------------------------------------------------------------------------------------------- |
94| **Error boundary testing** | [error-testing.md](debugging/error-testing.md) |
95| **Network failure simulation** | [error-testing.md](debugging/error-testing.md), [network-advanced.md](advanced/network-advanced.md) |
96| **Offline mode testing** | [error-testing.md](debugging/error-testing.md), [service-workers.md](browser-apis/service-workers.md) |
97| **Service worker testing** | [service-workers.md](browser-apis/service-workers.md) |
98| **Loading state testing** | [error-testing.md](debugging/error-testing.md) |
99| **Form validation testing** | [error-testing.md](debugging/error-testing.md) |
100
101### Multi-User & Collaboration Testing
102
103**When to use**: Testing features involving multiple users, roles, or real-time collaboration
104
105| Activity | Reference Files |
106| ------------------------------ | ------------------------------------------------------------------------------------ |
107| **Multiple users in one test** | [multi-user.md](advanced/multi-user.md) |
108| **Real-time collaboration** | [multi-user.md](advanced/multi-user.md), [websockets.md](browser-apis/websockets.md) |
109| **Role-based access testing** | [multi-user.md](advanced/multi-user.md) |
110| **Concurrent action testing** | [multi-user.md](advanced/multi-user.md) |
111
112### Architecture Decisions
113
114**When to use**: Choosing test patterns, deciding between approaches, planning test architecture
115
116| Activity | Reference Files |
117| ---------------------------- | --------------------------------------------------------- |
118| **POM vs fixtures decision** | [pom-vs-fixtures.md](architecture/pom-vs-fixtures.md) |
119| **Test type selection** | [test-architecture.md](architecture/test-architecture.md) |
120| **Mock vs real services** | [when-to-mock.md](architecture/when-to-mock.md) |
121| **Test suite structure** | [test-suite-structure.md](core/test-suite-structure.md) |
122
123### Framework-Specific Testing
124
125**When to use**: Testing React, Angular, Vue, or Next.js applications
126
127| Activity | Reference Files |
128| ------------------------- | ----------------------------------- |
129| **Testing React apps** | [react.md](frameworks/react.md) |
130| **Testing Angular apps** | [angular.md](frameworks/angular.md) |
131| **Testing Vue/Nuxt apps** | [vue.md](frameworks/vue.md) |
132| **Testing Next.js apps** | [nextjs.md](frameworks/nextjs.md) |
133
134### Refactoring & Maintenance
135
136**When to use**: Improving existing tests, code review, reducing duplication
137
138| Activity | Reference Files |
139| ------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
140| **Refactoring to Page Object Model** | [page-object-model.md](core/page-object-model.md), [test-suite-structure.md](core/test-suite-structure.md) |
141| **Improving test organization** | [test-suite-structure.md](core/test-suite-structure.md), [page-object-model.md](core/page-object-model.md) |
142| **Extracting common setup/teardown** | [fixtures-hooks.md](core/fixtures-hooks.md) |
143| **Replacing brittle selectors** | [locators.md](core/locators.md) |
144| **Removing explicit waits** | [assertions-waiting.md](core/assertions-waiting.md) |
145| **Creating test data factories** | [test-data.md](core/test-data.md) |
146| **Configuration setup** | [configuration.md](core/configuration.md) |
147
148### Infrastructure & Configuration
149
150**When to use**: Setting up projects, configuring CI/CD, optimizing performance
151
152| Activity | Reference Files |
153| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
154| **Configuring Playwright project** | [configuration.md](core/configuration.md), [projects-dependencies.md](core/projects-dependencies.md) |
155| **Setting up CI/CD pipelines** | [ci-cd.md](infrastructure-ci-cd/ci-cd.md), [github-actions.md](infrastructure-ci-cd/github-actions.md) |
156| **GitHub Actions setup** | [github-actions.md](infrastructure-ci-cd/github-actions.md) |
157| **GitLab CI setup** | [gitlab.md](infrastructure-ci-cd/gitlab.md) |
158| **Other CI providers** | [other-providers.md](infrastructure-ci-cd/other-providers.md) |
159| **Docker/container setup** | [docker.md](infrastructure-ci-cd/docker.md) |
160| **Global setup & teardown** | [global-setup.md](core/global-setup.md) |
161| **Project dependencies** | [projects-dependencies.md](core/projects-dependencies.md) |
162| **Optimizing test performance** | [performance.md](infrastructure-ci-cd/performance.md), [test-suite-structure.md](core/test-suite-structure.md) |
163| **Configuring parallel execution** | [parallel-sharding.md](infrastructure-ci-cd/parallel-sharding.md), [performance.md](infrastructure-ci-cd/performance.md) |
164| **Isolating test data between workers** | [fixtures-hooks.md](core/fixtures-hooks.md), [performance.md](infrastructure-ci-cd/performance.md) |
165| **Test coverage** | [test-coverage.md](infrastructure-ci-cd/test-coverage.md) |
166| **Test reporting/artifacts** | [reporting.md](infrastructure-ci-cd/reporting.md) |
167
168### Advanced Patterns
169
170**When to use**: Complex scenarios, API mocking, network interception
171
172| Activity | Reference Files |
173| ------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
174| **Mocking API responses** | [test-suite-structure.md](core/test-suite-structure.md), [network-advanced.md](advanced/network-advanced.md) |
175| **Network interception** | [network-advanced.md](advanced/network-advanced.md), [assertions-waiting.md](core/assertions-waiting.md) |
176| **GraphQL mocking** | [network-advanced.md](advanced/network-advanced.md) |
177| **HAR recording/playback** | [network-advanced.md](advanced/network-advanced.md) |
178| **Custom fixtures** | [fixtures-hooks.md](core/fixtures-hooks.md) |
179| **Advanced waiting strategies** | [assertions-waiting.md](core/assertions-waiting.md) |
180| **OAuth/SSO mocking** | [third-party.md](advanced/third-party.md), [multi-context.md](advanced/multi-context.md) |
181| **Payment gateway mocking** | [third-party.md](advanced/third-party.md) |
182| **Email/SMS verification mocking** | [third-party.md](advanced/third-party.md) |
183| **Failing on console errors** | [console-errors.md](debugging/console-errors.md) |
184| **Security testing (XSS, CSRF)** | [security-testing.md](testing-patterns/security-testing.md) |
185| **Performance budgets & Web Vitals** | [performance-testing.md](testing-patterns/performance-testing.md) |
186| **Lighthouse integration** | [performance-testing.md](testing-patterns/performance-testing.md) |
187| **Test annotations (skip, fixme)** | [annotations.md](core/annotations.md) |
188| **Test tags (@smoke, @fast)** | [test-tags.md](core/test-tags.md) |
189| **Test steps for reporting** | [annotations.md](core/annotations.md) |
190
191## Quick Decision Tree
192
193```
194What are you doing?
195│
196├─ Writing a new test?
197│ ├─ E2E test → core/test-suite-structure.md, core/locators.md, core/assertions-waiting.md
198│ ├─ Component test → testing-patterns/component-testing.md
199│ ├─ API test → testing-patterns/api-testing.md, core/test-suite-structure.md
200│ ├─ GraphQL test → testing-patterns/graphql-testing.md
201│ ├─ Visual regression → testing-patterns/visual-regression.md
202│ ├─ Visual/canvas test → testing-patterns/canvas-webgl.md, core/test-suite-structure.md
203│ ├─ Accessibility test → testing-patterns/accessibility.md
204│ ├─ Mobile/responsive test → advanced/mobile-testing.md
205│ ├─ i18n/locale test → testing-patterns/i18n.md
206│ ├─ Electron app test → testing-patterns/electron.md
207│ ├─ Browser extension test → testing-patterns/browser-extensions.md
208│ ├─ Multi-user test → advanced/multi-user.md
209│ ├─ Form validation test → testing-patterns/forms-validation.md
210│ └─ Drag and drop test → testing-patterns/drag-drop.md
211│
212├─ Testing specific features?
213│ ├─ File upload/download → testing-patterns/file-operations.md, testing-patterns/file-upload-download.md
214│ ├─ Date/time dependent → advanced/clock-mocking.md
215│ ├─ WebSocket/real-time → browser-apis/websockets.md
216│ ├─ Geolocation/permissions → browser-apis/browser-apis.md
217│ ├─ OAuth/SSO mocking → advanced/third-party.md, advanced/multi-context.md
218│ ├─ Payments/email/SMS → advanced/third-party.md
219│ ├─ iFrames → browser-apis/iframes.md
220│ ├─ Canvas/WebGL/charts → testing-patterns/canvas-webgl.md
221│ ├─ Service workers/PWA → browser-apis/service-workers.md
222│ ├─ i18n/localization → testing-patterns/i18n.md
223│ ├─ Security (XSS, CSRF) → testing-patterns/security-testing.md
224│ └─ Performance/Web Vitals → testing-patterns/performance-testing.md
225│
226├─ Architecture decisions?
227│ ├─ POM vs fixtures → architecture/pom-vs-fixtures.md
228│ ├─ Test type selection → architecture/test-architecture.md
229│ ├─ Mock vs real services → architecture/when-to-mock.md
230│ └─ Test suite structure → core/test-suite-structure.md
231│
232├─ Framework-specific testing?
233│ ├─ React app → frameworks/react.md
234│ ├─ Angular app → frameworks/angular.md
235│ ├─ Vue/Nuxt app → frameworks/vue.md
236│ └─ Next.js app → frameworks/nextjs.md
237│
238├─ Authentication testing?
239│ ├─ Basic auth patterns → advanced/authentication.md
240│ └─ Complex flows (MFA, reset) → advanced/authentication-flows.md
241│
242├─ Test is failing/flaky?
243│ ├─ Flaky test investigation → debugging/flaky-tests.md
244│ ├─ Element not found → core/locators.md, debugging/debugging.md
245│ ├─ Timeout issues → core/assertions-waiting.md, debugging/debugging.md
246│ ├─ Race conditions → debugging/flaky-tests.md, debugging/debugging.md
247│ ├─ Flaky only with multiple workers → debugging/flaky-tests.md, infrastructure-ci-cd/performance.md
248│ ├─ State leak / isolation → debugging/flaky-tests.md, core/fixtures-hooks.md
249│ ├─ Console/JS errors → debugging/console-errors.md, debugging/debugging.md
250│ └─ General debugging → debugging/debugging.md
251│
252├─ Testing error scenarios?
253│ ├─ Network failures → debugging/error-testing.md, advanced/network-advanced.md
254│ ├─ Offline (unexpected) → debugging/error-testing.md
255│ ├─ Offline-first/PWA → browser-apis/service-workers.md
256│ ├─ Error boundaries → debugging/error-testing.md
257│ └─ Form validation → testing-patterns/forms-validation.md, debugging/error-testing.md
258│
259├─ Refactoring existing code?
260│ ├─ Implementing POM → core/page-object-model.md
261│ ├─ Improving selectors → core/locators.md
262│ ├─ Extracting fixtures → core/fixtures-hooks.md
263│ ├─ Creating data factories → core/test-data.md
264│ └─ Configuration setup → core/configuration.md
265│
266├─ Setting up infrastructure?
267│ ├─ CI/CD → infrastructure-ci-cd/ci-cd.md
268│ ├─ GitHub Actions → infrastructure-ci-cd/github-actions.md
269│ ├─ GitLab CI → infrastructure-ci-cd/gitlab.md
270│ ├─ Other CI providers → infrastructure-ci-cd/other-providers.md
271│ ├─ Docker/containers → infrastructure-ci-cd/docker.md
272│ ├─ Sharding/parallel → infrastructure-ci-cd/parallel-sharding.md
273│ ├─ Reporting/artifacts → infrastructure-ci-cd/reporting.md
274│ ├─ Global setup/teardown → core/global-setup.md
275│ ├─ Project dependencies → core/projects-dependencies.md
276│ ├─ Test performance → infrastructure-ci-cd/performance.md
277│ ├─ Test coverage → infrastructure-ci-cd/test-coverage.md
278│ └─ Project config → core/configuration.md, core/projects-dependencies.md
279│
280├─ Organizing tests?
281│ ├─ Skip/fixme/slow tests → core/annotations.md
282│ ├─ Test tags (@smoke, @fast) → core/test-tags.md
283│ ├─ Filtering tests (--grep) → core/test-tags.md
284│ ├─ Test steps → core/annotations.md
285│ └─ Conditional execution → core/annotations.md
286│
287└─ Running subset of tests?
288 ├─ By tag (@smoke, @critical) → core/test-tags.md
289 ├─ Exclude slow/flaky tests → core/test-tags.md
290 ├─ PR vs nightly tests → core/test-tags.md, infrastructure-ci-cd/ci-cd.md
291 └─ Project-specific filtering → core/test-tags.md, core/configuration.md
292```
293
294## Test Validation Loop
295
296After writing or modifying tests:
297
2981. **Run tests**: `npx playwright test --reporter=list`
2992. **If tests fail**:
300 - Review error output and trace (`npx playwright show-trace`)
301 - Fix locators, waits, or assertions
302 - Re-run tests
3033. **Only proceed when all tests pass**
3044. **Run multiple times** for critical tests: `npx playwright test --repeat-each=5`