Browse all tutorials →
AI Testing August 15, 2026 13 min read

Playwright Test Agents 2026: Planner, Generator & Healer Guide

Playwright v1.56 added built-in test agents: a planner that explores your app and writes a test plan, a generator that turns the plan into verified tests, and a healer that repairs failing ones. This guide covers setup with init-agents, what each agent produces, and how to review their work.

🤖

Key takeaway: three agents, driven by your AI tool

Since v1.56, Playwright ships agent definitions for a planner, a generator and a healer. npx playwright init-agents adds them to your project, and you run them from Claude Code, VS Code or OpenCode. The planner writes a Markdown test plan, the generator turns it into tests it has checked in a live browser, and the healer repairs failing tests. You still review everything.

If you have spent years writing Playwright tests by hand, you know where the time goes: finding locators, turning requirements into steps, and fixing tests after every UI change. Playwright Test Agents take on those three jobs. One agent plans what to test, one generates the test code, and one heals tests that break.

They are not a separate product or a paid add-on. They ship with Playwright from v1.56, and they run inside the AI coding tool you already use. This guide covers how they work, how to set them up, what each agent produces, and the review habits that keep them safe.


What Are Playwright Test Agents?

Playwright Test Agents are agent definitions: instructions plus a set of Playwright tools that an AI coding assistant follows. Playwright provides three of them:

  • Planner: explores your app and writes a Markdown test plan with scenarios, steps and expected results.
  • Generator: turns the plan into Playwright test files. As it works it performs each step in a real browser, so locators and assertions are checked against the live page instead of guessed.
  • Healer: runs a failing test, replays the failing steps, inspects the current UI and patches the test. If it decides the feature itself is broken, it can mark the test as skipped instead of forcing it green.

The model doing the reasoning is whichever one your tool uses: Claude in Claude Code, or the model you pick in GitHub Copilot. Playwright supplies the browser tools and the instructions. Nothing about the agents goes into playwright.config.ts, and Playwright has no setting for an LLM provider or API key.

Version requirement: Test Agents need Playwright v1.56 or later. Upgrade with npm install -D @playwright/test@latest. They are opt-in: nothing changes in your existing suite until you run init-agents.

How the Agent Pipeline Works

The agents can be used one at a time or in sequence. In sequence, each one's output is the next one's input:

Your request + seed test (+ optional PRD)
        |
        v
+------------------------+
|        PLANNER         |  <-- explores the app in a real browser
+------------------------+
        |  Markdown plan in specs/
        v
+------------------------+
|       GENERATOR        |  <-- performs each step, verifies locators
+------------------------+
        |  .spec.ts files in tests/
        v
+------------------------+
|   npx playwright test  |  <-- the normal test runner
+------------------------+
        |  failing test name
        v
+------------------------+
|         HEALER         |  <-- replays, inspects, patches, re-runs
+------------------------+
        |
        v
 Passing test OR skipped test (likely a real bug)

Two inputs matter more than anything else. The seed test (tests/seed.spec.ts) gets the app into a ready state, for example logged in with the right fixtures, and the agents copy its setup. Your request says what to cover. A vague request ("test the app") gets a shallow plan, while a specific one ("guest checkout, including invalid cards and empty required fields") gets a useful plan.

Setting Up Playwright Test Agents

Step 1: Install or upgrade Playwright

Terminal
# New project
npm init playwright@latest

# Existing project: upgrade to v1.56+
npm install -D @playwright/test@latest
npx playwright install

Step 2: Add the agent definitions

Run init-agents with the loop that matches your AI tool:

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

# VS Code with GitHub Copilot (VS Code v1.105+)
npx playwright init-agents --loop=vscode

# OpenCode
npx playwright init-agents --loop=opencode

The command writes the planner, generator and healer definitions into the folder your tool reads them from (.claude/ for Claude Code, .github/ for VS Code). It also registers the Playwright tools the agents call, and creates a specs/ folder for plans plus a tests/seed.spec.ts to edit. Commit these files so the whole team uses the same agents.

Re-run after every Playwright upgrade. The definitions are tied to your Playwright version. When you upgrade, run init-agents again so the agents get the new tools and instructions.

Step 3: Write a seed test

The seed test is an ordinary Playwright test that sets up the environment. If your tests use custom fixtures for login or test data, import them here:

tests/seed.spec.ts
import { test, expect } from './fixtures';

