About playwright
A reference skill for writing and maintaining Playwright end-to-end tests in Next.js applications. It organizes 45 prioritized rules into eight areas, from test structure and selectors to debugging and CI.
Key features
- 0145 rules in eight categories
- 02Guidance for test isolation and architecture
- 03Selector and assertion practices
- 04Authentication state reuse
- 05Network mocking and Next.js testing
- 06Performance, debugging, and CI guidance
Use cases
- 01Writing Playwright tests for Next.js apps
- 02Investigating flaky or failing tests
- 03Reusing authentication state across tests
- 04Reviewing test code and CI settings
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.
references/arch-cleanup-state.mdarch-fixtures.mdarch-page-object-model.mdarch-parallel-execution.mdarch-test-isolation.mdarch-test-production.mdassert-aria-snapshots.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-frame-locator.mdloc-label-selectors.mdloc-placeholder-selector.mdloc-role-selectors.mdloc-text-selectors.mdmock-abort-requests.mdmock-api-responses.mdmock-har-files.mdmock-intercept-modify.mdmock-network-conditions.mdnext-app-router-navigation.mdDetails
From the project READMEPlaywright + Next.js Testing Best Practices
Comprehensive testing optimization guide for Playwright with Next.js applications. Contains 45 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 sparinglyloc-frame-locator- Locate elements inside iframes with frameLocator
3. Waiting & Assertions (HIGH)
wait-web-first-assertions- Use web-first assertionsassert-aria-snapshots- Assert accessibility structure with aria snapshotswait-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
Run in the project root first:
npx -y @pymodel/react-frontend-skills detect # installed vs. targeted versions
npx -y @pymodel/react-frontend-skills scan --skill playwright # deprecated APIs → rule IDs
Read references/<rule-id>.md for each rule above that matches the task and for each scan hit: why it matters, then incorrect vs. correct code.
Comments
Markdown supported