Official Playwright Test Agents (v1.56+)

AI Agents That Plan, Generate & Heal Your Playwright Tests

Playwright Test Agents use AI and MCP (Model Context Protocol) to explore your app, create test plans, generate executable tests, and automatically fix failures - all from natural language descriptions.

precision_manufacturing

What are Playwright Test Agents?

Playwright Test Agents are AI-powered assistants introduced in Playwright v1.56 that use MCP (Model Context Protocol) to automate test creation and maintenance. They work inside AI coding assistants like Claude Code, VS Code Copilot, and Cursor.

smart_toyThree Specialized AI Agents

  • check_circle🎭 Planner - Explores your app and creates Markdown test plans
  • check_circle🎭 Generator - Converts test plans into executable Playwright tests
  • check_circle🎭 Healer - Automatically fixes failing tests by analyzing errors

Powered by: Playwright MCP (@playwright/mcp) + AI Assistants

Introduced: Playwright v1.56 (October 2024)

school

Practice with Our Test Material

We've created a complete practice repository with examples specifically designed for Playwright Test Agents. Use our test website and sample code to learn and practice!

check_circleWhat's Included

  • arrow_rightLive Test Site: practiceautomatedtesting.com/shopping - A real shopping cart to practice on
  • arrow_rightExample Test Plans: Pre-made specs showing how the Planner agent works
  • arrow_rightSample Tests: Generated tests you can study and modify
  • arrow_rightSetup Guide: Step-by-step instructions for getting started

The Three Test Agents Explained

Playwright comes with three specialized agents that work together sequentially or independently:

🎭

Planner

Explores & Plans

🎭

Generator

Creates Tests

🎭

Healer

Fixes Failures

🎭

Planner Agent

The Planner explores your application like a real user, following natural tab order and interactive elements. It produces a detailed Markdown test plan with scenarios, user flows, and edge cases.

Example Prompt (Try It!):

"Explore https://practiceautomatedtesting.com/shopping and create a test plan for the shopping cart functionality"

Output Location:

specs/shopping-cart.md

🎭

Generator Agent

The Generator reads Markdown test plans and transforms them into executable Playwright tests. It actively interacts with your app to verify selectors and assertions work correctly before generating code.

Example Prompt:

"Generate Playwright tests from the shopping-cart test plan in specs/"

Output Location:

tests/shopping-cart.spec.ts

🎭

Healer Agent

The Healer runs tests in debug mode, analyzes console logs, network requests, and page snapshots to identify root causes of failures. It automatically patches broken tests or marks them as skipped if functionality is actually broken.

Example Prompt:

"Run the shopping cart tests and fix any failures"

What it does:

Identifies UI changes, updates selectors, re-runs tests until passing

Complete Workflow: From Exploration to Self-Healing Tests

1

Initial Setup

Run the initialization command to set up Playwright Test Agents for your AI assistant:

# For Claude Code
npx playwright init-agents --loop=claude

# For VS Code Copilot
npx playwright init-agents --loop=vscode

# For other OpenCode-compatible editors
npx playwright init-agents --loop=opencode

This adds Playwright Test Agent definitions to your project. Re-run when you update Playwright to get new tools and instructions.

arrow_downward
2

Planner: Explore & Create Test Plan

You say in Claude Code:

"Explore the shopping flow at https://practiceautomatedtesting.com/shopping and create a comprehensive test plan. Save it as shopping-flow in the specs folder."

arrow_downward

Planner explores and generates: specs/shopping-flow.md

# Shopping Flow Test Plan

## Application Overview
E-commerce shopping cart functionality...

## Test Scenarios

### Scenario 1: Add Item to Cart
1. Navigate to /shopping
2. Click "Add to Cart" on first product
3. Verify cart count increases to 1
4. Verify cart icon updates

### Scenario 2: Remove Item from Cart
1. Navigate to cart page
2. Click "Remove" on product
3. Verify cart count decreases
4. Verify empty cart message

### Scenario 3: Checkout Flow
1. Add products to cart
2. Proceed to checkout
3. Fill billing information
4. Submit order
5. Verify confirmation message
arrow_downward
3

Generator: Create Playwright Tests

You say in Claude Code:

"Generate Playwright tests from the shopping-flow test plan. Verify all selectors work."

arrow_downward

Generator creates: tests/shopping-flow.spec.ts

import { test, expect } from '@playwright/test';

