playwright-best-practices

name	playwright-best-practices
description	Code-generation skill for writing, debugging, and hardening Playwright tests in this repo. Use only when creating or changing automated tests and related test infrastructure.
license	MIT
metadata	{"author":"currents.dev","version":"1.1"}

Playwright Best Practices

This is a code-generation skill. Use it only for test implementation and debugging work.

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:

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