Skip to main content
The Playwright Best Practices Skill is a structured knowledge pack that AI coding agents load on demand. It provides opinionated guidance for writing, debugging, and maintaining Playwright tests based on proven patterns. The skill follows the open Agent Skills specification and works with any compatible tool.

​
Installation

npx skills add testdino-hq/playwright-skill
Install individual sub-skills when you need specific coverage: 
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

ToolLink
Claude Codecode.claude.com/docs/en/skills
Cursorcursor.com/docs/context/skills
VS Code Copilotcode.visualstudio.com/docs/copilot/customization/agent-skills
Gemini CLIgeminicli.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. 
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:
StageWhat LoadsToken Cost
IdleSkill name and one-line description~50 tokens
ActivatedSKILL.md manifest with core principles and guide index~500 tokens
Reference pullIndividual 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

ProviderCoverage
GitHub ActionsWorkflow configuration, artifact upload, sharding with matrix strategy
GitLab CIPipeline stages, browser caching, parallel jobs
CircleCIOrb usage, test splitting, resource classes
Azure DevOpsYAML pipelines, hosted agent configuration
JenkinsDeclarative pipelines, Playwright in Docker
DockerOfficial Playwright image, dependency caching, multi-stage builds
Cross-cuttingTest 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:
  • “Write Playwright tests for a multi-step form wizard with input validation on each step.” — The agent loads locator strategy, form validation patterns, and test organization guidance.
  • “Optimize our CI pipeline time with test sharding.” — The agent loads CI/CD and sharding guides to configure matrix-based parallel execution.
  • “This checkout test passes locally but times out in CI.” — The agent references debugging, flaky test diagnosis, and CI environment differences.
  • “Test the real-time collaboration feature in our app.” — The agent loads multi-user testing and WebSocket guides covering browser.newContext() isolation, page.on('websocket') observation, and SSE interception.
  • “Migrate our Cypress login tests to Playwright.” — The agent loads migration mapping tables and authentication patterns.
  • “Add visual regression tests for the dashboard components.” — The agent loads visual testing with toHaveScreenshot() configuration and CI artifact handling.

GitHub Repository

Full source and all guides. MIT licensed.

Agent Skills Specification

The open standard defining how skills, manifests, and progressive disclosure work.

AI in TestDino

AI failure classification, pattern detection, and recommendations.

TestDino MCP

Connect AI assistants to your test data.