How Playwright Agents Are Changing the Way We Write and Maintain Tests

Adapted from the original post on the GeekyAnts blog.

Ask any automation engineer what their week looks like and you'll hear some version of the same story: read the requirements, write the test cases, script the automation, watch a locator break, chase down why, fix it, run it again. That loop hasn't really gone anywhere — it just moved frameworks, from Selenium to Cypress to Playwright.

So here's a question worth sitting with: what if the framework didn't just run your tests, but actually helped plan them, write them, and repair them when they broke? That's the pitch behind Playwright's Test Agents.

Shipped in Playwright 1.56, these agents bring AI into three specific stages of the testing lifecycle — planning, writing, and healing — by looping against your actual running application rather than guessing from a prompt alone.

This piece walks through what the agents do, how a project gets wired up to use them, what a seed test is for, what comes out the other end, and where this genuinely differs from just asking ChatGPT or Cursor to write you a test script.

Why Playwright Alone Wasn't Enough

Playwright earned its popularity by killing off a lot of the pain that made older frameworks miserable — flaky waits, brittle timing, locators that broke for no obvious reason. Auto-waiting, role-based selectors, and built-in tracing meant engineers spent less time fighting the tool and more time actually testing.

But none of that touched the manual work upstream and downstream of running the tests: translating a requirement doc into concrete scenarios, turning those scenarios into actual code, rewriting tests every time the UI shifts, and chasing broken selectors after every release. Agents are Playwright's attempt to close that gap.

What the Three Agents Actually Do

Playwright Test Agents are AI workflows that live inside a project and split the job into three roles.

The Planner takes a plain-language description of what needs testing, then uses a "seed test" as its entry point into the app to explore flows and edge cases. It comes back with a structured written test plan — not code, but the kind of scenario breakdown a QA engineer would write by hand.

The Generator takes that plan and turns it into runnable Playwright code. Crucially, it does this while poking at the live app — checking that selectors actually resolve, that assertions match real UI state — rather than hallucinating locators from memory. Told to, it'll follow a Page Object Model layout too.

The Healer steps in when a test fails. It re-runs the failing scenario, looks at the current DOM, works out what changed, and tries to patch the selector, wait, or interaction logic itself, instead of leaving that job to whoever's on call.

Chain the three together and the loop becomes Planner, then Generator, then Healer — turning a sentence of intent into a working, self-repairing test suite.

Setting Up a Project

Getting started involves scaffolding a standard Node and Playwright project first, exactly as any engineer already familiar with Playwright would expect. From there, Playwright's own agent tooling can be initialized, which adds a new folder of agent definitions into the project alongside the usual test folders.

That new folder holds three files, one for each agent: the planner, the generator, and the healer, each written as a Markdown definition. Whatever AI assistant is driving the workflow, whether that's Claude Code, VS Code's Copilot, or another agentic coding tool, reads these definitions to understand how to behave in each role.

Alongside the agent definitions, a typical project ends up with a folder for the Markdown plans the Planner produces, a folder for the actual generated Playwright test files, and a single seed test that acts as the Planner's starting point into the application. This layout is the convention Playwright's own tooling expects, so sticking to it keeps things predictable.

The seed test matters more than it sounds like it should. It's the Planner's foothold: where to navigate first, what login step to run, what "home base" looks like for the application before any exploration begins. Alongside it, a small file of sample data (a couple of test user credentials, say — one valid, one intentionally invalid) gives the Planner enough grounding to write scenarios that are actually relevant to the app rather than generic boilerplate.

The Planner Agent in Practice

Think of the Planner less like a code generator and more like a QA analyst that happens to run on AI. Instead of jumping straight to code, it produces a Markdown test plan: scenarios, steps, expected outcomes, and the data each one needs.

A prompt as simple as asking for a test plan covering login with both valid and invalid credentials, using the seed test as context, is enough to get it moving. The Planner explores the app through that seed test and writes out a plan as a readable document, not a script, meant to be read and approved before any code gets written. This is the step where a bad assumption gets caught early, before it turns into a bad test.

