Playwright Agents: AI-Powered Test Generation, Planning, and Self-Healing

Playwright has always been the gold standard for browser automation. Reliable auto-wait, a first-class TypeScript API, and a massive community made it the default choice for teams investing seriously in E2E testing. But writing tests still required a developer who understood the codebase, knew how to pick stable selectors, and had time to maintain the suite as the UI evolved.

Playwright v1.50 changes that equation. Three built-in AI agents — Planner, Generator, and Healer — automate the parts of the test lifecycle that have always eaten the most time. This post walks through what each agent does, how to install and run them, and where their limits are.

What Are Playwright Agents?

Playwright Agents is not a plugin, a third-party wrapper, or an experimental branch. As of v1.50, it ships as part of the @playwright/test package under the agents namespace. You do not need to install anything extra beyond the standard Playwright setup.

The three agents form a pipeline:

1. Planner — explores the app and writes a test plan
2. Generator — converts the plan into .spec.ts files
3. Healer — monitors the suite and repairs broken tests

Each can be used independently, but they are designed to work together.

The Planner Agent

The Planner is the first agent in the pipeline. You point it at a URL and it drives a real Chromium instance, clicking through flows, filling forms, navigating between pages. As it explores, it produces a structured Markdown document listing the user scenarios it discovered.

Running the Planner

npx playwright agent plan --url https://your-app.com --output plan.md

The output is a Markdown file organized by feature area. A typical excerpt looks like this:

## Authentication

### Scenario: User can sign in with valid credentials
1. Navigate to /login
2. Fill email field with a valid user email
3. Fill password field
4. Click the "Sign in" button
5. Assert: redirect to /dashboard
6. Assert: user avatar visible in nav

### Scenario: Invalid credentials show error
1. Navigate to /login
2. Fill email with invalid@example.com
3. Fill password with wrongpassword
4. Click "Sign in"
5. Assert: error message "Invalid email or password" is visible

You can edit this file before passing it to the Generator. This is intentional — the plan is the contract between what the AI understood and what you actually want to test. Reviewing it takes five minutes and catches misunderstandings before they become bad tests.

What Planner Does Well

Planner is good at discovering happy paths and obvious error states. It handles SPAs, modals, multi-step forms, and client-side navigation. It respects aria-label and semantic HTML when available, which produces more stable plans.

Planner Limitations

Planner does not understand business logic. It will not discover that a user needs a specific subscription tier to access a feature unless that gate is visually present in the UI. It also cannot authenticate against apps that use SSO or complex OAuth flows without help — you need to provide a pre-authenticated state or a test account.

The Generator Agent

Once you have a plan, the Generator converts it into runnable Playwright TypeScript test files.

npx playwright agent generate --plan plan.md --output tests/

For the authentication scenario above, Generator produces something like:

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

test.describe('Authentication', () => {
  test('User can sign in with valid credentials', async ({ page }) => {
    await page.goto('/login');
    await page.getByLabel('Email').fill('user@example.com');
    await page.getByLabel('Password').fill('testpassword123');
    await page.getByRole('button', { name: 'Sign in' }).click();
    await expect(page).toHaveURL('/dashboard');
    await expect(page.getByTestId('user-avatar')).toBeVisible();
  });

  test('Invalid credentials show error', async ({ page }) => {
    await page.goto('/login');
    await page.getByLabel('Email').fill('invalid@example.com');
    await page.getByLabel('Password').fill('wrongpassword');
    await page.getByRole('button', { name: 'Sign in' }).click();
    await expect(page.getByText('Invalid email or password')).toBeVisible();
  });
});

The Generator uses getByRole, getByLabel, and getByTestId preferentially — the same selector hierarchy Playwright recommends for resilience. It adds await correctly, uses expect assertions, and groups scenarios into describe blocks.

Generator Limitations

Generated tests use placeholder credentials like user@example.com. You will need to replace these with real test account values or hook them into your fixtures. The Generator also does not understand your authentication fixtures or test.use() patterns — it generates standalone tests. Integrating them into an existing test suite with shared state requires manual work.

The Healer Agent

The Healer is the most practically valuable of the three for established codebases. It monitors your existing test suite, detects failures caused by selector drift, and patches them automatically.

