playwright-best-practices

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 testing.

Install with Tessl CLI

npx tessl i github:currents-dev/playwright-best-practices-skill --skill playwright-best-practices

What are skills?

Overall
score

18%

Review — 0%

Does it follow best practices?

If you maintain this skill, you can automatically optimize it using the tessl CLI to improve its score:

npx tessl skill review --optimize ./path/to/skill

Learn more

Validation — 10 / 11 Passed

Validation for skill structure

Validation failed for this skill

This skill has errors that need to be fixed before it can move to Implementation and Discovery review.

SKILL.md

Review

Evals

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

Repository: github.com/currents-dev/playwright-best-practices-skill
Last updated: 1 day ago
Created: 1 day ago

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.