Playwright Agents: Planner, Generator and Healer, Hands-On

What Are Playwright Agents

Playwright Agents are three AI modules built into Playwright v1.56, the Planner, Generator, and Healer, that automate test planning, spec-file generation, and locator repair from inside VS Code.

Later releases keep adding agent-facing APIs: Playwright 1.64 adds page.getByRef(), which turns a ref from an aria snapshot back into a locator, and WebMCP testing for the tools a page exposes to agents. The Playwright 1.64 release guide covers both.

They run inside VS Code through Playwright's MCP and AI agents integration. Each agent reads its own definition file and uses the configured LLM to act on your prompt. Here is what each one does:

Teams that want to build their own agent instead of the built-in modules can follow this guide to Playwright LangChain.

It covers wrapping Playwright actions as LangChain tools, running a ReAct loop for failure triage and test generation, and the security patterns a production agent browser needs.

For a deeper look at how these agents communicate with the underlying MCP server, see this guide to AI and Playwright MCP, which covers MCP setup and an end-to-end Jira-ticket-to-tests workflow.

Planner, Generator and Healer Agents in Playwright

Each agent covers one phase of the test lifecycle. The details here come from the Playwright Test Agents docs and from the definition files and MCP tools that Playwright 1.64.0 ships.

How Do Playwright Test Agents Work?

Playwright Test Agents are built on the Model Context Protocol (MCP). The init-agents command writes the agent definitions and registers Playwright's test MCP server, which starts with npx playwright run-test-mcp-server.

On 1.64.0 that server identifies itself as Playwright Test Runner and exposes 92 tools. Most are browser actions such as browser_click and browser_snapshot. A handful belong to the agents, among them planner_save_plan, generator_read_log, generator_write_test, test_run and test_debug.

When you call an agent, your coding agent loads its definition, and the model picks the next tool call. Browser actions go through the MCP server, so the planner and generator work against the real page.

The agents hand work to each other in this order:

• Planner receives a request and a seed test, explores the app in a browser, and saves a Markdown plan with scenarios, steps and expected results.
• Generator reads the plan, performs the steps in a browser, and writes a Playwright test file with locators and assertions.
• Playwright runs the generated tests. The test runner executes each spec file and outputs pass or fail results with full error logs.
• Healer runs the failing tests in debug mode, patches the code, and re-runs to verify.

The --loop flag only chooses which coding agent the definitions are written for. It does not run or chain anything.

Chaining is up to you. Ask for all three agents in one prompt, or call one at a time, such as only the healer when a locator breaks or only the generator for new scenarios.

How to Set Up Playwright Agents

Run npx playwright init-agents with the --loop flag for your coding agent. The command writes the three agent definitions into your project, and you then call the agents from that coding agent's chat.

Prerequisite: a Coding Agent

Playwright Agents extend an existing Playwright project and run inside a coding agent. The docs list four.

• VS Code - Version 1.105 or later, which the docs require for the agent experience. The vscode loop writes GitHub Copilot agent files.
• Claude Code, Codex or OpenCode - Each has its own loop value and its own folder for the definitions.
• Model - The agents use the model your coding agent runs. The definitions name a default, which on 1.64.0 is Claude Sonnet 4.6 in the VS Code files and sonnet in the Claude Code files, and you can edit it.
• TypeScript and JavaScript output - The agents write Playwright Test spec files. As of October 2026 the Test Agents page exists only in the Node.js docs, with no Python, Java or .NET equivalent.

npm init playwright@latest               # new project
npm install -D @playwright/test@latest   # existing project
npx playwright install                   # browsers for the installed version

$ npx playwright init-agents --loop=claude
 🎭 Using project "" as a primary project
 📝 specs/README.md - directory for test plans
 🌱 tests/seed.spec.ts - default environment seed file
 🤖 .claude/agents/playwright-test-generator.md - agent definition
 🤖 .claude/agents/playwright-test-healer.md - agent definition
 🤖 .claude/agents/playwright-test-planner.md - agent definition
 🔧 .mcp.json - mcp configuration
 ✅ Done.

repo/
  .claude/agents/          # agent definitions (folder depends on --loop)
  .mcp.json                # MCP server config
  specs/                   # Markdown test plans from the planner
  tests/
    seed.spec.ts           # seed test
  playwright.config.ts

import { test, expect } from '@playwright/test';

test.describe('Test group', () => {
  test('seed', async ({ page }) => {
    // generate code here.
  });
});

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

test('seed', async ({ page }) => {
  await page.goto('https://ecommerce-playground.lambdatest.io/');
});