test('seed', async ({ page }) => {
  // Uses the same fixtures as the rest of the suite (e.g. a logged-in user).
  await page.goto('/');
});

There is no API key to set in Playwright. The agents use whatever account your AI tool is signed in with: a Claude plan or API credits for Claude Code, or a Copilot subscription for VS Code.

The Planner Agent

The planner's job is to decide what should be tested. It runs the seed test, explores the pages involved in your request, and writes a plan you can read and edit. Ask for it in plain English in your AI tool:

Prompt in Claude Code
Use the Playwright test planner agent to create a test plan for guest checkout.
Cover the happy path, an invalid card, and submitting with empty required fields.
Use tests/seed.spec.ts as the seed.

The output is a Markdown file in specs/. It is written for humans, so a QA lead can review it before any code exists:

specs/guest-checkout.md (excerpt)
# Guest Checkout Test Plan

## 1. Checkout

### 1.1 Complete checkout with a valid card
**Steps:**
1. Add any product to the cart and open the cart
2. Click "Checkout as guest"
3. Fill name, street address, city and ZIP code
4. Enter a valid test card and click "Place order"

**Expected results:**
- The "Order confirmed" heading is visible
- An order number is shown
- The cart badge shows 0

### 1.2 Invalid card shows an error
...

Treat the plan as a draft. Delete scenarios that don't matter and add the business rules the planner can't know. Editing a Markdown plan is far cheaper than reviewing code that tests the wrong things.

The Generator Agent

The generator agent, sometimes called the Microsoft Playwright Generator Agent, turns a Markdown plan into Playwright tests. What sets it apart from asking a chatbot for a test is that it performs every step in a real browser while it writes. Each locator is checked against the live page and each assertion is checked against what the page really shows, before it reaches the file.

Prompt in Claude Code
Use the Playwright test generator agent to generate tests for section 1
of specs/guest-checkout.md.

The generated file records which plan and seed it came from, so you can trace every test back to a reviewed scenario:

tests/guest-checkout/valid-card.spec.ts
// spec: specs/guest-checkout.md
// seed: tests/seed.spec.ts

import { test, expect } from '../fixtures';

