> ## Documentation Index > Fetch the complete documentation index at: https://docs.testdino.com/llms.txt > Use this file to discover all available pages before exploring further. # Playwright Best Practices Skill > AI agent skill for writing, debugging, and maintaining Playwright tests. The Playwright Best Practices Skill is a knowledge pack that AI coding agents (Claude Code, Cursor, VS Code Copilot, Gemini CLI) load on demand. It guides writing, debugging, and maintaining Playwright tests. Install it with the command below, then ask your agent a Playwright question. The skill follows the open [Agent Skills](https://agentskills.io/home) specification. ## Installation ```bash theme={null} npx skills add testdino-hq/playwright-skill ``` Install individual sub-skills when you need specific coverage: ```bash theme={null} npx skills add testdino-hq/playwright-skill/core npx skills add testdino-hq/playwright-skill/ci npx skills add testdino-hq/playwright-skill/pom npx skills add testdino-hq/playwright-skill/migration npx skills add testdino-hq/playwright-skill/playwright-cli ``` No additional configuration is required. The skill activates automatically when your AI agent detects a Playwright-related task. ### Supported Tools | Tool | Link | | :-------------- | :------------------------------------------------------------------------------------------------------------------------------------- | | Claude Code | [code.claude.com/docs/en/skills](https://code.claude.com/docs/en/skills) | | Cursor | [cursor.com/docs/context/skills](https://cursor.com/docs/context/skills) | | VS Code Copilot | [code.visualstudio.com/docs/copilot/customization/agent-skills](https://code.visualstudio.com/docs/copilot/customization/agent-skills) | | Gemini CLI | [geminicli.com/docs/cli/skills](https://geminicli.com/docs/cli/skills/) | ## How It Works An Agent Skill is a directory containing a `SKILL.md` manifest and reference documents. The manifest declares metadata, core instructions, and an index of guides. Reference documents contain topic-specific guidance the agent reads on demand. ```text theme={null} testdino-hq/playwright-skill/ ├── core/ │ ├── SKILL.md │ ├── locators.md │ ├── assertions-and-waiting.md │ ├── authentication.md │ ├── network-mocking.md │ └── ... ├── ci/ │ ├── SKILL.md │ └── ... ├── pom/ │ ├── SKILL.md │ └── ... ├── migration/ │ ├── SKILL.md │ └── ... └── playwright-cli/ ├── SKILL.md └── ... ``` ### Progressive Disclosure Skills use a three-stage loading model to minimize context window usage: | Stage | What Loads | Token Cost | | :------------- | :------------------------------------------------------- | :------------------------- | | Idle | Skill name and one-line description | \~50 tokens | | Activated | `SKILL.md` manifest with core principles and guide index | \~500 tokens | | Reference pull | Individual guide files, loaded selectively per task | \~200-800 tokens per guide | The agent determines which stage to enter based on task relevance. A task like "fix this flaky Playwright test" causes the agent to load the manifest, then selectively read `debugging.md` and `flaky-tests.md` rather than every guide in the skill. This differs from loading full documentation into a system prompt (30,000+ tokens upfront regardless of relevance) or RAG retrieval (variable quality, no opinionated guidance). ## Core Principles The `SKILL.md` manifest in the core skill defines ten principles applied to all generated code: 1. Prefer accessible selectors (`getByRole`, `getByLabel`) over CSS/XPath 2. Never use hard timeouts. Wait on conditions 3. Use web-first assertions that auto-retry 4. Isolate every test. No shared state 5. Centralize URLs via `baseURL` 6. Retries: `2` in CI, `0` locally 7. Traces: `'on-first-retry'` 8. Share state via fixtures, not module globals 9. One behavior per test 10. Mock external dependencies only. Never mock your own app ## Coverage ### Core Locators, locator strategy, assertions and waiting, fixtures and hooks, forms and validation, drag and drop, file operations, test data management, test organization, authentication flows, OAuth and SSO, API testing, CRUD testing, network mocking, and when-to-mock decision framework. ### Framework Recipes React, Next.js (App Router and Pages Router), Vue, Angular. Framework-specific selectors, routing, SSR/hydration patterns. ### Visual and Accessibility Visual regression with `toHaveScreenshot()`, axe-core integration, keyboard navigation, WCAG compliance. ### Debugging Trace viewer, UI mode, error index, flaky test diagnosis, common pitfalls, error and edge case handling. ### Advanced WebSockets, Service Workers, PWAs, Canvas/WebGL, Electron, browser extensions, iframes, Shadow DOM, i18n, multi-user collaboration, security testing, performance testing. ### CI/CD | Provider | Coverage | | :------------- | :----------------------------------------------------------------------------- | | GitHub Actions | Workflow configuration, artifact upload, sharding with matrix strategy | | GitLab CI | Pipeline stages, browser caching, parallel jobs | | CircleCI | Orb usage, test splitting, resource classes | | Azure DevOps | YAML pipelines, hosted agent configuration | | Jenkins | Declarative pipelines, Playwright in Docker | | Docker | Official Playwright image, dependency caching, multi-stage builds | | Cross-cutting | Test sharding (`--shard=N/M`), reporting aggregation, code coverage collection | ### Page Object Model POM implementation patterns with a decision guide for choosing between POMs, fixtures, and helper functions. Includes trade-off analysis. ### Migration API mapping tables and incremental migration strategies: * **Cypress to Playwright**: `cy.get()` to `page.locator()`, `cy.intercept()` to `page.route()` * **Selenium/WebDriver to Playwright**: driver setup, element interaction, and wait strategy translation ### Playwright CLI Browser commands, request mocking, script execution, session and storage management, `codegen` for test generation, tracing, screenshots, video recording, and device emulation. ## Example Prompts The skill activates based on task inference. These prompts demonstrate what triggers the agent to load relevant guides: | Prompt | Guides Loaded | | :-------------------------------------------------------------------- | :---------------------------------------------------------- | | "Write Playwright tests for a multi-step form wizard with validation" | Locator strategy, form validation, test organization | | "Optimize our CI pipeline time with test sharding" | CI/CD, sharding, matrix-based parallel execution | | "This checkout test passes locally but times out in CI" | Debugging, flaky test diagnosis, CI environment differences | | "Test the real-time collaboration feature in our app" | Multi-user testing, WebSocket, SSE interception | | "Migrate our Cypress login tests to Playwright" | Migration mapping tables, authentication patterns | | "Add visual regression tests for dashboard components" | Visual testing, `toHaveScreenshot()`, CI artifact handling | ## Related Full source and all guides. MIT licensed. The open standard defining how skills, manifests, and progressive disclosure work. Connect AI assistants to your test data.