About playwright
A reference skill with 43 prioritized rules for testing Next.js applications with Playwright. It helps developers write and maintain reliable end-to-end tests, with guidance on selectors, waiting, authentication, network mocking, Next.js behavior, performance, and debugging.
Key features
- 0143 rules across eight categories
- 02Guidance on test architecture and locators
- 03Recommendations for waits and assertions
- 04Authentication and state reuse patterns
- 05Network mocking and Next.js testing
- 06Performance, debugging, and CI practices
Use cases
- 01Create end-to-end tests for a Next.js app
- 02Investigate flaky or failing tests
- 03Reuse authentication state across tests
- 04Improve test execution and CI debugging
Install
Copy the command and run it in a terminal.
$
npx skills add https:/After installing, type/playwrightin Claude Code to confirm it loaded.
Bundled files
References and scripts installed along with SKILL.md.
AGENTS.mdmetadata.jsonassets/templates/_template.mdreferences/_sections.mdarch-cleanup-state.mdarch-fixtures.mdarch-page-object-model.mdarch-parallel-execution.mdarch-test-isolation.mdarch-test-production.mdauth-api-login.mdauth-multiple-roles.mdauth-parallel-workers.mdauth-session-storage.mdauth-storage-state.mddebug-ci-reporters.mddebug-inspector.mddebug-screenshots-videos.mddebug-trace-viewer.mdloc-avoid-xpath.mdloc-chained-locators.mdloc-data-testid.mdloc-label-selectors.mdloc-placeholder-selector.mdloc-role-selectors.mdloc-text-selectors.mdmock-abort-requests.mdmock-api-responses.mdmock-har-files.mdmock-intercept-modify.mdDetails
From the project READMEPlaywright + 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 |
Comments
Markdown supported