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

arch-

loc-

wait-

auth-

mock-

next-

perf-

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