playwright
Playwright testing best practices for Next.js applications (formerly test-playwright). This skill should be used when writing, reviewing, or debugging E2E tests with Playwright. Triggers on tasks involving test selectors, flaky tests, authentication state, API mocking, hydration testing, parallel execution, CI configuration, or debugging test failures.
Playwright testing best practices for Next.js applications (formerly test-playwright). This skill should be used when writing, reviewing, or debugging E2E tests with Playwright. Triggers on tasks involving test selectors, flaky tests, authentication state, API mocking, hydration testing, parallel execution, CI configuration, or debugging test failures.
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- Use network idle for complex pageswait-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 development server when possibleperf-retries- Configure retries for flaky test recovery
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
- 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 |
You Might Also Like
Related Skills
fix
Use when you have lint errors, formatting issues, or before committing code to ensure it passes CI.
facebook
frontend-testing
Generate Vitest + React Testing Library tests for Dify frontend components, hooks, and utilities. Triggers on testing, spec files, coverage, Vitest, RTL, unit tests, integration tests, or write/review test requests.
langgeniusfrontend-code-review
Trigger when the user requests a review of frontend files (e.g., `.tsx`, `.ts`, `.js`). Support both pending-change reviews and focused file reviews while applying the checklist rules.
langgenius
code-reviewer
Use this skill to review code. It supports both local changes (staged or working tree) and remote Pull Requests (by ID or URL). It focuses on correctness, maintainability, and adherence to project standards.
google-gemini
session-logs
Search and analyze your own session logs (older/parent conversations) using jq.
moltbot