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.
- Installs
- 1.2K
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/pproenca/dot-skills --skill playwright- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads playwright automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
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 |
FAQ
What does the playwright skill do?
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.
How do I install playwright?
Run npx skills add https://github.com/pproenca/dot-skills --skill playwright in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/playwright/ (personal) or .claude/skills/playwright/ (project).
Which AI agents can use playwright?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is playwright safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains playwright?
It is published by pproenca in pproenca/dot-skills. It has 1,152 recorded installs.
More from pproenca/dot-skills
zod
pproenca/dot-skills
Zod schema validation best practices for type safety, parsing, and error handling. This skill should be used when defining z.object schemas, using z.string validations, safeParse, or z.infer. This skill does NOT cover React Hook Form integration patterns (use react-hook-form skill) or OpenAPI client generation (use orval skill).
vitest
pproenca/dot-skills
Vitest testing framework patterns for test setup, async testing, mocking with vi., snapshots, and test performance (formerly test-vitest). This skill should be used when writing or debugging Vitest tests. This skill does NOT cover TDD methodology (use test-tdd skill), API mocking with MSW (use test-msw skill), or Jest-specific APIs.
react-hook-form
pproenca/dot-skills
React Hook Form performance optimization for client-side form validation using useForm, useWatch, useController, useFieldArray, the subscribe() API, and the Watch / FormStateSubscribe / FieldArray render-prop components. Covers RHF 7.82 additions including resetDefaultValues() and the disabled field-array option. This skill should be used when building client-side controlled forms with React Hook Form library. This skill does NOT cover React 19 Server Actions, useActionState, or server-side form handling (use react-19 skill for those).
emilkowal-animations
pproenca/dot-skills
Emil Kowalski's animation best practices for web interfaces. Use when writing, reviewing, or implementing animations in React, CSS, or Framer Motion. Triggers on tasks involving transitions, easing, gestures, toasts, drawers, or motion.
nuqs
pproenca/dot-skills
nuqs (type-safe URL query state) best practices for Next.js and other React frameworks. This skill should be used when writing, reviewing, or refactoring code that uses nuqs for URL state management. Triggers on tasks involving useQueryState, useQueryStates, search params, URL state, query parameters, nuqs parsers, limitUrlUpdates, Standard Schema, NuqsAdapter, or Next.js routing with state.
clean-architecture
pproenca/dot-skills
Clean Architecture principles and best practices from Robert C. Martin's book. This skill should be used when designing software systems, reviewing code structure, or refactoring applications to achieve better separation of concerns. Triggers on tasks involving layers, boundaries, dependency direction, entities, use cases, or system architecture.
Popular testing & qa skills
tdd
mattpocock/skills
Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests.
grilling
mattpocock/skills
Grill the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking, or uses any 'grill' trigger phrases.
migrate-to-shoehorn
mattpocock/skills
Migrate test files from as type assertions to @total-typescript/shoehorn. Use when user mentions shoehorn, wants to replace as in tests, or needs partial test data.
run-train
lllllllama/rigorpilot-skills
Rigor Train skill for deep learning research repositories. Use when a documented or selected training command should be run conservatively for startup verification, short-run verification, full kickoff, or resume, with command, config, seed, log, checkpoint, status, and metric evidence written to standardized trainoutputs/. Do not use for environment setup, exploratory sweeps, speculative idea implementation, or end-to-end orchestration.
test-driven-development
obra/superpowers
Use when implementing any feature or bugfix, before writing implementation code
finishing-a-development-branch
obra/superpowers
Use when implementation is complete, all tests pass, and you need to decide how to integrate the work