Playwright Test Agents: AI That Plans, Generates, and Heals Your E2E Tests

End-to-end tests are the verification layer that lets you trust AI-written code, but writing and maintaining them is exactly the tedious work nobody wants. Playwright's answer is Test Agents — three specialized AI roles that, per the Playwright documentation, split the job into explore, write and repair: a planner, a generator and a healer. Each is a defined agent with its own instructions and tools, not a single black-box "write my tests" button.

The three agents

Planner (the explorer). Per the docs, the planner "explores the app and produces a Markdown test plan." It navigates your application and writes a human-readable plan in Markdown describing the scenarios worth covering — output you can read and edit before any code is generated. Plans land in a specs/ directory (e.g. basic-operations.md).

Generator (the writer). The generator "transforms the Markdown plan into the Playwright Test files," verifying selectors and assertions live as it runs each scenario rather than guessing at locators statically. Generated tests land in a tests/ directory aligned with the specs. Because it validates against the running app, the tests it emits are grounded in the real DOM, not invented.

Healer (the repairer). The healer "executes the test suite and automatically repairs failing tests." When a test breaks, it replays the failing steps, inspects the current UI for equivalent elements, and suggests patches — updated locators, adjusted waits, data fixes — then re-runs until the test passes or a guardrail stops it. The documented outcome is "a passing test, or a skipped test if the healer believes that functionality is broken." That last clause matters: the healer does not paper over a genuinely broken feature by forcing a green check; it skips and flags it.

How to set them up

You initialize the agents for your AI loop with one command. Per the docs:

npx playwright init-agents --loop=vscode
npx playwright init-agents --loop=claude
npx playwright init-agents --loop=codex
npx playwright init-agents --loop=opencode

This generates agent definitions — described as "collections of instructions and MCP tools" — under .github/. The docs add an operational note: "These definitions should be regenerated whenever Playwright is updated to pick up new tools and instructions," so re-run init-agents after a Playwright upgrade.

The other piece you provide is seed.spec.ts, a bootstrap test that supplies context and environment setup. The planner "will run this test to execute all the initialization necessary for your test" — login, base URL, fixtures — so the agents start from a logged-in, ready state instead of the front page.

The workflow end to end

1. Write seed.spec.ts so the agents start authenticated and configured.
2. Run the planner; review and edit the Markdown plan in specs/ — this is your chance to steer coverage cheaply, before code exists.
3. Run the generator to turn the approved plan into real Playwright tests, validated against the live app.
4. Run the healer when tests fail after a UI change; review its patches, and treat any test it skips as a signal to check whether the feature actually broke.

The human stays in the loop at two points that matter: approving the plan (what gets tested) and reviewing heals (whether a failure is a flaky locator or a real regression).

Why the planner/generator/healer split works

The split maps to the three different skills E2E testing actually requires. Deciding what to test is a judgment task best reviewed as plain Markdown. Writing correct tests is a mechanical task that benefits from live selector verification. Maintenance — the part that usually kills test suites — is pattern-matching against a changed UI, which is where the healer earns its keep by re-deriving locators instead of you doing it by hand every time the markup shifts.

This is the same principle behind treating tests as the specification you give an agent: a passing, real-DOM test is an objective signal the agent's code does what you asked, far stronger than "it looks done."

Read: Tests Are the New Prompt

FAQ

What are the three Playwright Test Agents?

The planner (explores the app and writes a Markdown test plan), the generator (turns the plan into Playwright test files, verifying selectors live), and the healer (runs the suite and repairs failing tests, or skips them if functionality looks genuinely broken).

Which AI tools do Test Agents work with?

You initialize them with npx playwright init-agents --loop= and a target: vscode, claude, codex or opencode. The command writes agent definitions under .github/.

What is seed.spec.ts for?

It is a bootstrap test that handles setup like login and base URL. The planner runs it first so the agents work from an initialized, authenticated state.

Does the healer just force tests to pass?

No. It replays failing steps, finds equivalent UI elements and patches locators/waits, but if it believes the functionality is actually broken it skips the test rather than faking a green result.

Do I need to regenerate the agents after upgrading Playwright?

Yes. The docs say definitions "should be regenerated whenever Playwright is updated to pick up new tools and instructions" — re-run init-agents.

Bottom line

Playwright Test Agents turn E2E testing into a three-stage pipeline: a planner decides what to test (as reviewable Markdown), a generator writes real-DOM-validated tests, and a healer keeps them green as the UI changes — or honestly skips a test when the feature is broken. Set them up with init-agents, seed them with a login bootstrap, and keep a human on the plan-approval and heal-review steps. It is the most concrete version yet of "let the AI maintain the test suite."

Sources and further reading