AI & agentic testing

Playwright Test Agents: Planner, Generator and Healer Explained (and Where They Fall Short)

Aslam KhanAslam Khan 10 min read
Playwright Test Agents: a planner, a generator and a healer agent in a row, with a person reviewing every heal

You run one command, open Claude Code or VS Code, and type "plan tests for guest checkout". A few minutes later you have a Markdown test plan, a folder of Playwright tests and an agent that offers to fix whichever ones fail.

That's the promise of Playwright Test Agents. It's real, and it's useful. It also raises the question every QA lead asks next: if an AI agent fixes the failing tests, who checks that it fixed the test and not the bug?

Playwright Test Agents are three AI agent definitions that ship with Playwright: a planner that explores your app and writes a Markdown test plan, a generator that turns the plan into Playwright test files, and a healer that runs failing tests and patches them. You install them with npx playwright init-agents and run them in Claude Code, VS Code, Codex or OpenCode.

This guide explains how each agent works, how to set them up, what the healer can and can't be trusted with, and when a team needs more than three agents in a repository.

Key takeaways

  • One command sets them up: npx playwright init-agents --loop=claude (or vscode, codex, opencode).
  • The planner needs a seed test that gets the app into a ready state, such as signed in.
  • The healer can mark a test as skipped when it decides the feature is broken. Review every healer change before it merges.
  • They write and repair Playwright code in your repo. Running, scheduling and reporting at scale is still your job.

What are Playwright Test Agents?

Playwright Test Agents arrived in Playwright 1.56. The Playwright docs describe them as three agents that "can be used independently, sequentially, or as the chained calls in the agentic loop."

AgentInputWhat it doesOutput
PlannerA request, a seed test, optionally a product specExplores the running app in a real browserA Markdown test plan in specs/
GeneratorA Markdown plan from specs/Writes tests and checks selectors and assertions live against the appPlaywright test files in tests/
HealerThe name of a failing testReplays the steps, inspects the current UI, patches the test and re-runs itA passing test, or a skipped one

Each agent is a set of instructions plus Playwright's MCP browser tools. The AI model is whatever your client uses, so quality depends on the model as well as on Playwright.

How do you set up Playwright Test Agents?

You need an existing Playwright Test project. Then run the command for your client:

npx playwright init-agents --loop=claude    # Claude Code
npx playwright init-agents --loop=vscode    # VS Code with Copilot
npx playwright init-agents --loop=codex     # OpenAI Codex
npx playwright init-agents --loop=opencode  # OpenCode

The command writes the agent definitions into your project. For VS Code, the docs say you need VS Code v1.105 or later for the agentic experience to work properly.

After a run, a typical project looks like this:

.github/                # agent definitions written by init-agents
specs/                  # Markdown test plans from the planner
tests/
  seed.spec.ts          # gets the app into a ready state
  guest-checkout.spec.ts
playwright.config.ts

Two rules save a lot of confusion:

  1. Regenerate the agent definitions after every Playwright upgrade. The docs say they "should be regenerated whenever Playwright is updated." Assume regeneration replaces the generated files, so keep your own custom instructions somewhere else.
  2. Commit specs/ with your tests. The plan is the human-readable record of what each test is meant to prove. It's what you'll check the healer's changes against later.

How does the planner work?

The planner opens your app, explores the flow you ask about and writes a plan for one or many scenarios. Before it explores, it runs your seed test, which does all the setup a test needs: opening the right page, signing in, seeding data.

A seed test can be very small. This one is illustrative:

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

test('seed', async ({ page }) => {
  await page.goto('https://staging.example.com/login');
  await page.getByLabel('Email').fill(process.env.TEST_USER_EMAIL!);
  await page.getByLabel('Password').fill(process.env.TEST_USER_PASSWORD!);
  await page.getByRole('button', { name: 'Sign in' }).click();
  await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
});

Then ask for a plan in plain language, for example: "Use the planner agent to create a test plan for applying a discount code at checkout. Cover valid, expired and already-used codes."

The planner saves a Markdown file in specs/. The docs call it "human-readable but precise enough for test generation". It lists scenarios, steps and expected results. Read it before you generate anything. A wrong plan produces confident, wrong tests.

What makes plans better:

  • Ask for one flow at a time. "Checkout with discount codes" beats "test the store".
  • Give it the rules it can't see. Business rules such as "codes are case-insensitive" or "only one code per order" should be in the prompt or the spec you attach.
  • Name the negative cases. Agents cover the happy path well and the edge cases only when asked.

How does the generator turn a plan into tests?

