Playwright Test Agents: Planner, Generator, Healer

Updated Jul 2026

What Shipped

With v1.56 (and maturing through 1.61, current as of July 2026), Playwright gained three first-party test agents — not a bolted-on AI product, but agent definitions that plug into whatever coding agent you already run:

Agent	Input	Output	Job
🎭 Planner	A seed test, optional PRD, your request	`specs/*.md` — human-readable Markdown test plans	Explores the app, decides what to test
🎭 Generator	A Markdown plan	`tests/*/.spec.ts` — executable Playwright tests	Converts scenarios to code, verifying selectors and assertions live against the running app
🎭 Healer	A failing test	A patched test (or a verdict that the app itself is broken)	Replays the failure, inspects the UI, updates locators/waits/data, reruns until green

Scaffolding is one command, rerun whenever Playwright updates:

npx playwright init-agents --loop=claude    # Claude Code
npx playwright init-agents --loop=vscode    # VS Code (v1.105+, Oct 2025 or later)
npx playwright init-agents --loop=codex     # Codex CLI
npx playwright init-agents --loop=opencode  # opencode

Note the --loop flag: the agent definitions are portable across agent runtimes. This is the skills thesis from Foundations applied by the biggest player in the ecosystem — write instructions once, run them under any capable coding agent.

The Artifact Layout

repo/
  .github/              # agent definitions (regenerated by init-agents — don't hand-edit)
  specs/                # human-readable Markdown plans
    basic-operations.md
  tests/
    seed.spec.ts        # environment bootstrap: auth, base state, fixtures
    create/
      add-valid-todo.spec.ts
  playwright.config.ts

Three conventions matter:

The seed test is the contract. seed.spec.ts gives every agent a pre-configured page context (logged in, correct tenant, test data). Agents don't reinvent your auth flow; they inherit it.
Specs are the source of truth. Plans live in specs/ as Markdown a product owner can read and correct. Generated tests map one-to-one to spec scenarios.
Generated tests are drafts. The generator verifies selectors live, but its output may still contain errors — that's explicitly what the healer (and your code review) are for.

Why This Workflow Is the Right Division of Labor

The plan → generate → heal split mirrors how a senior QA engineer actually works, and it puts the human review where it's cheapest and highest-leverage — at the plan stage, in Markdown, before any code exists:

PRD ──► Planner ──► specs/*.md ──► HUMAN REVIEW ──► Generator ──► tests/*.spec.ts
                                                                      │
                                              CI failure ──► Healer ──┘

Reviewing a ten-line scenario description takes a minute. Reviewing 300 lines of generated test code takes an hour. Push your judgment upstream.

The Healer Is Self-Healing Done Honestly

The healer's loop: run the failing test → replay the failing step → inspect the live UI → propose a patch (new locator, adjusted wait, fixed data) → rerun → repeat until passing or conclude the functionality itself is broken.

That last clause is the difference between self-healing and self-deception. A healer that always makes the test pass is a bug-hiding machine. Playwright's framing — "determines functionality is broken" is a valid terminal state — is the correct architecture, and it's the standard you should hold any vendor's "self-healing AI" to in an evaluation. (More on this in the Self-Healing Strategies chapter.)

Limits an Architect Should Name

Non-determinism. Two planner runs produce different plans. Treat agent output like human output: reviewed, versioned, owned.
Generated tests inherit generated blind spots. The planner tests what it can see. Business rules that live outside the UI (pricing math, permissions matrices) still need designed tests — see the AI-Augmented Test Design topic.
Token cost lives somewhere. Agents explore the app through browser tooling; long exploration sessions are not free. The CLI's disk-first snapshots (previous chapter) are what make this affordable.
Regenerate on upgrade. Agent definitions are Playwright-version-coupled; stale definitions are a real failure mode. Rerun init-agents as part of your Playwright upgrade checklist.

Interview Talking Point

"We use Playwright's first-party test agents. The planner explores the app and writes Markdown plans into specs/; humans review the plans — that's where review is cheap. The generator turns approved specs into Playwright tests, verifying locators against the live app. The healer handles CI failures by replaying, inspecting the UI, and patching locators or waits — and critically, it's allowed to conclude the app is actually broken instead of forcing the test green. Everything is scaffolded with init-agents and works under Claude Code, VS Code, or Codex, so we're not locked to one agent runtime."