Labsco
sanity-io logo

playwright-best-practices

★ 6,200

by sanity-io · part of sanity-io/sanity

Use when writing Playwright tests, fixing flaky tests, debugging failures, implementing Page Object Model, configuring CI/CD, optimizing performance, mocking…

🔥🔥🔥🔥✓ VerifiedFreeQuick setup
#email#payments#scraping#devops#git#maps#security
🧰 Not standalone. This skill ships with sanity-io/sanity and only works together with that tool — install the tool first, then add this skill.

Use when writing Playwright tests, fixing flaky tests, debugging failures, implementing Page Object Model, configuring CI/CD, optimizing performance, mocking…

Inspect the full instructions your agent will receiveExpand

This is the exact playbook injected into your agent when the skill activates — shown here so you can audit it before installing. You don't need to read it to use the skill.

by sanity-io

Use when writing Playwright tests, fixing flaky tests, debugging failures, implementing Page Object Model, configuring CI/CD, optimizing performance, mocking… npx skills add https://github.com/sanity-io/sanity --skill playwright-best-practices Download ZIPGitHub6.2k

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

Copy & paste — that's it
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