The Generator Agent: Plan to Code

Once a plan looks right, the same assistant can be switched into Generator mode and asked to turn that Markdown plan into actual TypeScript tests, following a Page Object Model structure if that's the preference.

The Generator reads the plan, checks selectors and assertions against the live app as it writes, and produces test files — typically one for a straightforward happy path, one covering an edge case, and others built around shared helper functions. Each generated file maps back to a scenario from the plan. Because it's validating against the running app rather than guessing, the output tends to be noticeably more stable than what comes out of a plain prompt-to-code tool with no live context.

The Healer Agent: Fixing What Breaks

Tests fail. A button gets relabeled, a locator moves, and something that passed yesterday doesn't today. Normally that means opening the inspector, finding the new selector, and patching it by hand.

The Healer automates that chase. Pointed at a specific failing test, it re-runs it in debug mode, inspects the current DOM for an equivalent element or flow, proposes a fix such as a new selector or an adjusted wait, and re-runs until it either passes or the agent concludes the failure actually reflects a real product change rather than a stale test. That second outcome matters: the goal isn't to force a green checkmark at any cost, it's to cut down the routine busywork of chasing UI churn.

Under the Hood: What's Actually Happening

From the outside, all of this looks deceptively simple: type a sentence, get back a test plan or a fix. Underneath, the agents run a loop that reads project files, executes real test runs, drives the browser, and inspects the live DOM at every stage. The Planner explores through the seed test, the Generator checks selectors as it writes, the Healer replays failures to diagnose them. That complexity stays hidden — a prompt goes in, a plan, script, or fix comes out, and the orchestration in between isn't something anyone has to manage by hand.

Keeping the Output Organized with Page Object Model

If the generated code needs to stay maintainable long-term, and it should, it's worth being explicit about that in the prompt: asking for a Page Object Model structure with locators kept in separate page files. That nudges the Generator toward splitting locator definitions and reusable actions into their own files, separate from the test logic itself, which saves a lot of refactoring down the line.

The Full Loop, End to End

Run all three agents together and the shape of the workflow is: a seed test plus a prompt goes to the Planner, which writes a Markdown plan; that plan goes to the Generator, which writes the tests; those tests run, and any failures go to the Healer, which fixes what it can. What comes out the other side is a test suite that largely maintains itself. It's the same lifecycle a human QA team already runs, just with AI doing the first draft at every stage.

Where This Differs From Generic AI Coding Tools

It's tempting to lump this in with Cursor, ChatGPT, or any other "AI writes my code" tool, but the comparison doesn't hold up well. Generic AI code generation can write code from a prompt, but it doesn't run the tests it writes, doesn't fix failures on its own, and doesn't check the live DOM while generating. Playwright Agents do all three, and they do it wired directly into Playwright's own tooling through MCP (Model Context Protocol), staying in the loop with the running application throughout rather than generating code from a prompt in isolation.

A Few Things That Make This Work Better

Giving the agents real context matters more than clever prompting — a well-built seed test and structured seed data make a bigger difference than a cleverly worded instruction. Prompts should be specific about architecture preferences, data sources, and expected outputs rather than left open-ended. Generated tests are still worth a human read-through; good scaffolding isn't the same as a finished, reviewed test. And in CI, healed or freshly generated tests are best treated as drafts until someone's actually looked at them.

Wrapping Up

Between the Planner, Generator, and Healer, Playwright's agents take a real bite out of the manual overhead in test automation, turning a plain-language description into scenarios, code, and self-repair without cutting humans out of the review loop.

Anyone with basic Playwright experience already has most of what they need to try this. It's the same lifecycle, with AI doing more of the first draft. Worth trying on a small project first: set up the agents, write a decent seed test, and see how far a simple prompt actually gets.

---

Adapted from the original article on the GeekyAnts blog.