AGENT SKILL

playwright-best-practices

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
所属仓库
BigSimmo/PsychSift
最近更新
2026-11-13
Stars
★ 1
Forks
0

01 前言 Front Matter

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

02 资源文件 58

03 SKILL.md 正文

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:

  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

04 同仓库更多 Skills

BigSimmo
BigSimmo/PsychSift

supabase-postgres-best-practices

Postgres performance optimization and best practices from Supabase. Use this skill when writing, reviewing, or optimizing Postgres queries, schema designs, or database configurations.

★ 1
BigSimmo
BigSimmo/PsychSift

cursor-codebase-indexing

Set up and optimize Cursor codebase indexing for semantic code search and @Codebase queries. Triggers on "cursor index", "codebase indexing", "index codebase", "cursor semantic search", "@codebase", "cursor embeddings".

★ 1
BigSimmo
BigSimmo/PsychSift

vercel-react-best-practices

React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.

★ 1
BigSimmo
BigSimmo/PsychSift

vercel-composition-patterns

React composition patterns that scale. Use when refactoring components with boolean prop proliferation, building flexible component libraries, or designing reusable APIs. Triggers on tasks involving compound components, render props, context providers, or component architecture. Includes React 19 API changes.

★ 1
BigSimmo
BigSimmo/PsychSift

supabase-postgres-best-practices

Postgres performance optimization and best practices from Supabase. Use this skill when writing, reviewing, or optimizing Postgres queries, schema designs, or database configurations.

★ 1
BigSimmo
BigSimmo/PsychSift

sentry-nextjs-sdk

Full Sentry SDK setup for Next.js. Use when asked to "add Sentry to Next.js", "install @sentry/nextjs", or configure error monitoring, tracing, session replay, logging, profiling, AI monitoring, or crons for Next.js applications. Supports Next.js 13+ with App Router and Pages Router.

★ 1