playwright-best-practices

Category: 数据与AI | Uploader: currents-dev | Downloads: 0 | Version: v1.0（Latest）

Provides 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 upload/download, 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.

Changelog: Source: GitHub https://github.com/currents-dev/playwright-best-practices-skill

Directory Structure

Current level: Root

📁 references/
- 📄 accessibility.md 8.9 KB
- 📄 annotations.md 10.5 KB
- 📄 assertions-waiting.md 9.2 KB
- 📄 browser-apis.md 10.4 KB
- 📄 browser-extensions.md 13.5 KB
- 📄 canvas-webgl.md 12.8 KB
- 📄 ci-cd.md 8.5 KB
- 📄 clock-mocking.md 9.6 KB
- 📄 component-testing.md 11.4 KB
- 📄 console-errors.md 9.9 KB
- 📄 debugging.md 14.6 KB
- 📄 electron.md 13.2 KB
- 📄 error-testing.md 9.4 KB
- 📄 file-operations.md 10.1 KB
- 📄 fixtures-hooks.md 11.5 KB
- 📄 flaky-tests.md 14.7 KB
- 📄 global-setup.md 12.6 KB
- 📄 i18n.md 12.8 KB
- 📄 iframes.md 11.3 KB
- 📄 locators.md 6.4 KB
- 📄 mobile-testing.md 10.7 KB
- 📄 multi-context.md 8.4 KB
- 📄 multi-user.md 11.2 KB
- 📄 network-advanced.md 10.8 KB
- 📄 page-object-model.md 7.9 KB
- 📄 performance-testing.md 12.2 KB
- 📄 performance.md 11.5 KB
- 📄 projects-dependencies.md 8.7 KB
- 📄 security-testing.md 11.8 KB
- 📄 service-workers.md 13.5 KB
- 📄 test-coverage.md 12.4 KB
- 📄 test-data.md 11.8 KB
- 📄 test-organization.md 9.3 KB
- 📄 third-party.md 11.9 KB
- 📄 websockets.md 10.3 KB
📄 LICENSE.md 1.0 KB
📄 README.md 7.0 KB
📄 SKILL.md 20.6 KB

SKILL.md

---
name: playwright-best-practices
description: Provides 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 upload/download, 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.
license: MIT
metadata:
  author: currents.dev
  version: "1.0"
---

# 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](references/test-organization.md), [locators.md](references/locators.md), [assertions-waiting.md](references/assertions-waiting.md) |
| **Writing component tests**         | [component-testing.md](references/component-testing.md), [test-organization.md](references/test-organization.md)                                          |
| **Writing API tests**               | [test-organization.md](references/test-organization.md), [assertions-waiting.md](references/assertions-waiting.md)                                        |
| **Writing visual regression tests** | [test-organization.md](references/test-organization.md), [canvas-webgl.md](references/canvas-webgl.md)                                                    |
| **Structuring test code with POM**  | [page-object-model.md](references/page-object-model.md), [test-organization.md](references/test-organization.md)                                          |
| **Setting up test data/fixtures**   | [fixtures-hooks.md](references/fixtures-hooks.md), [test-data.md](references/test-data.md)                                                                |
| **Handling authentication**         | [fixtures-hooks.md](references/fixtures-hooks.md), [third-party.md](references/third-party.md)                                                            |
| **Testing date/time features**      | [clock-mocking.md](references/clock-mocking.md)                                                                                                           |
| **Testing file upload/download**    | [file-operations.md](references/file-operations.md)                                                                                                       |
| **Testing accessibility**           | [accessibility.md](references/accessibility.md)                                                                                                           |
| **Testing security (XSS, CSRF)**    | [security-testing.md](references/security-testing.md)                                                                                                     |
| **Using test annotations**          | [annotations.md](references/annotations.md)                                                                                                               |
| **Testing iframes**                 | [iframes.md](references/iframes.md)                                                                                                                       |
| **Testing canvas/WebGL**            | [canvas-webgl.md](references/canvas-webgl.md)                                                                                                             |
| **Internationalization (i18n)**     | [i18n.md](references/i18n.md)                                                                                                                             |
| **Testing Electron apps**           | [electron.md](references/electron.md)                                                                                                                     |
| **Testing browser extensions**      | [browser-extensions.md](references/browser-extensions.md)                                                                                                 |

### Mobile & Responsive Testing

**When to use**: Testing mobile devices, touch interactions, responsive layouts

| Activity                        | Reference Files                                                                          |
| ------------------------------- | ---------------------------------------------------------------------------------------- |
| **Device emulation**            | [mobile-testing.md](references/mobile-testing.md)                                        |
| **Touch gestures (swipe, tap)** | [mobile-testing.md](references/mobile-testing.md)                                        |
| **Viewport/breakpoint testing** | [mobile-testing.md](references/mobile-testing.md)                                        |
| **Mobile-specific UI**          | [mobile-testing.md](references/mobile-testing.md), [locators.md](references/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](references/websockets.md)                                                    |
| **Geolocation mocking**         | [browser-apis.md](references/browser-apis.md)                                                |
| **Permission handling**         | [browser-apis.md](references/browser-apis.md)                                                |
| **Clipboard testing**           | [browser-apis.md](references/browser-apis.md)                                                |
| **Camera/microphone mocking**   | [browser-apis.md](references/browser-apis.md)                                                |
| **Multi-tab/popup flows**       | [multi-context.md](references/multi-context.md)                                              |
| **OAuth popup handling**        | [third-party.md](references/third-party.md), [multi-context.md](references/multi-context.md) |

