playwright-cli-agents

Playwright CLI Agents for Claude Code

A production-ready set of Claude Code agents and skills that automate Playwright E2E test generation, debugging, and planning using the Page Object Model pattern.

Drop these files into any project's .claude/ directory and get an AI-powered E2E testing workflow — from exploring a live URL to generating robust, maintainable test suites.

---

Getting Started

Installation

npm install -g @playwright/cli@latest
playwright-cli --help

Note that you might need to force it to reclaim the playwright-cli binary from our older MCP package.

npm install -g @playwright/cli@latest --force

Demo

> Use playwright skills to test https://demo.playwright.dev/todomvc/.
  Take screenshots for all successful and failing scenarios.

Your agent will be running commands, but it does not mean you can't play with it manually:

playwright-cli open https://demo.playwright.dev/todomvc/ --headed
playwright-cli type "Buy groceries"
playwright-cli press Enter
playwright-cli type "Water flowers"
playwright-cli press Enter
playwright-cli check e21
playwright-cli check e35
playwright-cli screenshot

Skills-less operation

Point your agent at the CLI and let it cook. It'll read the skill off playwright-cli --help on its own:

Test the "add todo" flow on https://demo.playwright.dev/todomvc using playwright-cli.
Check playwright-cli --help for available commands.

Installing skills

Claude Code, GitHub Copilot and others will let you install the Playwright skills into the agentic loop.

Plugin (recommended)

/plugin marketplace add microsoft/playwright-cli
/plugin install playwright-cli

Manual

mkdir -p .claude/skills/playwright-cli
curl -o .claude/skills/playwright-cli/SKILL.md \
  https://raw.githubusercontent.com/microsoft/playwright-cli/main/skills/playwright-cli/SKILL.md

---

What's Inside

.claude-plugin/
└── marketplace.json                     # Plugin marketplace catalog

plugins/
└── playwright-cli-agents/
    ├── .claude-plugin/
    │   └── plugin.json                  # Plugin manifest
    ├── agents/                          # Specialized subagents
    │   ├── playwright-cli-planner.md    # Explores pages → creates test plans
    │   ├── playwright-cli-generator.md  # Executes plans → writes test code
    │   └── playwright-cli-healer.md     # Debugs & fixes failing tests
    └── skills/
        ├── playwright-cli/              # Browser automation via CLI
        │   └── SKILL.md                 # playwright-cli command reference
        └── e2e/                         # Shared domain knowledge
            ├── SKILL.md                 # Core skill (auto-injected into agents)
            ├── examples/
            │   ├── page-object-model.md # Page Object class templates
            │   └── e2e-tests.md         # Integration test patterns
            └── references/
                ├── component-exploration.md # How to explore UIs via playwright-cli
                └── api-mocking.md       # Deterministic test data setup

The Three Agents

Agent	Purpose	Trigger Example
Planner	Navigates to a URL, explores interactive elements, and produces a structured test plan	"Create a test plan for our checkout flow at localhost:3000/checkout"
Generator	Takes a test plan (or creates one), drives the browser in real-time, and outputs Page Object + spec files	"Generate Playwright tests for the login page"
Healer	Runs failing tests, inspects the DOM, console, and network, then fixes broken locators/timing	"The dashboard test is failing after the redesign, fix it"

How They Work Together

 You describe what to test
          │
          ▼
   ┌─────────────┐
   │   Planner    │  Explores the page, identifies elements,
   │   (green)    │  writes a markdown test plan
   └──────┬──────┘
          │ test plan
          ▼
   ┌─────────────┐
   │  Generator   │  Drives browser via playwright-cli, records actions,
   │   (blue)     │  generates Page Object + spec files
   └──────┬──────┘
          │ test files
          ▼
   ┌─────────────┐
   │   Healer     │  Runs tests, catches failures,
   │   (red)      │  auto-fixes locators & timing
   └─────────────┘

The E2E Skill

The e2e skill is shared domain knowledge that all three agents preload via the skills: [e2e, playwright-cli] frontmatter field. It defines:

• Test file structure — where Page Objects, specs, and constants go
• Visual testing conventions — component-level screenshots with @visual tag
• API mocking patterns — deterministic data via mockApi utility
• Locator strategy — role-based > data-attribute > CSS selector
• Anti-patterns — no waitForTimeout, no full-page screenshots, no fixture files

Generated Test Structure