Playwright Agents Explained: Planner, Generator, and Healer in a Real Workflow

Playwright agents are three first-party AI agents that ship with Playwright - the Planner explores your app and writes a Markdown test plan, the Generator turns that plan into executable Playwright Test code verified against the live app, and the Healer runs the suite and repairs failing tests. That is the whole idea in one sentence. Introduced in Playwright v1.56, Playwright agents are the framework team’s own answer to AI test generation - not a third-party wrapper, but a workflow baked into the tool most web automation teams already use. This guide walks through what each agent does, how they fit a real workflow, setup, code, and the limits you should understand before trusting the output.

The three agents at a glance

The pipeline is deliberately shaped like how a good automation team already works: plan first, generate against the real application, and treat failures as triage work rather than noise. The difference is that each stage now has an agent doing the mechanical part.

One architectural point worth underlining: the agents use the LLM at authoring and triage time only. What lands in your repo is ordinary Playwright code. Your CI pipeline runs deterministic specs with zero AI calls at runtime - no per-run token cost, no nondeterministic execution. That separation is what makes this approach CI-safe, and it is the same property we look for when comparing AI browser tools in Stagehand vs browser-use vs Playwright MCP.

Setup: one command plus a seed test

Playwright agents run inside an AI coding loop - VS Code (v1.105+), Claude Code, Codex, or OpenCode. You generate the agent definitions with:

npx playwright init-agents --loop=vscode
# or: --loop=claude | --loop=codex | --loop=opencode

This drops agent definition files into your project, wired to Playwright MCP under the hood so the agents can drive a real browser through structured accessibility snapshots rather than screenshots. Two practical notes:

• Re-run init after upgrading Playwright. The agent definitions are regenerated with each release, so treat them as build output, not hand-edited files.
• Write a seed test. The Planner needs a known starting state. A seed test is a tiny ordinary spec that handles environment setup - base URL, authentication, feature flags:

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

test('seed', async ({ page }) => {
  await page.goto('/');
  await page.getByLabel('Email').fill(process.env.TEST_USER!);
  await page.getByLabel('Password').fill(process.env.TEST_PASS!);
  await page.getByRole('button', { name: 'Sign in' }).click();
});

Everything the agents do starts from the state this test produces. A weak seed - wrong environment, missing test data - is the most common reason early runs disappoint.

The Planner: exploration into a reviewable plan

You give the Planner a goal in natural language - “plan tests for the checkout flow” - and it explores the running application in a browser, following links, opening forms, and observing states. The output is not code. It is a Markdown plan, something like specs/checkout.md, containing scenarios with preconditions, steps, expected outcomes, and success and failure criteria.

That intermediate artifact is the smartest design decision in the whole system. A Markdown plan is something a product owner or QA lead can actually review. You catch “this scenario tests the wrong thing” at the plan stage, before anyone has generated a line of code. Edit the plan, delete scenarios that do not matter, add the edge cases the agent could not know about - the plan is yours.

The Generator: plans into verified code

The Generator takes a plan file and produces executable Playwright Test specs. Crucially, it does not write code blind. It works against the live application, checking that each locator resolves, preferring resilient role-based and label-based locators, and confirming assertions actually hold before committing them to the file. The result looks like code a careful engineer would write:

// tests/checkout.spec.ts (generated, then reviewed)
import { test, expect } from '@playwright/test';

test('applies a discount code at checkout', async ({ page }) => {
  await page.goto('/cart');
  await page.getByRole('button', { name: 'Checkout' }).click();
  await page.getByLabel('Discount code').fill('SAVE10');
  await page.getByRole('button', { name: 'Apply' }).click();
  await expect(page.getByTestId('order-total')).toContainText('$90.00');
});

This is where playwright ai test generation earns its keep: verifying selectors against a real DOM removes the classic failure mode of LLM-written tests - plausible-looking locators that never existed. You still review the diff like any other pull request, because the Generator can pick a technically-valid assertion that misses the business point.

The Healer: triage-time repair, not runtime magic