test.describe('Checkout', () => {
  test('Complete checkout with a valid card', async ({ page }) => {
    // 1. Add any product to the cart and open the cart
    await page.goto('/products');
    await page.getByRole('button', { name: 'Add to cart' }).first().click();
    await page.getByRole('link', { name: 'Cart' }).click();

    // 2. Click "Checkout as guest"
    await page.getByRole('button', { name: 'Checkout as guest' }).click();

    // 3. Fill name, street address, city and ZIP code
    await page.getByLabel('Full name').fill('Jane Smith');
    await page.getByLabel('Street address').fill('123 Main St');
    await page.getByLabel('City').fill('Austin');
    await page.getByLabel('ZIP code').fill('78701');

    // 4. Enter a valid test card and click "Place order"
    await page.getByLabel('Card number').fill('4242424242424242');
    await page.getByRole('button', { name: 'Place order' }).click();

    // Expected results
    await expect(page.getByRole('heading', { name: 'Order confirmed' })).toBeVisible();
    await expect(page.getByText(/Order #\d+/)).toBeVisible();
    await expect(page.getByTestId('cart-count')).toHaveText('0');
  });
});

Notice the locators: getByRole, getByLabel and getByTestId. The generator reads the page's accessibility tree, so it reaches for user-facing locators instead of CSS chains. Each step from the plan appears as a comment, which makes review quick: check that every expected result became a real assertion.

Generator review checklist

  • Every expected result is asserted. If the plan says "cart shows 0" and the test doesn't check it, the test is incomplete.
  • No hard-coded secrets or data that will change. Order numbers, dates and prices need patterns or fixtures.
  • Setup comes from fixtures. If the generator logged in through the UI in every test, move that into the seed fixtures.
  • It fails when it should. Break the feature or the expected text once and confirm the test goes red.

The Healer Agent

The healer works on one failing test at a time. You give it the failing test's name; it runs the test, replays the failing steps, inspects the current UI to find the equivalent element or flow, and proposes a patch: a locator update, a wait adjustment or a data fix. Then it re-runs, looping until the test passes or its guardrails stop it.

Prompt in Claude Code
Use the Playwright test healer agent to fix the failing test
"Checkout › Complete checkout with a valid card".

A typical case: a developer renames the "Place order" button to "Complete purchase". The healer sees the old locator resolve to nothing, finds the renamed button in the page, and updates the locator:

The healer's patch
- await page.getByRole('button', { name: 'Place order' }).click();
+ await page.getByRole('button', { name: 'Complete purchase' }).click();

The important part is what happens when the problem is the app, not the test. If the healer concludes that the functionality itself is broken, it can mark the test as skipped rather than rewriting it to pass. A skipped test from the healer is a bug report: investigate it, don't just un-skip it.

Review every healer diff. A locator rename is safe to accept. A changed expected value (a different total, a different message) needs a reason, because it may be hiding a regression. Read the diff like a pull request from a new teammate.

ARIA Snapshots: How the Agents See the Page

The agents read pages mainly through the accessibility tree, the same structure screen readers use, serialised as an ARIA snapshot. Every element appears with its role (button, textbox, heading, link), its accessible name and its state:

ARIA snapshot: login form
- heading "Sign In" [level=1]
- textbox "Email address"
- textbox "Password"
- checkbox "Remember me"
- button "Sign In"
- link "Forgot your password?"

This is why the agents write getByRole('button', { name: 'Sign In' }) instead of .btn-primary: the role and name are exactly what the snapshot gives them. It has practical benefits:

  • Compact. A text snapshot costs far fewer tokens than analysing a screenshot.
  • Precise. Roles, names and states (checked, disabled, expanded) are explicit, not inferred from pixels.
  • Stable locators. Roles and labels change less often than CSS classes, so generated tests survive restyling.

It also has a blind spot: the accessibility tree says nothing about how the page looks. A button with the right label in the wrong colour passes. Use visual regression tests for that. Accessibility gaps in your app (unlabelled inputs, div buttons) also make the agents' job harder, which is a good reason to fix them; see ARIA snapshot testing.

Playwright Agents vs Claude AI + MCP Server

If you already use Claude with the Playwright MCP Server, the two approaches overlap: both let an AI drive a real browser. The difference is structure.

Playwright Test Agents

  • A fixed, repeatable workflow: plan, generate, heal
  • Plans saved as Markdown in specs/, so they can be reviewed and versioned
  • Generated tests trace back to a plan and a seed test
  • Best for: building and maintaining a regression suite in a Playwright project

Claude + Playwright MCP Server

  • Open-ended conversation: explore, investigate, debug, ask questions
  • Works for one-off tasks that don't fit plan → generate → heal
  • Combines with Claude Code's own subagents and project rules
  • Best for: exploratory testing, debugging a flaky test, investigating a bug

Most teams use both: the agents for the day-to-day suite, and Claude with the MCP Server for the investigative work. The MCP Server setup guide covers connecting Claude to a browser.

Real-World Agent Workflow Example

Here is the full loop for one feature, product search, as a team would actually run it.

Step 1: Plan, then edit the plan

Prompt
Use the Playwright test planner agent to plan tests for product search:
a matching query, a query with no results, and an empty search.
Use tests/seed.spec.ts as the seed. Save the plan as specs/product-search.md.

Open specs/product-search.md. Remove anything out of scope, and add rules the planner can't know, for example "results are sorted by relevance, not price".

Step 2: Generate and review

Prompt
Use the Playwright test generator agent to generate tests for specs/product-search.md.

Run npx playwright test tests/product-search, then review the files against the plan with the generator checklist above. Commit the plan and the tests together in one pull request.

Step 3: Heal after a UI change

Two sprints later the search box's label changes from "Search products" to "Find items" and two tests fail.

Prompt
Use the Playwright test healer agent to fix the failing tests in tests/product-search.

The healer updates the two locators and re-runs them. You read the diff, confirm only locators changed, and merge. If the healer had skipped a test instead, you would file a bug.

To run this loop in CI, drive the healer through your AI tool in a pipeline job and have it open a pull request rather than pushing to main. Playwright AI agents in GitHub Actions walks through that setup.

Limitations and Best Practices

What the agents can't do

  • Know your business rules. The planner can see a discount field; it can't know your discount policy unless you tell it (a PRD in the request helps).
  • Set up data they can't reach. Database state, feature flags and third-party services still need fixtures, seeding or mocks, ideally in the seed test.
  • Judge appearance or performance. They test behaviour through the accessibility tree, not looks or speed.
  • Replace review. They produce drafts and patches; a person still approves them.

Best practices

  1. Invest in the seed test. Good fixtures in the seed mean every generated test starts from a clean, realistic state.
  2. Review the plan before the code. It's faster, and it catches the expensive mistake of testing the wrong thing.
  3. Keep plans in the repo. specs/ becomes living documentation of what the suite covers.
  4. Treat healer skips as bugs. Investigate before un-skipping.
  5. Re-run init-agents after upgrades so definitions match your Playwright version.

Human review is non-negotiable. Teams get burned when they merge agent output unread. The QA engineer's job shifts from typing tests to deciding what to test and approving what the agents write. That job doesn't go away.


Learn Playwright Test Agents Hands-On

The agents are only as good as your ability to review their output, so the order you learn in matters: Playwright fundamentals first, then the AI tools.

Playwright + Claude AI & MCP Server: AI QA Automation 2026 on Udemy follows that order in JavaScript:

  • Playwright from scratch: locators, assertions, hooks, timeouts and the Page Object Model
  • Installing Playwright Test Agents and using the generator agent in practice
  • Claude Code for generating tests and reports, plus custom QA subagents
  • Building a QA AI agent with Claude and the Playwright MCP Server
  • Multi-agent workflows with orchestrator and worker agents
  • GitHub Copilot chat, edit and agent modes for test automation

See the agents in action.

Playwright in JavaScript from scratch, then Test Agents, Claude Code and the Playwright MCP Server.

See the course plan →

Frequently Asked Questions

Are Playwright test agents free?

Yes. The agent definitions ship with Playwright from v1.56 at no cost. The AI doing the work is your own tool, so the cost is your Claude plan or API credits for Claude Code, or your GitHub Copilot subscription for VS Code.

How do I set up Playwright test agents?

Upgrade to Playwright v1.56 or later, then run npx playwright init-agents --loop=claude (or --loop=vscode or --loop=opencode). It adds the planner, generator and healer definitions, a specs/ folder and a seed test. Re-run it after every Playwright upgrade.

What does the Playwright generator agent do?

The generator agent turns a Markdown test plan from specs/ into Playwright test files. While writing, it performs each step in a real browser, so locators and assertions are checked against the live page. Each generated file notes the plan and seed test it came from.

Which AI models work with Playwright test agents?

Whatever model your AI tool uses: Claude in Claude Code, or the model you select in GitHub Copilot or OpenCode. There is no LLM provider or API key setting in playwright.config.ts; Playwright supplies the instructions and browser tools, and your tool supplies the model.

Does the healer agent hide real bugs?

It is designed not to. If the healer concludes the functionality itself is broken, it can mark the test as skipped instead of forcing it to pass. Still review every healer diff: a changed locator is usually safe, a changed expected value needs a reason.

Can Playwright test agents run in CI/CD?

Not as a flag on npx playwright test. You run the healer through your AI tool in a pipeline job, for example Claude Code in headless mode, and have it open a pull request with its fix so a person reviews it before merge.

Do Playwright agents replace manual test writing?

No. They speed up planning, writing and maintenance, but they don't know your business rules or which risks matter most. The QA engineer decides what to test, edits the plan, and reviews the generated tests before merging.

What is the difference between Playwright agents and Playwright MCP?

The Playwright MCP Server gives an AI assistant general browser control for any task: exploring, debugging, investigating. Test agents are a structured plan, generate and heal workflow built on Playwright's tools, aimed at building and maintaining a test suite. Many teams use both.


Asim Noaman, Playwright and Claude AI course instructor

Asim Noaman

Sr. SQA Manager & AI Automation Engineer

18+ years in QA. Asim currently runs an 80+ engineer QA function at Tkxel and built a Testing Center of Excellence for a major Saudi bank. He builds AI testing agents with Playwright, Claude AI and the MCP Server at work, and teaches the same workflow in his courses.

18+ Years in QA 80+ engineer QA function
Udemy Instructor 4.5★ · 140+ ratings · 570+ students
Anthropic Certificates Claude API · MCP
Connect on LinkedIn

Full profile →

Playwright + Claude AI Course

Ready to Make Claude AI Part of Your Real Test Suite?

This article covers the what. The course covers the how, step by step: Playwright in JavaScript from zero, then Playwright Test Agents and the generator agent, Claude Code with custom QA subagents, and a QA agent built on the Playwright MCP Server.

  • Generate complete Playwright tests from plain-English prompts
  • Install Playwright Test Agents and use the generator agent
  • Claude Code and the Playwright MCP Server for AI test generation
  • Build your own QA AI agent with Claude and MCP
Start the Course on Udemy →