PLAYWRIGHT • AI TESTING • PRACTICAL TUTORIAL

Playwright
Testing Agents
Tutorial

Learn how Playwright's Planner, Generator and Healer agents can explore an application, design test coverage, generate executable tests and help repair failures.

Planner Agent Generator Agent Healer Agent Playwright AI-assisted QA 2026 Guide
P
Planner
Explore → understand → design coverage
PLAN
G
Generator
Test plan → executable Playwright tests
BUILD
H
Healer
Run → investigate failures → repair
HEAL
3 Specialised agents
Plan Explore the product
Build Generate tests
Heal Investigate failures
The big change

Test automation is becoming agentic

Traditional automation starts with a human deciding what to test, writing the test and maintaining it. Playwright Testing Agents add another layer: specialised AI agents can participate in each of those activities.

Important: this does not mean “press a button and QA disappears.” The tester still owns risk, business intent, coverage decisions, quality expectations and final review. The agents accelerate parts of the workflow.

Playwright currently provides three specialised testing agents: Planner, Generator and Healer.

You can use them independently, sequentially, or as part of a larger agentic testing workflow.

Meet the team

Three agents. Three different jobs.

A useful way to understand the model is to imagine a miniature automation team.

01

Planner

Explores the application and turns a testing objective into a structured Markdown test plan containing scenarios and user flows.

02

Generator

Reads the plan and translates scenarios into executable Playwright Test files, locators, actions and assertions.

03

Healer

Runs tests, investigates failures and attempts to repair tests when the application or automation needs adjustment.

Visual workflow

From business intent to executable tests

◎

Planner

Explores the product and identifies scenarios, actions and expected outcomes.

→
</>

Generator

Converts the approved plan into runnable Playwright tests.

→
↻

Healer

Executes tests, investigates failures and proposes or applies repairs.

The smart workflow: do not blindly automate every scenario produced by an agent. Review the Planner's coverage first. This is where your testing judgement has the highest leverage.
Before we start

What you'll need

You need a Playwright project plus a compatible coding-agent environment.

  • Node.js installed
  • A Playwright Test project
  • Your preferred supported agent loop
  • A web application or demo application to test
  • Basic understanding of Playwright tests is useful, but not essential
Hands-on

Step 1 — Create or open a Playwright project

If you do not already have a Playwright project, initialise one.

Terminal Playwright setup 
npm init playwright@latest

Follow the prompts to create your project and install the required browser dependencies.

Step 2 — Initialise Playwright agents

Playwright provides an init-agents command that generates the agent definitions required by your chosen environment.

For VS Code

Terminal VS Code agent loop 
npx playwright init-agents --loop=vscode

For Claude Code

Terminal Claude agent loop 
npx playwright init-agents --loop=claude

For Codex

Terminal Codex agent loop 
npx playwright init-agents --loop=codex
Tip: Playwright recommends regenerating agent definitions after upgrading Playwright so the definitions pick up the latest tools and instructions.
Real example

Our practice scenario

Imagine we are testing a simple task-management application. The feature allows users to create, complete, filter and remove tasks.

Business requirement

A user should be able to create tasks, mark tasks as complete, view active or completed tasks and clear completed tasks.

Our QA objective

Build meaningful automated coverage of the core user journey without manually writing every scenario from scratch.

Foundation

Step 3 — Give Planner a seed test

A seed test can initialise the environment and place the agent in the right application context before exploration begins.

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

test('open task application', async ({ page }) => {

    await page.goto('YOUR_APPLICATION_URL');

    await expect(page).toHaveTitle(/Todo|Tasks/i);

});

The seed does not need to contain the entire test suite. Think of it as the starting position from which the Planner can explore.

Agent 01

Planner — explore before you automate

Planner explores the application and creates a Markdown test plan. This is potentially the most important stage because poor coverage automated perfectly is still poor testing.

A better prompt

Prompt to Planner

Create a test plan for the core task-management workflow. Cover creation, validation, completion, filtering, deletion, useful boundary cases and important user-state transitions. Prioritise scenarios by business risk.

Notice that we did not simply say: "test this page."

A good tester gives the agent context about risk, scope and expected coverage.