test('add item to cart', async ({ page }) => {
  await page.goto('https://practiceautomatedtesting.com/shopping');

  // Add first product to cart
  await page.getByRole('button', { name: 'Add to Cart' }).first().click();

  // Verify cart count
  await expect(page.getByTestId('cart-count')).toHaveText('1');

  // Verify cart icon badge
  await expect(page.locator('.cart-badge')).toBeVisible();
});

test('remove item from cart', async ({ page }) => {
  await page.goto('https://practiceautomatedtesting.com/cart');

  // Remove product
  await page.getByRole('button', { name: 'Remove' }).first().click();

  // Verify empty cart message
  await expect(page.getByText('Your cart is empty')).toBeVisible();
});
arrow_downward
4

Healer: Run & Auto-Fix Tests

Test Failure Detected:

❌ Test Failed: shopping-flow.spec.ts > add item to cart

Error: Locator not found
  page.getByTestId('cart-count')

Reason: Element selector changed from 'cart-count' to 'shopping-cart-count'

You say in Claude Code:

"Run the shopping tests and fix any failures"

auto_fix_high

Healer analyzes, fixes, and updates the test:

test('add item to cart', async ({ page }) => {
  await page.goto('https://practiceautomatedtesting.com/shopping');

  await page.getByRole('button', { name: 'Add to Cart' }).first().click();

  // ✅ Healer updated selector automatically
  - await expect(page.getByTestId('cart-count')).toHaveText('1');
  + await expect(page.getByTestId('shopping-cart-count')).toHaveText('1');

  await expect(page.locator('.cart-badge')).toBeVisible();
});

✅ Test now passes! Healer identified the UI change and fixed the selector.

Works With Your Favorite AI Assistant

Playwright Test Agents work with any AI coding assistant that supports MCP (Model Context Protocol):

terminal

Claude Code

Anthropic's CLI tool with native MCP support

npx playwright init-agents \
  --loop=claude
code

VS Code

GitHub Copilot in Visual Studio Code

npx playwright init-agents \
  --loop=vscode
edit

Cursor / Others

Any OpenCode-compatible editor

npx playwright init-agents \
  --loop=opencode

How It Works: MCP + AI Agents

1

MCP Communication

Playwright Test Agents are custom AI subagents defined as collections of instructions and MCP tools provided by Playwright. They communicate with your AI assistant through the Model Context Protocol.

2

Accessibility Tree Analysis

The agents use the browser's accessibility tree to understand page structure, identify interactive elements, and verify selectors - no screenshots needed.

3

Live Verification

The Generator agent actively navigates your app to verify that selectors work and assertions are valid before generating code - ensuring tests work from the start.

4

Debug & Heal Loop

The Healer runs tests in debug mode, captures console logs, network requests, and snapshots, identifies root causes, patches code, and re-runs until tests pass.

Key Benefits

speed

10x Faster

  • checkTest design in minutes, not hours
  • checkAutomatic exploration and planning
  • checkPre-verified selectors and assertions
auto_fix_high

Self-Healing

  • checkAutomatically fixes broken selectors
  • checkAdapts to UI changes
  • checkReduces maintenance burden
verified

Official & Reliable

  • checkBuilt by the Playwright team
  • checkOpen source and well-documented
  • checkWorks with multiple AI assistants

Ready to Automate Your Test Creation?

Get started with Playwright Test Agents and let AI plan, generate, and heal your test suite

Frequently Asked Questions

Do I need Playwright v1.56 or higher?

Yes! Playwright Test Agents were introduced in v1.56 (October 2024). Make sure you're running Playwright v1.56+ to use these features. Run npx playwright --version to check your version.

Which AI assistant should I use?

All MCP-compatible AI assistants work well. Claude Code is great for terminal workflows, VS Code Copilot integrates with your existing setup, and Cursor offers an AI-first experience. Choose based on your preferred development environment.

Can the agents work with my existing tests?

Yes! The Healer agent can analyze and fix your existing Playwright tests. The Planner can also supplement your test coverage by exploring areas you haven't tested yet.

How accurate are the generated tests?

Very accurate! The Generator actively interacts with your app to verify selectors and assertions before generating code. However, you should always review generated tests to ensure they match your specific test requirements and business logic.

Can I use these agents on my own website?

Absolutely! Playwright Test Agents work with any website - localhost, staging, or production. Just provide the URL in your natural language prompt and the agents will explore and test your site.

Is this free to use?

Playwright Test Agents are free and open source as part of Playwright. However, you'll need access to an AI assistant (Claude Code, GitHub Copilot, etc.), which may have their own pricing. Check the pricing for your chosen AI assistant.