PyModel 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 testarch-parallel-execution- Enable parallel test executionarch-page-object-model- Use Page Object Model for complex pagesarch-fixtures- Use fixtures for shared setuparch-test-production- Test against production buildsarch-cleanup-state- Clean up test state after each test
2. Selectors & Locators (CRITICAL)
loc-role-selectors- Use role-based selectors over CSSloc-data-testid- Use data-testid for dynamic elementsloc-label-selectors- Use getByLabel for form inputsloc-text-selectors- Use getByText for static contentloc-avoid-xpath- Avoid XPath selectorsloc-chained-locators- Chain locators for specificityloc-placeholder-selector- Use getByPlaceholder sparingly
3. Waiting & Assertions (HIGH)
wait-web-first-assertions- Use web-first assertionswait-avoid-hard-waits- Avoid hard waitswait-network-idle- Wait for observable readiness, not network idlewait-action-retries- Let actions auto-wait before interactingwait-soft-assertions- Use soft assertions for non-critical checkswait-custom-timeout- Configure timeouts appropriately
4. Authentication & State (HIGH)
auth-storage-state- Reuse authentication with storage stateauth-multiple-roles- Use separate storage states for different rolesauth-session-storage- Handle session storage for authauth-api-login- Use API login for faster auth setupauth-parallel-workers- Use worker-scoped auth for parallel tests
5. Mocking & Network (MEDIUM-HIGH)
mock-api-responses- Mock API responses for deterministic testsmock-intercept-modify- Intercept and modify real responsesmock-har-files- Use HAR files for complex mock scenariosmock-abort-requests- Abort unnecessary requestsmock-network-conditions- Simulate network conditions
6. Next.js Integration (MEDIUM)
next-wait-hydration- Wait for hydration before interactingnext-server-components- Test server components correctlynext-app-router-navigation- Test App Router navigation patternsnext-server-actions- Test server actions end-to-endnext-baseurl-config- Configure baseURL for clean navigation
7. Performance & Speed (MEDIUM)
perf-sharding- Use sharding for large test suitesperf-headless-ci- Use headless mode in CIperf-browser-selection- Select browsers strategicallyperf-reuse-server- Reuse a matching local server when safeperf-retries- Use retries to detect and diagnose flakiness
8. Debugging & CI (LOW-MEDIUM)
debug-trace-viewer- Use trace viewer for failed testsdebug-screenshots-videos- Capture screenshots and videos on failuredebug-inspector- Use Playwright Inspector for interactive debuggingdebug-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
| File | Description |
|---|---|
| AGENTS.md | Complete compiled guide with all rules |
| references/_sections.md | Category definitions and ordering |
| metadata.json | Version and reference information |