Step 4: Call the Agents From Your Coding Agent

In VS Code, the three agents appear by name in the chat's agent picker. In Claude Code, ask for an agent by name, for example "Use the planner agent with tests/seed.spec.ts".

Start your web application before running any agent. The planner and generator open a real browser and interact with the running app, so unstable state or slow rendering shows up as gaps in the plan and in the generated code.

How to Use Playwright Test Agents (Step-by-Step Example)

Run the Planner to map your app's flows, pass the plan to the Generator to create a spec file, then use the Healer on whatever fails.

The screenshots in this section come from one run in VS Code, set up with --loop=vscode and using Claude Sonnet 4 as the model. The app is a demo store, and the test covers its login.

Each step gives a prompt you can adapt, what the agent produced in that run, and what to check before you move on.

1. Create a Test Plan (Planner Agent)

The Planner opens your app in a browser, explores the flows you name, and saves a Markdown test plan. Add the seed test to the context or name it in the prompt.

Prompt

Use the Playwright test planner with tests/seed.spec.ts. Create a test plan for login and checkout, and save it as test-plan.md.

The prompt names a file, so the Planner saved test-plan.md in the project root. Without a name, the convention is a file under specs/, the folder init-agents creates for plans.

In the saved plan, each scenario names the spec file it should become and lists numbered steps. The login scenario from this run points at tests/authentication/login-valid.spec.ts:

Edit the plan before passing it to the Generator. Remove out-of-scope flows and add edge cases the Planner missed. The plan is plain Markdown, so the edit can go through a pull request.

Use fixed test data and a stable app state before running the Planner. Inconsistent state between runs produces gaps in the plan.

2. Generate the Test Script (Generator Agent)

The Generator reads the plan and turns one scenario into an executable Playwright spec file. Reference the scenario by number or by name so it picks the right one.

Prompt

Use the Playwright test generator to create the test for the login scenario in test-plan.md.

The Generator opens a browser, performs each step of the scenario, and writes the spec to the path the plan gave it. In this run that was tests/authentication/login-valid.spec.ts, with a describe block named Authentication and a test named Successful Login with Valid Credentials.

Comments in the file mirror the plan's steps, which makes the code easy to review against the plan. See Playwright assertions for the expect() checks it writes. This excerpt is from the generated file:

// Verify demo credentials are visible on the page
await expect(page.getByText('demo@demo.com')).toBeVisible();
await expect(page.getByText('demo')).toBeVisible();

// 2. Fill email field
await page.getByRole('textbox', { name: 'Email' }).fill('demo@demo.com');

Run the generated spec before you treat it as finished. Check that every assertion reflects a business requirement and does more than confirm the page loaded.

3. Execute the Test

Run the generated spec with the command below. For more Playwright run tests options, including filters and reporters, see the linked guide.

npx playwright test tests/authentication/login-valid.spec.ts

If you would rather not install browsers locally, the Playwright testing tool runs the same spec online on the TestMu AI cloud.

The project runs each test in Chromium, Firefox and WebKit, and the first run failed. This is the WebKit failure, the third in the report:

Error: expect(locator).toBeVisible() failed

Locator: getByText('demo')
Expected: visible
Error: strict mode violation: getByText('demo') resolved to 2 elements:
    1) <p class="help-block">…</p> aka getByText('Email: demo@demo.com')
    2) <p class="help-block">…</p> aka getByText('Password: demo')

Playwright's strict mode requires a locator to match exactly one element. getByText('demo') matches by substring, so it resolved to both help texts on the login page, the one with the demo email and the one with the demo password. The error lists each match with a locator that would single it out.

Do not fix this by hand yet. Pass it to the Healer.

4. Fix Failures (Healer Agent)

The Healer runs the failing test in debug mode, reads the page where it stopped, and rewrites the affected lines. Point it at the failing file.

Prompt

Use the Playwright test healer to find why tests/authentication/login-valid.spec.ts fails and fix it.

In this run the Healer went past the reported failure. Its summary lists three more locators it tightened before the test passed:

• Category heading ambiguity - It added { exact: true } to getByText('Men Fashion').
• Electronics selector conflict - It switched to getByRole('heading', { name: 'Electronics', exact: true }) so the locator targets only the heading.
• Cart count check - getByText('0') matched several elements, including discounts and the copyright year, so it used page.locator('#cartCount').

Each fix follows the same principle as auto-heal in Playwright, which is to narrow the selector to exactly one element.

