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