Skip to main content
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 provides 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:
PromptGuides 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

GitHub Repository

Full source and all guides. MIT licensed.

Agent Skills Specification

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

TestDino MCP

Connect AI assistants to your test data.