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

• Use fresh browser context for each test

• arch-parallel-execution

• Enable parallel test execution

• arch-page-object-model

• Use Page Object Model for complex pages

• arch-fixtures

• Use fixtures for shared setup

• arch-test-production

• Test against production builds

• arch-cleanup-state

• Clean up test state after each test

2. Selectors & Locators (CRITICAL)

• loc-role-selectors

• Use role-based selectors over CSS

• loc-data-testid

• Use data-testid for dynamic elements

• loc-label-selectors

• Use getByLabel for form inputs

• loc-text-selectors

• Use getByText for static content

• loc-avoid-xpath

• Avoid XPath selectors

• loc-chained-locators

• Chain locators for specificity

• loc-placeholder-selector

• Use getByPlaceholder sparingly

3. Waiting & Assertions (HIGH)

• wait-web-first-assertions

• Use web-first assertions

• wait-avoid-hard-waits

• Avoid hard waits

• wait-network-idle

• Use network idle for complex pages

• wait-action-retries

• Let actions auto-wait before interacting

• wait-soft-assertions

• Use soft assertions for non-critical checks

• wait-custom-timeout

• Configure timeouts appropriately

4. Authentication & State (HIGH)

• auth-storage-state

• Reuse authentication with storage state

• auth-multiple-roles

• Use separate storage states for different roles

• auth-session-storage

• Handle session storage for auth

• auth-api-login

• Use API login for faster auth setup

• auth-parallel-workers

• Use worker-scoped auth for parallel tests

5. Mocking & Network (MEDIUM-HIGH)

• mock-api-responses

• Mock API responses for deterministic tests

• mock-intercept-modify

• Intercept and modify real responses

• mock-har-files

• Use HAR files for complex mock scenarios

• mock-abort-requests

• Abort unnecessary requests

• mock-network-conditions

• Simulate network conditions

6. Next.js Integration (MEDIUM)

• next-wait-hydration

• Wait for hydration before interacting

• next-server-components

• Test server components correctly

• next-app-router-navigation

• Test App Router navigation patterns

• next-server-actions

• Test server actions end-to-end

• next-baseurl-config

• Configure baseURL for clean navigation

7. Performance & Speed (MEDIUM)

• perf-sharding

• Use sharding for large test suites

• perf-headless-ci

• Use headless mode in CI

• perf-browser-selection

• Select browsers strategically

• perf-reuse-server

• Reuse development server when possible

• perf-retries

• Configure retries for flaky test recovery

8. Debugging & CI (LOW-MEDIUM)

• debug-trace-viewer

• Use trace viewer for failed tests

• debug-screenshots-videos

• Capture screenshots and videos on failure

• debug-inspector

• Use Playwright Inspector for interactive debugging

• debug-ci-reporters

• Configure reporters for CI integration

How to Use

Read individual reference files for detailed explanations and code examples:

• Section definitions - Category structure and impact levels

• Rule template - Template for adding new rules

Reference Files

File Description

AGENTS.md Complete compiled guide with all rules

references/_sections.md Category definitions and ordering

assets/templates/_template.md Template for new rules

metadata.json Version and reference information