The generator reads the plan and writes Playwright tests. It doesn't just translate text into code. It runs the steps in a browser and checks that selectors and assertions work against the live app.

Generated files point back to their sources with comments, which makes review easier:

// spec: specs/discount-codes.md
// seed: tests/seed.spec.ts
import { test, expect } from '@playwright/test';

test('expired discount code shows an error', async ({ page }) => {
  await page.goto('https://staging.example.com/cart');
  await page.getByLabel('Discount code').fill('SPRING2025');
  await page.getByRole('button', { name: 'Apply' }).click();
  await expect(page.getByText('This code has expired')).toBeVisible();
  await expect(page.getByTestId('order-total')).toHaveText('$120.00');
});

(Illustrative output; your generator's code will differ.)

The docs are upfront that generated tests "may include initial errors" that the healer can then fix. In practice, review three things in every generated test:

  1. Does each assertion check an outcome, or only that a page loaded? "Order total unchanged" is a real check. "The page is visible" isn't.
  2. Are the locators role- or label-based? They survive redesigns better than CSS paths. Our Playwright best practices guide covers this in depth.
  3. Is test data fixed or generated? Hard-coded codes and users break the second time a test runs against a shared environment.

What does the healer actually fix?

When a test fails, you give the healer its name. According to the docs, it:

  • replays the failing steps
  • inspects the current UI to find equivalent elements or flows
  • suggests a patch, such as a new locator, a wait or a data fix
  • re-runs the test until it passes or until guardrails stop the loop

The result is "a passing test, or a skipped test if the healer believes that functionality is broken."

That last line is the one to think hardest about.

Can the healer hide real bugs?

Yes, if you let it merge changes nobody reviews. This is the biggest worry testers raise about AI healing, and it's fair. One reviewer on a QA forum described the risk as "an easy always green model".

A test can fail for two very different reasons:

FailureExampleRight fix
The test is out of dateThe "Apply" button was renamed "Redeem"Update the locator. Healing is exactly right.
The product is brokenThe discount no longer changes the totalFail the build and file a bug. "Healing" this is hiding it.

A healer that changes an assertion from $108.00 to $120.00, or skips a test "because the feature looks broken", turns the second case into a green build. The agent isn't being malicious. It was asked to make a test pass.

Guardrails that keep healing honest:

  • Healer changes go through pull requests, like any other code. Never let an agent push straight to your main branch.
  • Treat locator changes and assertion changes differently. A new locator is usually safe. A changed expected value or a deleted expect needs a human who knows the feature.
  • Fail CI on new skips. A short script can block any pull request that adds test.skip or test.fixme, or removes assertions, until someone approves it:
# Fails if a pull request adds skipped tests or deletes assertions under tests/
BASE=origin/main
if git diff -U0 "$BASE"...HEAD -- tests | grep -qE '^\+.*\btest\.(skip|fixme)\('; then
  echo "New skipped or fixme tests found. Get a reviewer to approve them."
  exit 1
fi
REMOVED=$(git diff -U0 "$BASE"...HEAD -- tests | grep -cE '^-\s*(await\s+)?expect\(' || true)
if [ "$REMOVED" -gt 0 ]; then
  echo "$REMOVED assertion(s) removed. Get a reviewer to approve them."
  exit 1
fi
  • Check changes against the plan. If the healed test no longer proves what its specs/ scenario says, the heal is wrong.

For a wider look at keeping AI agents' test results trustworthy, see why confidence is the real bottleneck in agentic testing.

What's new for Playwright agents since 1.56?

Playwright has added agent features steadily since the test agents launched. From the release notes:

  • 1.59: coding agents can run npx playwright test --debug=cli and explore traces with npx playwright trace. Agents can also record "agentic video receipts" of what they did.
  • 1.62: Playwright bundles the Playwright MCP server and playwright-cli, so npx playwright mcp and npx playwright cli work without separate installs.
  • 1.64: Playwright MCP supports WebMCP by default.

The Playwright CLI also installs "skills" for Claude Code, GitHub Copilot and Cursor, including one to plan, generate and heal tests. It's a lighter-weight route to the same workflow.

Test Agents vs Playwright MCP vs Playwright CLI: which do you need?

Test AgentsPlaywright MCPPlaywright CLI with skills
What it isPredefined planner, generator and healer agentsBrowser tools for any MCP clientA command-line tool and skills for coding agents
Best forBuilding and repairing a Playwright suite in your repoExploring, debugging, one-off agent sessionsCoding agents that work in a terminal
OutputPlans in specs/, tests in tests/Actions, snapshots, optional generated codeCommands and generated tests
Set up withnpx playwright init-agentsnpx @playwright/mcp@latest (also bundled as npx playwright mcp since 1.62)npm install -g @playwright/cli@latest

They aren't rivals. The test agents use Playwright's MCP tools under the hood, and many teams use all three. Our Playwright MCP guide covers MCP setup in Claude Code, Cursor and VS Code in detail.

What do teams report after using them?

The honest picture from early users is mixed:

  • Fast first drafts, in principle. A Ministry of Testing member working on small to medium web apps saw the appeal as getting a basic suite running quickly to kick-start automation on a new product (thread).
  • Rework is normal. A developer who compared the agents with AI-native platforms advised planning for rework on generated tests (dev.to).
  • Results depend on the model. The same plan can produce different tests with different models and on different days.

None of this is surprising for a tool that's only a year old. It does mean the agents speed up writing tests, while owning the suite is still a job for your team.

When should you use Playwright Test Agents?

They're a strong fit when:

  • your team already writes Playwright tests in TypeScript and reviews them in pull requests
  • you want to add coverage to a web app quickly and can review generated code
  • developers own the tests and are happy to run them from your own CI

They're a weaker fit when:

  • most of your testers don't read code, so nobody can review what the generator and healer change
  • you test native mobile, desktop or API flows, or phone and chat agents, alongside web
  • you need run history, video evidence and audit trails for every release
  • your bottleneck is running and maintaining hundreds of journeys, not writing the first draft

Where does Robonito fit?

Robonito is an agentic QA platform. Its agents create, run and maintain end-to-end tests, and it covers the jobs that sit around the three Playwright agents rather than replacing Playwright.

  • Plain-language test creation. In AI Studio you describe what to test, paste a URL or reference a Jira issue, and the agent works through the app step by step. Testers who don't write TypeScript can build and review tests.
  • Healing you can audit. Self-healing adapts steps when labels, layouts or locators change, and every healed step is logged for review. That's the guardrail this post recommends, built in.
  • Runs and evidence. Tests run in parallel in isolated cloud workers, from Jenkins, GitHub Actions, GitLab CI, Azure DevOps or CircleCI. Every run keeps video, network traces and an AI root cause for failures.
  • More than web. Mobile (Android and iOS), desktop and API testing are on the Pro and Enterprise plans.
  • No lock-in. Robonito can generate executable code for your test cases.

Where Playwright Test Agents are the better choice: a developer-owned suite that should live entirely in your repository as Playwright code, with no platform and no extra cost beyond your model's tokens.

For a fuller comparison, see Robonito vs Playwright. Or on a flow you've already planned with the planner agent.

Frequently asked questions

Are Playwright Test Agents free?

Yes. They ship with Playwright, which is open source. You pay for the AI model your client uses, such as Claude Code, Copilot or Codex.

Which Playwright version do the test agents need?

They were introduced in Playwright 1.56. Use a current release and regenerate the agent definitions with npx playwright init-agents after each upgrade.

Do Playwright Test Agents work with Claude Code?

Yes. Run npx playwright init-agents --loop=claude. The docs also list VS Code, Codex and OpenCode loops.

What is the seed test in Playwright Test Agents?

It's a normal Playwright test that sets up everything other tests need, such as signing in. The planner runs it before exploring, and uses it as an example for the tests it plans.

Can the healer agent fix any failing test?

It can fix tests that broke because the UI changed, such as a renamed button or a new layout. If it decides the feature itself is broken, it can mark the test as skipped. Review those changes: a skipped test may be hiding a real bug.

What's the difference between Playwright Test Agents and Playwright MCP?

Playwright MCP gives any MCP-capable AI client tools to drive a browser. Test Agents are three predefined agents that use those tools to plan, generate and heal Playwright tests in your repository.

Can Playwright Test Agents test mobile apps?

Not native apps. They drive browsers, so they can test mobile web with a phone-sized viewport, but native Android and iOS apps need a different tool.


Let the agents draft. Keep the suite trustworthy. Robonito runs your critical journeys on every release, with healing your team can review and evidence for every run. or .

Free whitepaperThe Agentic QA PlaybookMove from test scripts to AI agents in 90 days, with the controls, metrics and a 25-question vendor checklist.

No-code AI test automation

Spend less time testing and more time shipping.

3Pillar showed Robonito's agents to its own client live, and that client is now onboarding. Start on the Free plan, which stays free forever, or book a demo and we'll walk through your own app.

All blog posts