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 specification.

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

Tool	Link
Claude Code	code.claude.com/docs/en/skills
Cursor	cursor.com/docs/context/skills
VS Code Copilot	code.visualstudio.com/docs/copilot/customization/agent-skills
Gemini CLI	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.

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

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.