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