The Healer is what people usually mean when they ask about self-healing Playwright tests, and it is worth being precise about what it does. When a test fails, the Healer:

1. Re-runs the failing test and replays the steps in a real browser.
2. Inspects the current UI to understand what changed.
3. Patches the test - a replacement locator after a redesign, an adjusted wait, an updated step order when the flow changed.
4. Re-runs until the test passes.
5. Stops if the functionality itself appears broken, leaving the test failing so a real regression is not silently patched away.

Point 5 is the line between a useful tool and a dangerous one. Healing that happens invisibly at runtime can turn a red build green while a real bug ships. The Healer instead produces code changes you review in a diff, and it is designed to distinguish “the button moved” from “the button is gone.” Keep a human on that review: an agent’s judgment about whether behavior is a bug or a redesign is a guess informed by the UI, not by your product requirements.

How this fits a real test-automation workflow

Here is the loop we set up for teams adopting the agents:

1. Seed and scope. An engineer writes the seed test and decides which flows deserve automated coverage. This is a strategy call, not an agent call.
2. Plan and review. The Planner drafts plans; a human edits them. Ten minutes of plan review saves hours of code review.
3. Generate and gate. The Generator writes specs; they go through normal pull-request review with the same bar as any other code - naming, assertions, test data, no leaked waits.
4. Run deterministic CI. The suite runs as plain Playwright in CI. No AI, no per-run cost, standard flake tracking.
5. Heal on failure, review the patch. When the app changes and tests break, the Healer drafts the fix and an engineer approves or rejects it - and asks whether a rejected heal means a bug escaped to staging.

Teams that skip steps 2 and 3 end up with a large, shallow suite nobody trusts. Teams that keep them get the real win: the mechanical 70 percent of automation work - exploring, drafting, locator hunting, selector maintenance - moves to the agents, and engineers spend their time on the 30 percent that decides whether the suite is worth anything.

Limitations to plan around

• Nondeterministic authoring. Two Planner runs produce different plans. That is fine for drafts, but pin your suite’s shape with review, not regeneration.
• Token cost scales with UI complexity. Exploration and healing are LLM-heavy on large apps. Budget for it, and prefer healing targeted failures over regenerating suites.
• Coverage is bounded by the seed. The agents test what they can reach from the seeded state. Multi-role flows, emails, webhooks, and data setup still need engineering.
• Assertions need business review. The Generator verifies that assertions pass, not that they matter. A checkout test asserting the page title is green and useless.
• Healing can mask real bugs if unreviewed. The Healer tries to detect genuine breakage, but the final call belongs in code review.
• The moving-target problem. Agent definitions regenerate each release, and behavior evolves version to version - keep your Playwright upgrades deliberate.

Do you still need SDET engineering?

Yes - the job shifts rather than disappears. What the agents genuinely absorb is scaffolding work: exploring pages, drafting scenarios, writing locator-correct code, fixing broken selectors. What remains is exactly the work that separates an SDET from a QA engineer: deciding what to test and at which layer, designing test data and environments, building CI infrastructure that reports failures people believe, reviewing generated code and healing patches, and owning the judgment call on every “is this a bug or a redesign” moment. If anything, AI test generation raises the bar - a team that can generate 200 tests in an afternoon needs stronger engineering discipline, not weaker, to keep those tests meaningful. The choice of AI coding loop matters too; we compared the main contenders in Claude Code vs Cursor vs Codex for test automation.

Related reading

• Stagehand vs browser-use vs Playwright MCP - how the agents’ MCP foundation compares to the other AI browser automation stacks
• Selenium vs Playwright - the framework decision underneath all of this
• Claude Code vs Cursor vs Codex for test automation - choosing the AI loop the agents run inside
• What is an SDET - how the role changes when agents do the typing

Getting help

We help teams adopt Playwright agents without ending up with a pile of unreviewed AI-generated specs. An AI-Augmented Test Generation engagement at sdet.qa sets up the agents, MCP, seed tests, and the review workflow, then hands your team a suite that stays trustworthy - or a Test Automation Framework Engineering engagement if the foundation itself needs building first.

Book a free scope call.