Read the diff before you commit it. The third fix trades a text locator for an element id. It works, but Playwright's best practices prefer user-facing attributes to CSS selectors, so it is a change to question in review.

A heal can also change what the test verifies. The Healer's definition lists fixing assertions and expected values among its remedies, and tells it to do the most reasonable thing possible to pass the test.

The Healer does not repair a test that fails because of an application bug. If it is confident the test is right, it marks the test test.fixme() and comments on what the app did instead, so investigate every skip.

5. Re-run and Confirm

After the Healer applies its fixes, re-run the spec to confirm the repair holds.

npx playwright test tests/authentication/login-valid.spec.ts

The run reported the test passing in each of the three browsers:

Running 3 tests using 1 worker
  3 passed (16.9s)

From here the spec is ordinary Playwright code, and it runs in CI with the same command.

Running the Full Playwright Agents Loop

Chained together, the agents take a feature description to a reviewed, passing test suite in five steps, with a human checkpoint after the plan and another after the code.

• Seed - Write or update tests/seed.spec.ts so it reaches the feature, logged in and with the right data.
• Plan - Ask the planner for the feature, optionally attaching the PRD or ticket. Review the Markdown plan and edit it.
• Generate - Ask the generator to build tests from that plan.
• Run - Run npx playwright test on the new folder. Expect some failures on the first run.
• Heal - Send the failures to the healer. Review the diffs and investigate any test it skipped.

After that, the suite runs in CI with npx playwright test. When the UI changes later, you send the new failures to the healer again.

In Claude Code, one prompt can cover the whole loop and still stop for review:

Use the planner to plan checkout from tests/seed.spec.ts, then the generator to write the tests, then run them and use the healer on any failures. Stop and show me the plan before generating.

What Don't Playwright Agents Do?

Playwright Agents speed up writing and repairing Playwright code, but you still own that code, its coverage and its infrastructure.

The agents are built for teams that want to own Playwright code. Decide first whether yours does.

Playwright Agents vs Kane CLI vs KaneAI

Choose Playwright Agents if your team wants AI help writing Playwright code it will own. Choose Kane CLI if developers or coding agents want a verified pass or fail on a flow without maintaining scripts. Choose KaneAI if manual testers and PMs need to author and manage tests in natural language as a team.

Kane CLI and KaneAI are both from TestMu AI and share one automation engine. The Kane CLI and KaneAI columns are taken from their product pages.

Teams That Can Stop at Playwright Agents

• Your team already writes Playwright and reviews test code in pull requests.
• You test a web app only, with no native mobile.
• Writing new tests is your bottleneck, and suite maintenance is under control.
• Nobody asks you for requirement-level coverage reports.

Reasons to Add Kane CLI or KaneAI

• Coding agents ship features faster than your team can write tests for them. Kane CLI checks the flow an agent touched and returns a verdict the agent can act on, which is the case covered in testing apps built with Claude Code.
• Test maintenance, more than test creation, is eating your sprint.
• You need proof per acceptance criterion for audits or release sign-off.
• Manual testers and PMs need to own tests without learning TypeScript.
• You test native mobile apps alongside web. AI app testing with KaneAI by TestMu AI runs on 3,000+ browser and OS combinations and 10,000+ real devices.

The two approaches can run side by side: Playwright Agents for the regression suite engineers own, and Kane CLI for fast-changing flows and code written by coding agents.

With Kane CLI you hand over one objective instead of a plan and a spec. This command ran against the TestMu AI eCommerce Playground on October 11, 2026, with Kane CLI 0.8.17:

npm install -g @testmuai/kane-cli
kane-cli run --url https://ecommerce-playground.lambdatest.io/ \
  "search for a laptop, add the first result to the cart and verify the cart shows one item" \
  --agent --headless

The run reported a duration of 111.8 seconds and exited with code 0. This is its closing event, trimmed to the fields that carry the verdict:

{"type":"run_end","status":"passed","one_liner":"added the first laptop search result to the cart on ecommerce-playground.lambdatest.io","final_state":{"cart_item_count":"1"},"reason":"Objective completed","duration":111.8}

The pass came from a check on the page. Kane CLI read the quantity cell in the cart, extracted 1 from "x1", and compared it with the expected value.

Get Kane CLI to try it. The product page lists 10,000 Kane CLI credits, free for a month. For the web app, start with the KaneAI getting started guide.

Running Agent-Generated Playwright Tests at Scale

Tests from the generator are standard Playwright Test files, so they run anywhere Playwright runs: locally, in CI, or on a cloud across many browsers in parallel.