Example Planner Output
✓
Create a new task
Verify a valid task appears in the active task list.
HIGH
✓
Prevent invalid task creation
Verify blank or unsupported input is handled appropriately.
HIGH
✓
Complete an existing task
Verify status and remaining task count are updated.
HIGH
✓
Filter completed tasks
Verify only completed tasks remain visible.
MEDIUM
✓
Clear completed tasks
Verify completed tasks are removed while active tasks remain.
MEDIUM
Tester checkpoint: before moving to Generator, ask: Has the plan missed accessibility, permissions, negative scenarios, data boundaries, concurrency, recovery or business-critical paths?
Agent 02

Generator — turn the plan into code

Once you are comfortable with the coverage, Generator can convert the test plan into executable Playwright Test files.

Prompt to Generator

Generate Playwright tests from the approved task-management test plan. Use resilient user-facing locators, web-first assertions and keep each test focused on a clear behaviour.

A generated test could conceptually look like this:

task-management.spec.ts Generated test example 
import { test, expect } from '@playwright/test';

test.beforeEach(async ({ page }) => {

    await page.goto('YOUR_APPLICATION_URL');

});

test('user can create a task', async ({ page }) => {

    const taskInput = page.getByPlaceholder(
        'What needs to be done?'
    );

    await taskInput.fill('Review regression results');
    await taskInput.press('Enter');

    await expect(
        page.getByText('Review regression results')
    ).toBeVisible();

});

test('user can complete a task', async ({ page }) => {

    const taskInput = page.getByPlaceholder(
        'What needs to be done?'
    );

    await taskInput.fill('Run smoke tests');
    await taskInput.press('Enter');

    await page
        .getByRole('checkbox', { name: /toggle todo/i })
        .check();

    await expect(
        page.getByText('Run smoke tests')
    ).toBeVisible();

});

Do not stop at “the code runs”

Review generated automation exactly as you would review human-written automation.

  • Are assertions meaningful?
  • Are locators resilient?
  • Are tests independent?
  • Is setup unnecessarily duplicated?
  • Could the test pass even when the feature is broken?
  • Are important business validations missing?
Reality check

Now run the tests

Generated automation becomes useful only when it survives execution against the real application.

Terminal Execute suite 
npx playwright test

This is where flaky selectors, unexpected states, incorrect assumptions and genuine product defects reveal themselves.

Agent 03

Healer — investigate failures intelligently

Healer executes the suite, examines failures and can attempt to repair failing tests.

TEST FAILED

Before

Automation expects a button labelled "Submit Order". 

page.getByRole(
  'button',
  { name: 'Submit Order' }
)

The UI has changed and now uses "Place Order".

→
INVESTIGATED

After

Healer explores the current application state and identifies a potential test repair. 

page.getByRole(
  'button',
  { name: 'Place Order' }
)

The repaired test can then be rerun and validated.

Critical testing principle: a failing test should never automatically be assumed to be a broken test. It may be revealing a genuine product defect.
Tester judgement

Should the test be healed — or should the product be fixed?

Situation Likely interpretation Tester action
Button deliberately renamed Expected UI change Update automation after verifying requirement
Expected checkout button disappeared Possible regression Investigate product before healing test
Selector tied to fragile CSS changed Automation maintenance issue Replace with resilient locator
Business total is incorrect Product defect Do not “heal” the assertion to match bad behaviour
Application is temporarily unavailable Environment/infrastructure issue Investigate environment
The complete loop

What an agent-assisted testing workflow looks like

TESTER INTENT risk + scope + goals PLANNER explores + creates plan TEST PLAN tester reviews coverage GENERATOR writes Playwright tests EXECUTE run + observe results HEALER investigate failures rerun after investigation
The right operating model

Agent responsibility vs tester responsibility

Let agents accelerate

  • Application exploration
  • Drafting test scenarios
  • Generating repetitive test code
  • Locating UI elements
  • Running automation
  • Investigating routine failures
  • Suggesting test repairs

Tester must still own

  • Business risk
  • Test strategy
  • Coverage decisions
  • Requirement interpretation
  • Oracle quality
  • Defect vs test-failure judgement
  • Release confidence
Why testers should care

What changes for QA professionals?

A

Less mechanical coding

Agents can reduce time spent translating obvious scenarios into repetitive automation code.

B

More emphasis on intent

