Skip to content
Skills Library
Programming · Testing

playwright

/playwright

Playwright testing best practices for Next.js applications (formerly test-playwright). This skill should be used when writing, reviewing, or debugging E2E tests with Playwright. Triggers on tasks involving test selectors, flaky tests, authentication state, API mocking, hydration testing, parallel execution, CI configuration, or debugging test failures.

Repository
dotfiles ↗
Licence
MIT
Last repository change
26.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
48
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Playwright testing best practices for Next.js applications (formerly test-playwright). This skill should be used when writing, reviewing, or debugging E2E tests with Playwright. Triggers on tasks involving test selectors, flaky tests, authentication state, API mocking, hydration testing, parallel execution, CI configuration, or debugging test failures.

Original author description

Playwright testing best practices for Next.js applications (formerly test-playwright). This skill should be used when writing, reviewing, or debugging E2E tests with Playwright. Triggers on tasks involving test selectors, flaky tests, authentication state, API mocking, hydration testing, parallel execution, CI configuration, or debugging test failures.

How it works

  1. When to Apply
  2. Rule Categories by Priority
  3. Quick Reference
  4. How to Use
  5. Reference Files
Original SKILL.md headings · 114 lines, 656 words
SKILL.md preview
---
name: playwright
description: Playwright testing best practices for Next.js applications (formerly test-playwright). This skill should be used when writing, reviewing, or debugging E2E tests with Playwright. Triggers on tasks involving test selectors, flaky tests, authentication state, API mocking, hydration testing, parallel execution, CI configuration, or debugging test failures.
---

# Playwright + Next.js Testing Best Practices

Comprehensive testing optimization guide for Playwright with Next.js applications. Contains 43 rules across 8 categories, prioritized by impact to guide reliable, fast, and maintainable E2E tests.

## When to Apply

Reference these guidelines when:
- Writing new Playwright tests for Next.js apps
- Debugging flaky or failing tests
- Optimizing test execution speed
- Setting up authentication state reuse
- Configuring CI/CD pipelines for testing
- Testing Server Components and App Router features
- Reviewing test code for reliability issues

## Rule Categories by Priority

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | Test Architecture | CRITICAL | `arch-` |
| 2 | Selectors & Locators | CRITICAL | `loc-` |
| 3 | Waiting & Assertions | HIGH | `wait-` |
| 4 | Authentication & State | HIGH | `auth-` |
| 5 | Mocking & Network | MEDIUM-HIGH | `mock-` |
| 6 | Next.js Integration | MEDIUM | `next-` |
| 7 | Performance & Speed | MEDIUM | `perf-` |
| 8 | Debugging & CI | LOW-MEDIUM | `debug-` |

## Quick Reference

### 1. Test Architecture (CRITICAL)

- [`arch-test-isolation`](references/arch-test-isolation.md) - Use fresh browser context for each test
- [`arch-parallel-execution`](references/arch-parallel-execution.md) - Enable parallel test execution
- [`arch-page-object-model`](references/arch-page-object-model.md) - Use Page Object Model for complex pages
- [`arch-fixtures`](references/arch-fixtures.md) - Use fixtures for shared setup
- [`arch-test-production`](references/arch-test-production.md) - Test against production builds
- [`arch-cleanup-state`](references/arch-cleanup-state.md) - Clean up test state after each test

### 2. Selectors & Locators (CRITICAL)

- [`loc-role-selectors`](references/loc-role-selectors.md) - Use role-based selectors over CSS
- [`loc-data-testid`](references/loc-data-testid.md) - Use data-testid for dynamic elements
- [`loc-label-selectors`](references/loc-label-selectors.md) - Use getByLabel for form inputs
- [`loc-text-selectors`](references/loc-text-selectors.md) - Use getByText for static content
- [`loc-avoid-xpath`](references/loc-avoid-xpath.md) - Avoid XPath selectors
- [`loc-chained-locators`](references/loc-chained-locators.md) - Chain locators for specificity
- [`loc-placeholder-selector`](references/loc-placeholder-selector.md) - Use getByPlaceholder sparingly

