---

name: playwright-best-practices description: 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. license: MIT metadata: author: currents.dev version: "1.2"

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