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

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