### 3. Waiting & Assertions (HIGH)

- [`wait-web-first-assertions`](references/wait-web-first-assertions.md) - Use web-first assertions
- [`wait-avoid-hard-waits`](references/wait-avoid-hard-waits.md) - Avoid hard waits
- [`wait-network-idle`](references/wait-network-idle.md) - Use network idle for complex pages
- [`wait-action-retries`](references/wait-action-retries.md) - Let actions auto-wait before interacting
- [`wait-soft-assertions`](references/wait-soft-assertions.md) - Use soft assertions for non-critical checks
- [`wait-custom-timeout`](references/wait-custom-timeout.md) - Configure timeouts appropriately

### 4. Authentication & State (HIGH)

- [`auth-storage-state`](references/auth-storage-state.md) - Reuse authentication with storage state
- [`auth-multiple-roles`](references/auth-multiple-roles.md) - Use separate storage states for different roles
- [`auth-session-storage`](references/auth-session-storage.md) - Handle session storage for auth
- [`auth-api-login`](references/auth-api-login.md) - Use API login for faster auth setup
- [`auth-parallel-workers`](references/auth-parallel-workers.md) - Use worker-scoped auth for parallel tests

### 5. Mocking & Network (MEDIUM-HIGH)

- [`mock-api-responses`](references/mock-api-responses.md) - Mock API responses for deterministic tests
- [`mock-intercept-modify`](references/mock-intercept-modify.md) - Intercept and modify real responses
- [`mock-har-files`](references/mock-har-files.md) - Use HAR files for complex mock scenarios
- [`mock-abort-requests`](references/mock-abort-requests.md) - Abort unnecessary requests
- [`mock-network-conditions`](references/mock-network-conditions.md) - Simulate network conditions

### 6. Next.js Integration (MEDIUM)

- [`next-wait-hydration`](references/next-wait-hydration.md) - Wait for hydration before interacting
- [`next-server-components`](references/next-server-components.md) - Test server components correctly
- [`next-app-router-navigation`](references/next-app-router-navigation.md) - Test App Router navigation patterns
- [`next-server-actions`](references/next-server-actions.md) - Test server actions end-to-end
- [`next-baseurl-config`](references/next-baseurl-config.md) - Configure baseURL for clean navigation

### 7. Performance & Speed (MEDIUM)

- [`perf-sharding`](references/perf-sharding.md) - Use sharding for large test suites
- [`perf-headless-ci`](references/perf-headless-ci.md) - Use headless mode in CI
- [`perf-browser-selection`](references/perf-browser-selection.md) - Select browsers strategically
- [`perf-reuse-server`](references/perf-reuse-server.md) - Reuse development server when possible
- [`perf-retries`](references/perf-retries.md) - Configure retries for flaky test recovery

### 8. Debugging & CI (LOW-MEDIUM)

- [`debug-trace-viewer`](references/debug-trace-viewer.md) - Use trace viewer for failed tests
- [`debug-screenshots-videos`](references/debug-screenshots-videos.md) - Capture screenshots and videos on failure
- [`debug-inspector`](references/debug-inspector.md) - Use Playwright Inspector for interactive debugging
- [`debug-ci-reporters`](references/debug-ci-reporters.md) - Configure reporters for CI integration

## How to Use

Read individual reference files for detailed explanations and code examples:

- [Section definitions](references/_sections.md) - Category structure and impact levels
- [Rule template](files/assets/templates/_template.md) - Template for adding new rules

## Reference Files