npx playwright agent heal --config playwright.config.ts

How Healer Works

When a test fails, Healer does not just log the error. It:

1. Captures the current DOM snapshot at the point of failure
2. Identifies the selector that stopped matching
3. Generates candidate replacement selectors ranked by resilience
4. Patches the test file
5. Re-runs the patched test to verify the fix
6. If the fix passes, commits the change to the test file

A Concrete Example

Suppose your app ships a form redesign. The submit button changes from id="submit-btn" to id="form-submit". Your test was:

await page.locator('#submit-btn').click();

This now throws Locator: nothing found for CSS selector #submit-btn. Healer sees the failure, inspects the current DOM, finds a button with type="submit" and text content "Submit", and rewrites the line:

await page.getByRole('button', { name: 'Submit' }).click();

It re-runs the test. It passes. Healer writes the change back to your .spec.ts file.

What Healer Cannot Fix

Healer repairs selector drift — the most common cause of flaky tests after UI changes. It does not fix logic errors. If the form now requires a new required field before submission, Healer cannot add that field fill to the test. If a flow changed (login now has a two-step verification screen), Healer cannot restructure the test flow. Those require human review.

The Full Workflow

Here is the pipeline end to end:

# Step 1: Explore the app and generate a plan
npx playwright agent plan --url https://staging.your-app.com --output plan.md

<span class="hljs-comment"># Step 2: Review plan.md, edit scenarios as needed

<span class="hljs-comment"># Step 3: Generate test files from the plan
npx playwright agent generate --plan plan.md --output tests/generated/

<span class="hljs-comment"># Step 4: Run the suite
npx playwright <span class="hljs-built_in">test

<span class="hljs-comment"># Step 5: Heal any failures from selector drift
npx playwright agent heal --config playwright.config.ts

This workflow takes a new feature from zero to test coverage in under an hour, including review time.

Requirements and Setup

Playwright Agents require:

• Node.js 18 or later
• @playwright/test v1.50 or later
• Browser binaries installed (npx playwright install)
• An OpenAI API key (or compatible LLM endpoint) — set as PLAYWRIGHT_AI_KEY in your environment

The agents make LLM calls to analyze the DOM and generate/repair test code. You are billed for those API calls directly by your LLM provider.

npm install -D @playwright/test@latest
npx playwright install chromium
export PLAYWRIGHT_AI_KEY=sk-...

When Playwright Agents Are Not Enough

Playwright Agents are a significant step forward for individual developers. But they have structural limitations that matter at team scale:

No cloud hosting. Tests run on your machine or your CI runner. There is no persistent cloud environment, no always-on health monitoring, and no scheduled runs without setting up your own cron infrastructure.

No team dashboard. Results live in your terminal or your CI logs. There is no shared view of test history, flakiness trends, or coverage across the team.

No non-technical access. The Planner and Generator are CLI tools. PMs, QA leads, and non-developer stakeholders cannot create or review tests without a developer in the loop.

Maintenance still requires local setup. Healer runs locally. If a test breaks at 2am on a Friday, no one knows until someone checks CI on Monday.

No scheduling. Running tests on a schedule against production requires your own cron setup and CI configuration.

HelpMeTest: Cloud-Hosted AI Testing Without the Setup

If Playwright Agents give you the generation and healing but leave the infrastructure problem unsolved, HelpMeTest picks up where they stop.

HelpMeTest is a cloud-hosted test automation platform at $100/month flat — unlimited tests, unlimited runs. It uses Robot Framework + Playwright under the hood with an AI layer for test generation and self-healing. You write tests in plain English, run them from the cloud, and get results in a shared dashboard your whole team can see.

No Node.js setup. No browser binaries. No CI configuration for scheduling. Install with one command:

curl -fsSL https://helpmetest.com/install | bash

Or connect it directly to your AI coding agent via MCP:

helpmetest install mcp --claude HELP-your-token-here

Playwright Agents are an excellent choice for developers who live in the Playwright ecosystem and want AI assistance in their local workflow. HelpMeTest is the choice for teams that need persistent, scheduled, cloud-hosted automation that any team member can use — without a Playwright expert in the room.