---
name: playwright
description: Playwright end-to-end tests and flaky-test fixes.
title: playwright
canonical_url: https://skilld.dev/gh/pymodel/react-frontend-skills/playwright
last_updated: 2026-11-12T09:04:44.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> 45 supporting files sit beside this SKILL.md. When the Skill refers to one, fetch https://skilld.dev/api/skills-raw/pymodel/react-frontend-skills/playwright/PATH with PATH replaced.
>
> If the user asked to install this Skill, run `npx skilld install pymodel/react-frontend-skills/playwright`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/playwright`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/pymodel/react-frontend-skills/playwright) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/playwright`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/playwright --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/playwright --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Playwright + Next.js Testing Best Practices

Comprehensive testing optimization guide for Playwright with Next.js applications. Contains 45 rules across 8 categories, prioritized by impact to guide reliable, fast, and maintainable E2E tests. Current: Playwright 1.65 (1.65.0).

## 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`](https://skilld.dev/api/skills-raw/pymodel/react-frontend-skills/playwright/references/arch-test-isolation.md) - Use fresh browser context for each test
- [`arch-parallel-execution`](https://skilld.dev/api/skills-raw/pymodel/react-frontend-skills/playwright/references/arch-parallel-execution.md) - Enable parallel test execution
- [`arch-page-object-model`](https://skilld.dev/api/skills-raw/pymodel/react-frontend-skills/playwright/references/arch-page-object-model.md) - Use Page Object Model for complex pages
- [`arch-fixtures`](https://skilld.dev/api/skills-raw/pymodel/react-frontend-skills/playwright/references/arch-fixtures.md) - Use fixtures for shared setup
- [`arch-test-production`](https://skilld.dev/api/skills-raw/pymodel/react-frontend-skills/playwright/references/arch-test-production.md) - Test against production builds
- [`arch-cleanup-state`](https://skilld.dev/api/skills-raw/pymodel/react-frontend-skills/playwright/references/arch-cleanup-state.md) - Clean up test state after each test

### 2. Selectors & Locators (CRITICAL)

- [`loc-role-selectors`](https://skilld.dev/api/skills-raw/pymodel/react-frontend-skills/playwright/references/loc-role-selectors.md) - Use role-based selectors over CSS
- [`loc-data-testid`](https://skilld.dev/api/skills-raw/pymodel/react-frontend-skills/playwright/references/loc-data-testid.md) - Use data-testid for dynamic elements
- [`loc-label-selectors`](https://skilld.dev/api/skills-raw/pymodel/react-frontend-skills/playwright/references/loc-label-selectors.md) - Use getByLabel for form inputs
- [`loc-text-selectors`](https://skilld.dev/api/skills-raw/pymodel/react-frontend-skills/playwright/references/loc-text-selectors.md) - Use getByText for static content
- [`loc-avoid-xpath`](https://skilld.dev/api/skills-raw/pymodel/react-frontend-skills/playwright/references/loc-avoid-xpath.md) - Avoid XPath selectors
- [`loc-chained-locators`](https://skilld.dev/api/skills-raw/pymodel/react-frontend-skills/playwright/references/loc-chained-locators.md) - Chain locators for specificity
- [`loc-placeholder-selector`](https://skilld.dev/api/skills-raw/pymodel/react-frontend-skills/playwright/references/loc-placeholder-selector.md) - Use getByPlaceholder sparingly
- [`loc-frame-locator`](https://skilld.dev/api/skills-raw/pymodel/react-frontend-skills/playwright/references/loc-frame-locator.md) - Locate elements inside iframes with frameLocator

### 3. Waiting & Assertions (HIGH)

- [`wait-web-first-assertions`](https://skilld.dev/api/skills-raw/pymodel/react-frontend-skills/playwright/references/wait-web-first-assertions.md) - Use web-first assertions
- [`assert-aria-snapshots`](https://skilld.dev/api/skills-raw/pymodel/react-frontend-skills/playwright/references/assert-aria-snapshots.md) - Assert accessibility structure with aria snapshots
- [`wait-avoid-hard-waits`](https://skilld.dev/api/skills-raw/pymodel/react-frontend-skills/playwright/references/wait-avoid-hard-waits.md) - Avoid hard waits
- [`wait-network-idle`](https://skilld.dev/api/skills-raw/pymodel/react-frontend-skills/playwright/references/wait-network-idle.md) - Wait for observable readiness, not network idle
- [`wait-action-retries`](https://skilld.dev/api/skills-raw/pymodel/react-frontend-skills/playwright/references/wait-action-retries.md) - Let actions auto-wait before interacting
- [`wait-soft-assertions`](https://skilld.dev/api/skills-raw/pymodel/react-frontend-skills/playwright/references/wait-soft-assertions.md) - Use soft assertions for non-critical checks
- [`wait-custom-timeout`](https://skilld.dev/api/skills-raw/pymodel/react-frontend-skills/playwright/references/wait-custom-timeout.md) - Configure timeouts appropriately

### 4. Authentication & State (HIGH)

- [`auth-storage-state`](https://skilld.dev/api/skills-raw/pymodel/react-frontend-skills/playwright/references/auth-storage-state.md) - Reuse authentication with storage state
- [`auth-multiple-roles`](https://skilld.dev/api/skills-raw/pymodel/react-frontend-skills/playwright/references/auth-multiple-roles.md) - Use separate storage states for different roles
- [`auth-session-storage`](https://skilld.dev/api/skills-raw/pymodel/react-frontend-skills/playwright/references/auth-session-storage.md) - Handle session storage for auth
- [`auth-api-login`](https://skilld.dev/api/skills-raw/pymodel/react-frontend-skills/playwright/references/auth-api-login.md) - Use API login for faster auth setup
- [`auth-parallel-workers`](https://skilld.dev/api/skills-raw/pymodel/react-frontend-skills/playwright/references/auth-parallel-workers.md) - Use worker-scoped auth for parallel tests

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

- [`mock-api-responses`](https://skilld.dev/api/skills-raw/pymodel/react-frontend-skills/playwright/references/mock-api-responses.md) - Mock API responses for deterministic tests
- [`mock-intercept-modify`](https://skilld.dev/api/skills-raw/pymodel/react-frontend-skills/playwright/references/mock-intercept-modify.md) - Intercept and modify real responses
- [`mock-har-files`](https://skilld.dev/api/skills-raw/pymodel/react-frontend-skills/playwright/references/mock-har-files.md) - Use HAR files for complex mock scenarios
- [`mock-abort-requests`](https://skilld.dev/api/skills-raw/pymodel/react-frontend-skills/playwright/references/mock-abort-requests.md) - Abort unnecessary requests
- [`mock-network-conditions`](https://skilld.dev/api/skills-raw/pymodel/react-frontend-skills/playwright/references/mock-network-conditions.md) - Simulate network conditions

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

- [`next-wait-hydration`](https://skilld.dev/api/skills-raw/pymodel/react-frontend-skills/playwright/references/next-wait-hydration.md) - Wait for hydration before interacting
- [`next-server-components`](https://skilld.dev/api/skills-raw/pymodel/react-frontend-skills/playwright/references/next-server-components.md) - Test server components correctly
- [`next-app-router-navigation`](https://skilld.dev/api/skills-raw/pymodel/react-frontend-skills/playwright/references/next-app-router-navigation.md) - Test App Router navigation patterns
- [`next-server-actions`](https://skilld.dev/api/skills-raw/pymodel/react-frontend-skills/playwright/references/next-server-actions.md) - Test server actions end-to-end
- [`next-baseurl-config`](https://skilld.dev/api/skills-raw/pymodel/react-frontend-skills/playwright/references/next-baseurl-config.md) - Configure baseURL for clean navigation

### 7. Performance & Speed (MEDIUM)

- [`perf-sharding`](https://skilld.dev/api/skills-raw/pymodel/react-frontend-skills/playwright/references/perf-sharding.md) - Use sharding for large test suites
- [`perf-headless-ci`](https://skilld.dev/api/skills-raw/pymodel/react-frontend-skills/playwright/references/perf-headless-ci.md) - Use headless mode in CI
- [`perf-browser-selection`](https://skilld.dev/api/skills-raw/pymodel/react-frontend-skills/playwright/references/perf-browser-selection.md) - Select browsers strategically
- [`perf-reuse-server`](https://skilld.dev/api/skills-raw/pymodel/react-frontend-skills/playwright/references/perf-reuse-server.md) - Reuse a matching local server when safe
- [`perf-retries`](https://skilld.dev/api/skills-raw/pymodel/react-frontend-skills/playwright/references/perf-retries.md) - Use retries to detect and diagnose flakiness

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

- [`debug-trace-viewer`](https://skilld.dev/api/skills-raw/pymodel/react-frontend-skills/playwright/references/debug-trace-viewer.md) - Use trace viewer for failed tests
- [`debug-screenshots-videos`](https://skilld.dev/api/skills-raw/pymodel/react-frontend-skills/playwright/references/debug-screenshots-videos.md) - Capture screenshots and videos on failure
- [`debug-inspector`](https://skilld.dev/api/skills-raw/pymodel/react-frontend-skills/playwright/references/debug-inspector.md) - Use Playwright Inspector for interactive debugging
- [`debug-ci-reporters`](https://skilld.dev/api/skills-raw/pymodel/react-frontend-skills/playwright/references/debug-ci-reporters.md) - Configure reporters for CI integration

## How to Use

Run in the project root first:

```bash
npx -y @pymodel/react-frontend-skills detect   # installed vs. targeted versions
```

Read `references/<rule-id>.md` for each rule above that matches the task: why it matters, then incorrect vs. correct code.