| File | Description |
|------|-------------|
| [AGENTS.md](AGENTS.md) | Complete compiled guide with all rules |
| [references/_sections.md](references/_sections.md) | Category definitions and ordering |
| [files/assets/templates/_template.md](files/assets/templates/_template.md) | Template for new rules |
| [metadata.json](metadata.json) | Version and reference information |
Files in this package (48)
  • AGENTS.md 8 KB
  • SKILL.md 7 KB
  • metadata.json 1 KB
  • assets/templates/_template.md 1 KB
  • references/_sections.md 2 KB
  • references/arch-cleanup-state.md 2 KB
  • references/arch-fixtures.md 3 KB
  • references/arch-page-object-model.md 2 KB
  • references/arch-parallel-execution.md 2 KB
  • references/arch-test-isolation.md 2 KB
  • references/arch-test-production.md 2 KB
  • references/auth-api-login.md 3 KB
  • references/auth-multiple-roles.md 3 KB
  • references/auth-parallel-workers.md 3 KB
  • references/auth-session-storage.md 3 KB
  • references/auth-storage-state.md 3 KB
  • references/debug-ci-reporters.md 2 KB
  • references/debug-inspector.md 2 KB
  • references/debug-screenshots-videos.md 2 KB
  • references/debug-trace-viewer.md 2 KB
  • references/loc-avoid-xpath.md 2 KB
  • references/loc-chained-locators.md 2 KB
  • references/loc-data-testid.md 2 KB
  • references/loc-label-selectors.md 2 KB
  • references/loc-placeholder-selector.md 2 KB
  • references/loc-role-selectors.md 2 KB
  • references/loc-text-selectors.md 2 KB
  • references/mock-abort-requests.md 3 KB
  • references/mock-api-responses.md 3 KB
  • references/mock-har-files.md 3 KB
  • references/mock-intercept-modify.md 3 KB
  • references/mock-network-conditions.md 3 KB
  • references/next-app-router-navigation.md 3 KB
  • references/next-baseurl-config.md 3 KB
  • references/next-server-actions.md 3 KB
  • references/next-server-components.md 3 KB
  • references/next-wait-hydration.md 3 KB
  • references/perf-browser-selection.md 3 KB
  • references/perf-headless-ci.md 2 KB
  • references/perf-retries.md 2 KB
  • references/perf-reuse-server.md 2 KB
  • references/perf-sharding.md 2 KB
  • references/wait-action-retries.md 2 KB
  • references/wait-avoid-hard-waits.md 3 KB
  • references/wait-custom-timeout.md 2 KB
  • references/wait-network-idle.md 3 KB
  • references/wait-soft-assertions.md 3 KB
  • references/wait-web-first-assertions.md 2 KB

Versions

RepositoryScoreLicence
This page · zenobi-us/dotfiles100MIT
magnus919/agent-skills100MIT
kriscard/kriscard-claude-plugins100MIT
dreamlab-ai/agentbox100AGPL-3.0
DroBov1Tya/dusk_code100MIT
ivy00johns/skill-madness100MIT
musingfox/cc-plugins100MIT
netease-youdao/LobsterAI100MIT
claude-dev-suite/claude-dev-suite100MIT

Database snapshot: 13.11.2026 · package version 593c979f7332 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100v1-e2e-testing
    Use when implementing or debugging browser end-to-end tests, especially Playwright or flaky tests. Triggers on "E2E test", "Playwright", or "flaky browser test".
  • 100playwright-ops
    Playwright end-to-end testing operations - selectors, fixtures, network mocking, auth, parallelism, CI, visual regression, flake hunting. Use for: playwright, e2e test, end-to-end testing, browser test, getByRole, page object, storageState, trace viewer, flaky test, test…
  • 100webapp-testing
    Playwright E2E patterns, Testing Library component tests, test selectors. Use when writing browser tests, component tests, or setting up an E2E testing pipeline for a Next.js or React app.
  • 100playwright-expert
    Use when writing E2E tests with Playwright, setting up test infrastructure, or debugging flaky browser tests. Invoke to write test scripts, create page objects, configure test fixtures, set up reporters, add CI integration, implement API mocking, or perform visual regression…
  • 100playwright-e2e-testing
    Write, fix, or review Playwright end-to-end tests, especially for Next.js apps - locators, auth via storageState, flaky waits, server-side fetch mocking, CI against a production build. Use for *.spec.ts / e2e/ / playwright.config changes or flaky browser tests. For unit and…
  • 100playwright-expert
    Use when writing E2E tests with Playwright, setting up test infrastructure, or debugging flaky browser tests. Invoke to write test scripts, create page objects, configure test fixtures, set up reporters, add CI integration, implement API mocking, or perform visual regression…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.