Playwright Test Agents: Planner, Generator and Healer Explained

Playwright now ships with AI agents that plan, generate and heal tests. In this lesson you will set them up, write a seed test, turn a Markdown test plan into Playwright tests, and use the healer safely when the UI changes.

---

🤝 What Are Playwright Test Agents?

Playwright Test Agents are three ready-made AI agents, shipped with Playwright, that help you plan, write and maintain end-to-end tests:

Agent	Input	Output
🎭 Planner	Your app (plus a seed test and optional requirements)	A Markdown test plan in specs/
🎭 Generator	The Markdown plan	Playwright Test files in tests/, with locators and assertions verified live in the browser
🎭 Healer	A failing test	A fixed test (locators, waits, data), or a skipped test if it believes the feature is really broken

They run inside AI coding tools (VS Code with Copilot, Claude Code, Codex, OpenCode) and use Playwright’s browser tools behind the scenes, similar to Playwright MCP. You can use them one at a time, in sequence, or as a loop.

---

⚙️ Set Up the Agents

Start from a working Playwright TypeScript project (installation) on a recent Playwright version, then generate the agent definitions for your AI tool:

npx playwright init-agents --loop=vscode     # VS Code (GitHub Copilot agent mode)
npx playwright init-agents --loop=claude     # Claude Code
npx playwright init-agents --loop=codex      # Codex
npx playwright init-agents --loop=opencode   # OpenCode

After initialization your project looks like this:

.github/                     # agent definitions (location depends on the AI tool)
specs/                       # human-readable Markdown test plans
tests/
  └── seed.spec.ts           # seed test: sets up the environment for the agents
playwright.config.ts

---

🌱 The Seed Test

The seed test prepares everything the agents need to start: navigation to the app, login, fixtures and global setup. The planner runs it first, and generated tests copy its setup. Keep it small:

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

test('seed', async ({ page }) => {
  await page.goto('https://www.saucedemo.com/');
  await page.getByPlaceholder('Username').fill('standard_user');
  await page.getByPlaceholder('Password').fill('secret_sauce');
  await page.getByRole('button', { name: 'Login' }).click();
  await expect(page.locator('.title')).toHaveText('Products');
});

If your project uses custom fixtures or a logged-in storage state, use them in the seed test so generated tests follow the same pattern.

---

🗺️ Step 1: The Planner Writes a Test Plan

Open your AI tool’s chat, choose the planner agent and describe what to cover:

💬 “Using the seed test, create a test plan for the cart and checkout flows of Sauce Demo: adding and removing items, cart badge, checkout information validation and order completion.”

The planner explores the app in a real browser and saves a plan such as specs/cart-and-checkout.md:

# Cart and Checkout Test Plan

## Application Overview
Sauce Demo lets a logged-in user add products to a cart, review the cart,
enter checkout information and complete an order.

## Test Scenarios

### 1. Cart
**Seed:** tests/seed.spec.ts

#### 1.1 Add a single product
**Steps:**
1. Click "Add to cart" for Sauce Labs Backpack
**Expected Results:**
- The cart badge shows 1
- The button changes to "Remove"

#### 1.2 Remove a product from the cart page
...

### 2. Checkout
#### 2.1 Postal code is required
...

---

🛠️ Step 2: The Generator Writes the Tests

Choose the generator agent and point it at the plan:

💬 “Generate tests for section 1 of specs/cart-and-checkout.md.”

The generator walks through each scenario in the browser, checks that locators and assertions really work, and writes files into tests/, for example:

// tests/cart/add-single-product.spec.ts
// spec: specs/cart-and-checkout.md
// seed: tests/seed.spec.ts
import { test, expect } from '@playwright/test';

test.describe('Cart', () => {
  test('Add a single product', async ({ page }) => {
    await page.goto('https://www.saucedemo.com/');
    await page.getByPlaceholder('Username').fill('standard_user');
    await page.getByPlaceholder('Password').fill('secret_sauce');
    await page.getByRole('button', { name: 'Login' }).click();

    await page.locator('[data-test="add-to-cart-sauce-labs-backpack"]').click();
    await expect(page.locator('.shopping_cart_badge')).toHaveText('1');
    await expect(page.locator('[data-test="remove-sauce-labs-backpack"]')).toBeVisible();
  });
});

Generated code differs between runs and versions; always read it, run it, and refactor it into your framework structure (page objects, fixtures, data files).

---

🩹 Step 3: The Healer Fixes Failing Tests

When the UI changes and tests fail, choose the healer agent:

💬 “Run the cart tests and fix any failures.”

The healer:

1. Runs the failing test.
2. Inspects the current UI to find equivalent elements or flows.
3. Patches the test: an updated locator, a missing wait condition, adjusted test data.
4. Re-runs it until it passes, or marks the test as skipped if it concludes that the application itself is broken.

---

🔁 Putting It Together

Step	Agent	Your role
1. Plan	Planner	Provide seed test and requirements, review the plan
2. Generate	Generator	Review code, refactor into page objects, add to CI
3. Maintain	Healer	Review healed changes; investigate skipped tests as possible bugs

Run the resulting tests like any other suite: locally, in GitHub Actions or Jenkins. The agents speed up writing and maintenance; the suite itself stays plain, deterministic Playwright code.

---

✅ Best Practices

• Start small: one feature, one plan, a handful of tests.
• Keep the seed test fast and reliable; every generated test depends on it.
• Use test environments and test accounts only.
• Store plans (specs/) in Git next to the tests; they document coverage for the team.
• Require code review for generated and healed tests.
• Combine with tags so agent-generated tests are easy to find and run.

---

📝 Assignment

1. In your Sauce Demo project, run npx playwright init-agents for the AI tool you use.
2. Write a seed test that logs in and asserts the products page.
3. Ask the planner for a test plan covering sorting and the cart. Review it and add two negative scenarios yourself.
4. Ask the generator to create tests for the sorting section. Run them and fix anything that fails.
5. Change one locator in a generated test to something wrong, then ask the healer to fix it. Review its diff.
6. Bonus: refactor the generated tests to use your page objects and fixtures from Project 2.

---

❓ FAQ

🤔 What are Playwright Test Agents?

Three AI agents included with Playwright: a planner that writes Markdown test plans, a generator that turns plans into Playwright tests, and a healer that repairs failing tests.

🤔 How do I set up Playwright Test Agents?

Run npx playwright init-agents --loop=vscode (or claude, codex, opencode) in your Playwright project, add a seed test, then use the agents from your AI tool’s chat.

🤔 What is the seed test in Playwright agents?

A test that sets up the environment (navigation, login, fixtures). The planner runs it first and generated tests reuse its setup.

🤔 Can the healer agent hide real bugs?

It can if you accept changes blindly. The healer skips tests it believes reflect broken functionality, but you should review every healed change.

🤔 What is the difference between Playwright Test Agents and Playwright MCP?

Playwright MCP is a general browser tool for any AI client. Test Agents are purpose-built agents for planning, generating and healing Playwright Test suites.

---

🎯 Next Steps

• 🤖 AI Tools for QA Engineers
• 🏗️ Project 1: Beginner Automation Project
• 🎭 Playwright MCP
• 🎭 Playwright Tutorial with TypeScript