playwright

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` - Wait for observable readiness, not network idle
• `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 a matching local server when safe
• `perf-retries` - Use retries to detect and diagnose flakiness

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

Reference Files