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.
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.
Three Specialized AI Agents
- 🎭 Planner - Explores your app and creates Markdown test plans
- 🎭 Generator - Converts test plans into executable Playwright tests
- 🎭 Healer - Automatically fixes failing tests by analyzing errors
Powered by: Playwright MCP (@playwright/mcp) + AI Assistants
Introduced: Playwright v1.56 (October 2024)
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!
What's Included
- Live Test Site: practiceautomatedtesting.com/shopping - A real shopping cart to practice on
- Example Test Plans: Pre-made specs showing how the Planner agent works
- Sample Tests: Generated tests you can study and modify
- Setup 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
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.
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."
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
Generator: Create Playwright Tests
You say in Claude Code:
"Generate Playwright tests from the shopping-flow test plan. Verify all selectors work."
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(); });
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"
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):
Claude Code
Anthropic's CLI tool with native MCP support
npx playwright init-agents \ --loop=claude
VS Code
GitHub Copilot in Visual Studio Code
npx playwright init-agents \ --loop=vscode
Cursor / Others
Any OpenCode-compatible editor
npx playwright init-agents \ --loop=opencode
How It Works: MCP + AI Agents
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.
Accessibility Tree Analysis
The agents use the browser's accessibility tree to understand page structure, identify interactive elements, and verify selectors - no screenshots needed.
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.
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
10x Faster
- Test design in minutes, not hours
- Automatic exploration and planning
- Pre-verified selectors and assertions
Self-Healing
- Automatically fixes broken selectors
- Adapts to UI changes
- Reduces maintenance burden
Official & Reliable
- Built by the Playwright team
- Open source and well-documented
- Works 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.