The value of the tester moves upward toward risk, questioning, coverage and evaluation.

C

New failure modes

AI-generated tests can contain weak assertions, incorrect assumptions and misleading confidence.

Do not skip this

Common mistakes with AI-generated tests

⚠

Automating incorrect assumptions

The agent may misunderstand the intended business behaviour. A syntactically correct test can still be logically wrong.

⚠

Weak assertions

A test may perform many actions but verify very little. Activity is not the same as validation.

⚠

Happy-path bias

Exploration can naturally gravitate toward visible, straightforward paths while missing deeper risks.

⚠

Healing a real defect

Never change expected behaviour merely because an agent discovers the current application behaves differently.

⚠

Unstable test data

Generated tests can inherit shared state or fragile data, making the resulting suite flaky.

⚠

False confidence

A large number of generated automated tests does not automatically equal meaningful product coverage.

SoftwareTestingPortal model

The 7-step responsible agentic testing workflow

1

Define the testing mission

Tell the agent what quality risk or business objective you are trying to investigate.

2

Provide context

Give it useful requirements, domain rules, fixtures and starting state instead of expecting it to guess.

3

Let Planner explore

Use exploration to draft coverage, not as an automatic replacement for your test strategy.

4

Review the plan

Add missing risks, negative scenarios, boundaries and business-critical behaviour.

5

Generate and review automation

Check locators, assertions, data, isolation and code maintainability.

6

Execute and investigate

Distinguish product defects, test problems, environment issues and expected application changes.

7

Heal with human oversight

Accept repairs only when they preserve the intended behaviour and testing objective.

Quick reference

Playwright Testing Agents cheat sheet

NEW PROJECT
npm init playwright@latest
VS CODE AGENTS
npx playwright init-agents --loop=vscode
CLAUDE AGENTS
npx playwright init-agents --loop=claude
CODEX AGENTS
npx playwright init-agents --loop=codex
RUN TESTS
npx playwright test
PLANNER
Application → exploration → Markdown test plan
GENERATOR
Approved plan → Playwright Test files
HEALER
Execution → failure investigation → test repair
Career bonus

Interview questions to remember

What does the Playwright Planner agent do?

It explores an application based on the testing objective and produces a structured Markdown test plan.

What is the role of Generator?

Generator converts the test plan into executable Playwright Test files.

What does Healer do?

It runs the test suite, investigates failures and can attempt to repair failing tests.

What is the biggest risk of self-healing tests?

Mistaking genuine product regression for test maintenance and changing automation so that defective behaviour appears valid.

Do AI testing agents replace testers?

They automate and accelerate parts of exploration, generation and maintenance. Human judgement remains essential for risk, strategy, expected behaviour, coverage and release decisions.

FAQ

Frequently asked questions

Are Playwright Testing Agents the same as Playwright MCP?
No. They are related parts of the broader AI-assisted Playwright ecosystem, but they solve different problems. Testing Agents provide specialised planning, generation and healing workflows. Playwright MCP exposes browser automation capabilities to MCP-compatible AI clients.
Can Planner automatically decide my complete test strategy?
It can help produce useful coverage, but important business, regulatory, security, integration and risk-based scenarios still require tester and domain expertise.
Should every failing test be given to Healer?
No. A failing test can represent a genuine product defect, an environment issue, bad data or broken automation. Diagnose the category before accepting a repair.
Are generated tests production-ready?
Treat them as generated engineering output that requires review. Validate assertions, test isolation, maintainability, data, locators and actual business coverage.
Do I still need to learn Playwright?
Yes. Understanding locators, assertions, fixtures, test organisation, debugging and browser behaviour makes you much better at evaluating generated tests and identifying weak automation.
Is agentic testing only useful for UI tests?
The broader agentic testing idea extends beyond UI automation, but the Playwright testing-agent workflow covered here is especially useful for browser-based application testing.
What's next?

Playwright agents are only the beginning.

Planner, Generator and Healer show how software testing is shifting from simple script automation toward collaborative workflows in which testers define risk and intent while agents help explore, generate, execute and maintain automation.

The next tutorial in this series will go one level deeper: Playwright MCP — letting an AI agent interact directly with the browser.

NEXT: PLAYWRIGHT MCP TUTORIAL →
Scroll to Top