Agents make a suite grow faster, and a larger suite is where one machine or one CI runner starts to slow down.

• Cross-browser - Point playwright.config.ts at the TestMu AI cloud with the wsEndpoint connection option and your LT_USERNAME and LT_ACCESS_KEY. The same generated tests then run on Chrome, Chromium, Firefox, WebKit and Edge across Windows, macOS and Linux, which the product page counts as 3,000+ browser and OS combinations. See Playwright testing on TestMu AI.
• Speed - HyperExecute splits a large Playwright suite into parallel tasks, retries real failures, and collects logs, screenshots and video per test.
• Visual checks - Generated tests assert behavior, and the healer never looks at layout. SmartUI visual testing compares screenshots across browsers to catch layout shifts.
• Triage - When a healed test keeps failing on one browser, the cloud session's video and network logs show whether the test or the app is at fault.

Troubleshooting Playwright Agent Issues

The first three failures below were reproduced on Playwright 1.64.0. All of them come from the project around the agents.

Seed Test in the Wrong Folder

Run from a folder with no Playwright config, init-agents reports an empty project name and writes the seed test to the project root:

 🎭 Using project "" as a primary project
 🌱 seed.spec.ts - default environment seed file

With a config whose testDir is ./tests, the same command writes tests/seed.spec.ts. Run init-agents from the folder that holds playwright.config.ts, or pass the config path with -c.

No Tests Found

Playwright prints this when it finds no spec files in testDir. Check that the path the plan gave each test sits inside the directory your config names.

Error: No tests found

Browser Executable Missing

A fresh install or an upgrade leaves Playwright without browsers for that version, and the first test run fails like this:

Error: browserType.launch: Executable doesn't exist at ~/Library/Caches/ms-playwright/chromium_headless_shell-1248/chrome-headless-shell-mac-arm64/chrome-headless-shell
╔════════════════════════════════════════════════════════════╗
║ Looks like Playwright was just installed or updated.       ║
║ Please run the following command to download new browsers: ║
║                                                            ║
║     npx playwright install                                 ║
║                                                            ║
║ <3 Playwright Team                                         ║
╚════════════════════════════════════════════════════════════╝

Run npx playwright install, and keep the Node.js and Playwright versions the same across local, staging and CI.

Stale Agent Definitions

The definitions belong to the Playwright version that generated them. After an upgrade, re-run init-agents so they pick up new tools and instructions, as the docs advise. In VS Code, also confirm the editor is on 1.105 or later.

Permissions and File Access

In Playwright Docker images and CI runners, check that the agent can read the config and write to tests/, specs/ and the folder that holds the definitions. Confirm that .dockerignore and .gitignore do not exclude the spec files.

Best Practices for Playwright Agents

Playwright Agents produce better output when the inputs are unambiguous and the environment is stable.

• Choose a capable model. Run two models on the same plan and keep the one that follows your locator instructions and writes real assertions.
• Write specific prompts. Give the target URL, each step, test data and expected outcome, so the planner has less to guess.
• State your locator strategy. Request getByRole(), getByLabel(), and getByTestId() explicitly, and pair with the Playwright Skill to enforce it.
• Review every generated spec before merging. Agents cannot verify that assertions match business logic, so a passing test can still be wrong.
• Run agents against a stable environment. Slow rendering and flaky APIs make agents miss flows, so use fixed test data.
• Run the Planner after major releases. Point it at the new UI, and treat plan scenarios with no spec file as coverage gaps.
• Version-control the generated files. Commit the definitions and the MCP config so the whole team shares one setup, and review the diff each time init-agents regenerates them.

In the TestMu Conference 2026 workshop Advanced Web Testing with Playwright and AI, Andrew Knight covers keeping a suite of hundreds of Playwright tests fast and maintainable.

Getting Started With One Flow

Start with one flow. Run npx playwright init-agents with the loop for your coding agent, write a seed test that reaches your most-tested path, and prompt the Planner on it.

Trim the plan to the scenarios you need, pass it to the Generator, and review every assertion before merging. Coverage and business-logic checks still belong to the engineer.

Once generated, the tests are ordinary spec files, so each CI run executes the same code. For a hosted, CLI-driven agent, compare a Playwright CLI alternative.

Citations

• Playwright Test Agents - https://playwright.dev/docs/test-agents
• Playwright MCP - https://github.com/microsoft/playwright-mcp
• Playwright v1.56 Release Notes - https://playwright.dev/docs/release-notes
• Playwright Best Practices - https://playwright.dev/docs/best-practices