### Debugging & Troubleshooting

**When to use**: Test failures, element not found, timeouts, unexpected behavior

| Activity                                          | Reference Files                                                                                                                                 |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **Debugging test failures**                       | [debugging.md](references/debugging.md), [assertions-waiting.md](references/assertions-waiting.md)                                              |
| **Fixing flaky tests**                            | [flaky-tests.md](references/flaky-tests.md), [debugging.md](references/debugging.md), [assertions-waiting.md](references/assertions-waiting.md) |
| **Debugging flaky parallel runs**                 | [flaky-tests.md](references/flaky-tests.md), [performance.md](references/performance.md), [fixtures-hooks.md](references/fixtures-hooks.md)     |
| **Ensuring test isolation / avoiding state leak** | [flaky-tests.md](references/flaky-tests.md), [fixtures-hooks.md](references/fixtures-hooks.md), [performance.md](references/performance.md)     |
| **Fixing selector issues**                        | [locators.md](references/locators.md), [debugging.md](references/debugging.md)                                                                  |
| **Investigating timeout issues**                  | [assertions-waiting.md](references/assertions-waiting.md), [debugging.md](references/debugging.md)                                              |
| **Using trace viewer**                            | [debugging.md](references/debugging.md)                                                                                                         |
| **Debugging race conditions**                     | [flaky-tests.md](references/flaky-tests.md), [debugging.md](references/debugging.md), [assertions-waiting.md](references/assertions-waiting.md) |
| **Debugging console/JS errors**                   | [console-errors.md](references/console-errors.md), [debugging.md](references/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](references/error-testing.md)                                                        |
| **Network failure simulation** | [error-testing.md](references/error-testing.md), [network-advanced.md](references/network-advanced.md) |
| **Offline mode testing**       | [error-testing.md](references/error-testing.md), [service-workers.md](references/service-workers.md)   |
| **Service worker testing**     | [service-workers.md](references/service-workers.md)                                                    |
| **Loading state testing**      | [error-testing.md](references/error-testing.md)                                                        |
| **Form validation testing**    | [error-testing.md](references/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](references/multi-user.md)                                            |
| **Real-time collaboration**    | [multi-user.md](references/multi-user.md), [websockets.md](references/websockets.md) |
| **Role-based access testing**  | [multi-user.md](references/multi-user.md)                                            |
| **Concurrent action testing**  | [multi-user.md](references/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](references/page-object-model.md), [test-organization.md](references/test-organization.md) |
| **Improving test organization**      | [test-organization.md](references/test-organization.md), [page-object-model.md](references/page-object-model.md) |
| **Extracting common setup/teardown** | [fixtures-hooks.md](references/fixtures-hooks.md)                                                                |
| **Replacing brittle selectors**      | [locators.md](references/locators.md)                                                                            |
| **Removing explicit waits**          | [assertions-waiting.md](references/assertions-waiting.md)                                                        |
| **Creating test data factories**     | [test-data.md](references/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](references/test-organization.md), [projects-dependencies.md](references/projects-dependencies.md) |
| **Setting up CI/CD pipelines**          | [ci-cd.md](references/ci-cd.md), [performance.md](references/performance.md)                                             |
| **Global setup & teardown**             | [global-setup.md](references/global-setup.md)                                                                            |
| **Project dependencies**                | [projects-dependencies.md](references/projects-dependencies.md)                                                          |
| **Optimizing test performance**         | [performance.md](references/performance.md), [test-organization.md](references/test-organization.md)                     |
| **Configuring parallel execution**      | [performance.md](references/performance.md)                                                                              |
| **Isolating test data between workers** | [fixtures-hooks.md](references/fixtures-hooks.md), [performance.md](references/performance.md)                           |
| **Test coverage**                       | [test-coverage.md](references/test-coverage.md)                                                                          |

### Advanced Patterns

**When to use**: Complex scenarios, API mocking, network interception

| Activity                             | Reference Files                                                                                                  |
| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| **Mocking API responses**            | [test-organization.md](references/test-organization.md), [network-advanced.md](references/network-advanced.md)   |
| **Network interception**             | [network-advanced.md](references/network-advanced.md), [assertions-waiting.md](references/assertions-waiting.md) |
| **GraphQL mocking**                  | [network-advanced.md](references/network-advanced.md)                                                            |
| **HAR recording/playback**           | [network-advanced.md](references/network-advanced.md)                                                            |
| **Custom fixtures**                  | [fixtures-hooks.md](references/fixtures-hooks.md)                                                                |
| **Advanced waiting strategies**      | [assertions-waiting.md](references/assertions-waiting.md)                                                        |
| **OAuth/SSO mocking**                | [third-party.md](references/third-party.md), [multi-context.md](references/multi-context.md)                     |
| **Payment gateway mocking**          | [third-party.md](references/third-party.md)                                                                      |
| **Email/SMS verification mocking**   | [third-party.md](references/third-party.md)                                                                      |
| **Failing on console errors**        | [console-errors.md](references/console-errors.md)                                                                |
| **Security testing (XSS, CSRF)**     | [security-testing.md](references/security-testing.md)                                                            |
| **Performance budgets & Web Vitals** | [performance-testing.md](references/performance-testing.md)                                                      |
| **Lighthouse integration**           | [performance-testing.md](references/performance-testing.md)                                                      |
| **Test annotations (skip, fixme)**   | [annotations.md](references/annotations.md)                                                                      |
| **Test steps for reporting**         | [annotations.md](references/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:

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`

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

playwright-best-practices

Directory Structure

SKILL.md

Report

Notice