Playwright 1.5 Test Agents Setup Tutorial (2026)

TL;DR

The commonly searched phrase says Playwright 1.5, but Test Agents were introduced in Playwright 1.56. Install Playwright 1.56 or newer, run `npx playwright init-agents --loop=<client>`, create a seed test, then use the planner, generator, and healer in sequence.

Key Takeaways

• Playwright Test Agents require Playwright 1.56 or newer because the feature does not exist in version 1.5.
• The init-agents command creates client-specific definitions for VS Code, Claude Code, Codex, or OpenCode.
• A seed test gives the planner the same fixtures, authentication, hooks, and application entry point as the final suite.
• The planner writes a reviewable Markdown specification before the generator creates executable TypeScript tests.
• The healer should repair test implementation failures but must not hide genuine product defects.
• Regenerate agent definitions after every Playwright upgrade so their tools and instructions stay compatible.

This playwright 1.5 test agents setup tutorial gives you a working agent-assisted test flow, but first correct an important version detail: Playwright 1.5 does not include Test Agents. Microsoft introduced the planner, generator, and healer in Playwright 1.56. Use version 1.56 or newer for every command below.

You will configure one supported coding client, give its planner a deterministic TodoMVC seed, review the resulting Markdown plan, generate TypeScript tests, and apply the healer safely. If you need to establish the underlying runner first, use the Playwright TypeScript framework guide before adding agents.

Agents accelerate exploration and implementation, but generated code remains production code. Keep specifications in review, inspect every diff, and make the normal test suite the final authority.

TL;DR: Playwright 1.5 Test Agents Setup Tutorial

Choose exactly one loop value that matches the AI client you actually use: vscode, claude, codex, or opencode. The generated definitions are client integration files, while the tests and specs stay ordinary repository artifacts. Re-run init-agents whenever you upgrade Playwright.

What You Will Build

By the end, your repository will contain:

• A Playwright 1.56+ TypeScript project configured for Chromium and a stable public TodoMVC target.
• Client-specific planner, generator, and healer definitions created by Playwright itself.
• A tests/seed.spec.ts bootstrap that opens the application and proves its starting state.
• A reviewed specs/todo-basic-operations.md plan describing add, complete, filter, and persistence behavior.
• Executable tests generated from that plan and verified through Playwright's runner and HTML report.

The workflow separates intent from implementation. The plan is the readable contract, the generated spec is executable evidence, and the healer is a constrained repair mechanism. That separation makes review much clearer than asking a general chatbot to invent a large test file in one pass. For broader prompting patterns, compare this workflow with using ChatGPT to write Playwright tests.

Prerequisites

Use these exact baseline versions for a reproducible 2026 setup:

• Node.js 22.x LTS and npm 10.x or newer.
• @playwright/test 1.56.0 or newer. The examples remain valid on the current Playwright release.
• Git 2.45 or newer for reviewing generated changes.
• One supported agent client: VS Code 1.105+ with its agent experience, Claude Code, Codex, or OpenCode.
• Permission to run a browser and write agent definition files in the project.

Check the local tools before changing anything:

node --version
npm --version
git --version

Expect Node output beginning with v22.. If an existing repository already uses a supported newer Node line, do not downgrade it solely for this tutorial. The application under test is https://demo.playwright.dev/todomvc/, so you do not need to start a local server. For a private application, substitute its staging URL and follow the same structure.

Verification: All three commands exit with code 0, and your coding client opens the repository as a trusted workspace.

Step 1: Install a Compatible Playwright Version

Create a clean project or work inside an existing test repository. These commands make a minimal TypeScript project without depending on interactive scaffolding:

mkdir playwright-agent-demo
cd playwright-agent-demo
npm init -y
npm install --save-dev @playwright/test@^1.56.0 typescript@^5.9.0
npx playwright install chromium

Pinning the minimum with ^1.56.0 communicates why the feature is available while allowing compatible minor updates. In a production repository, your lockfile fixes the actually installed version. Commit package-lock.json so CI and teammates resolve the same dependency graph.

Add useful scripts to package.json manually or with npm:

npm pkg set scripts.test="playwright test"
npm pkg set scripts.test:chromium="playwright test --project=chromium"
npm pkg set scripts.report="playwright show-report"

Now confirm the installed CLI rather than assuming the package operation succeeded:

npx playwright --version
npx playwright --help

The version must report 1.56.0 or higher. The help output should include init-agents. If it does not, inspect npm ls @playwright/test for an older transitive or workspace-resolved package. Playwright 1.5 is an historical release and cannot be made compatible through a flag.

Verification: npx playwright --version reports at least 1.56, and npx playwright --help lists the agent initialization command.

Step 2: Configure the Playwright Project

Create playwright.config.ts with a single browser project. One browser keeps the agent feedback loop quick; cross-browser coverage can be restored after the scenarios are stable.

import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  fullyParallel: true,
  forbidOnly: Boolean(process.env.CI),
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: [['list'], ['html', { open: 'never' }]],
  use: {
    baseURL: 'https://demo.playwright.dev/todomvc/',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
  },
  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
  ],
});

baseURL lets generated tests use page.goto('/'), which makes moving from the demo to another environment a configuration change. Traces on the first retry give a healer or human reviewer DOM snapshots, network events, and action history without recording every successful local run. One CI worker favors deterministic diagnosis; increase it only after proving the suite has isolated data.

Create the expected directories:

mkdir -p tests specs
npx playwright test --list

An empty suite can print that no tests were found and return a nonzero status, depending on the installed release. That does not invalidate the configuration. A TypeScript parse error, unknown device, or failure to load playwright.config.ts does.

Verification: The runner loads playwright.config.ts without a syntax or module-resolution error and identifies the chromium project.

Step 3: Generate Planner, Generator, and Healer Definitions

Run init-agents once with the loop matching your coding client:

# Pick one command, not all four.
npx playwright init-agents --loop=vscode
npx playwright init-agents --loop=claude
npx playwright init-agents --loop=codex
npx playwright init-agents --loop=opencode

For example, this tutorial uses Codex:

npx playwright init-agents --loop=codex

The command writes static definitions tailored to that client. Those definitions combine Playwright-maintained instructions with the browser and MCP tools the agents need. Do not copy definition files from a blog post because their schema and tool list can change. Let your installed Playwright package generate the matching files.

Inspect the result rather than relying on a fixed directory name from another client:

git status --short
find . -maxdepth 4 -type f | sort

You should see new client configuration files representing planner, generator, and healer roles. VS Code commonly places definitions under .github/, while another client can use its own conventions. Read the generated files before committing them. They can execute browser actions and modify test artifacts, so repository review is part of setup, not optional ceremony.

Whenever @playwright/test changes, run the same initialization command and review the diff. Regeneration picks up new tools, safety instructions, and supported workflow details.

Verification: Three agent roles are visible to your selected client, and git diff --stat shows only the definitions you intended to add.

Step 4: Write a Deterministic Seed Test

The planner needs a known entry point. Create tests/seed.spec.ts:

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

test('seed: open an empty TodoMVC workspace', async ({ page }) => {
  await page.goto('/');

  const todoInput = page.getByPlaceholder('What needs to be done?');
  await expect(todoInput).toBeVisible();
  await expect(todoInput).toBeEditable();
  await expect(page.locator('.todo-list li')).toHaveCount(0);
});

A seed is executable setup and an implementation example, not a full business scenario. It tells the planner which config, fixtures, hooks, and authentication path to use. In a real system, import your custom test fixture instead of @playwright/test, and let that fixture create isolated users or restore approved storage state. Never place credentials, session cookies, or production tokens in the seed file.

Run it directly:

npx playwright test tests/seed.spec.ts --project=chromium

The three assertions prove that navigation succeeded, the input accepts interaction, and local browser state begins empty. If TodoMVC retained data, a fresh Playwright browser context should still isolate the test. That property matters because the planner will run the seed before exploring.

For mature repositories, add a short comment naming any required project dependency and test-data boundary. Avoid page-specific cleanup hidden outside fixtures, because an agent cannot reason reliably about invisible shared state.

Verification: The terminal reports one passed test for Chromium, and no trace or screenshot failure artifact is created.

Step 5: Ask the Planner for a Reviewable Test Plan

Open your coding client's agent interface, select the Playwright planner, include tests/seed.spec.ts in context, and send a bounded request such as:

Using tests/seed.spec.ts, explore TodoMVC and create
specs/todo-basic-operations.md. Cover adding two uniquely named
todos, completing one item, filtering Active and Completed, and
checking that the remaining count changes. Do not test framework
implementation details. Record observable steps and expected results.

The planner should run the seed, inspect the live UI, and write Markdown. It should not create .spec.ts implementation files during this phase. Review the plan for user-visible outcomes, independent scenarios, explicit data, and correct preconditions. Reject vague expectations such as "works correctly." Replace them with observable facts such as an item count, checked state, URL fragment, or visible row.

A useful plan maps each scenario back to the seed and states the expected result after every meaningful action. It should mention how multiple rows are distinguished. Unique values such as agent-plan-alpha and agent-plan-beta prevent accidental matches against stale or duplicate content.

Check the artifact locally:

test -f specs/todo-basic-operations.md
sed -n '1,240p' specs/todo-basic-operations.md
git diff -- specs/todo-basic-operations.md

Do not proceed merely because a file exists. Confirm that the planner stayed within the requested scope and did not add destructive cleanup, arbitrary sleeps, or dependencies on scenario order. Planning is the cheapest point to correct misunderstood acceptance criteria.

Verification: The Markdown file contains the seed reference, at least four concrete scenarios, numbered actions, and explicit expected results, with no executable test code masquerading as a plan.

Step 6: Generate Executable TypeScript Tests

Select the Playwright generator and attach or name specs/todo-basic-operations.md. Use this request:

Generate Playwright TypeScript tests from
specs/todo-basic-operations.md. Follow playwright.config.ts and the
seed test. Put the suite in tests/todo-basic-operations.spec.ts.
Use user-facing locators and web-first assertions. Run the generated
tests in the chromium project and report any unmet plan requirement.

The generator explores the live application while implementing the plan, so it can validate locators and assertions. Review the output for getByRole, getByLabel, getByPlaceholder, or scoped locators that express user meaning. CSS can be appropriate for a stable application contract, but long DOM paths and nth() selectors often encode incidental layout.

A representative generated scenario should resemble this runnable test:

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

test('complete one todo and filter completed items', async ({ page }) => {
  await page.goto('/');
  const input = page.getByPlaceholder('What needs to be done?');

  await input.fill('agent-plan-alpha');
  await input.press('Enter');
  await input.fill('agent-plan-beta');
  await input.press('Enter');

  const alpha = page.locator('.todo-list li').filter({ hasText: 'agent-plan-alpha' });
  await alpha.getByRole('checkbox').check();
  await page.getByRole('link', { name: 'Completed' }).click();

  await expect(alpha).toBeVisible();
  await expect(page.getByText('agent-plan-beta', { exact: true })).toBeHidden();
  await expect(page).toHaveURL(/#\/completed$/);
});

Run the generated file independently:

npx playwright test tests/todo-basic-operations.spec.ts --project=chromium

Then inspect the diff as seriously as a human-authored change. AI code review for Playwright tests provides a focused checklist for locator quality, assertion strength, isolation, and hidden side effects.

Verification: Every generated test passes in Chromium, each plan scenario has a corresponding test, and no test relies on another test's data.

Step 7: Use the Healer Without Hiding Product Defects

A healer is valuable when the test implementation is stale, not when the product violates an accepted requirement. Create a controlled locator-only failure in a temporary branch by changing the TodoMVC input locator to a nonexistent placeholder, then run the file:

npx playwright test tests/todo-basic-operations.spec.ts --project=chromium

Select the Playwright healer and give it the exact failing test name:

Heal the failing test "complete one todo and filter completed items".
Preserve every business assertion from the Markdown specification.
Inspect the current UI, make the smallest test-only change, and rerun
that single test. If the expected product behavior is absent, do not
weaken or skip the assertion. Report it as a probable product defect.

The healer can replay the failure, inspect equivalent elements or flows, patch the test, and rerun it. Its acceptable result is a minimal locator correction. Removing toHaveURL, replacing a count with a visibility check, adding waitForTimeout, or skipping the scenario changes the contract and should fail review. Official behavior allows a healer to skip when it believes functionality is broken, but your team should require a human decision before committing that skip.

Review and rerun the whole relevant file:

git diff -- tests/todo-basic-operations.spec.ts
npx playwright test tests/todo-basic-operations.spec.ts --project=chromium
npx playwright show-report

For failures without an obvious locator cause, use the diagnosis process in the flaky test debugging guide before accepting repeated automated edits. A passing retry does not prove the repair is correct.

Verification: The original assertion set remains intact, the diff is limited to the stale implementation detail, and the complete generated file passes from a clean run.

Step 8: Commit and Operate the Agent Workflow Safely

Your completed repository should have this conceptual shape, although the client definition directory varies:

playwright-agent-demo/
  client-agent-definitions/
    planner
    generator
    healer
  specs/
    todo-basic-operations.md
  tests/
    seed.spec.ts
    todo-basic-operations.spec.ts
  package.json
  package-lock.json
  playwright.config.ts

Run the same checks a normal Playwright contribution receives:

npx playwright test --project=chromium
git status --short
git diff --check

Commit definitions, reviewed plans, configuration, tests, and the lockfile. Do not commit playwright-report/, test-results/, authentication state, or client caches. Add those artifacts to .gitignore if the initializer did not. Keep plan changes and generated implementation in the same pull request so a reviewer can compare intent with execution.

Treat each role as independently callable. Use the planner when requirements need exploration, the generator when an approved plan needs implementation, and the healer only against a named failure. Sequential use is convenient, but an uncontrolled loop can convert a product regression into a weakened green test. Place limits on changed files, reruns, and skipped tests in your prompts and review policy.

Regenerate definitions after upgrading Playwright:

npm install --save-dev @playwright/test@latest
npx playwright install chromium
npx playwright init-agents --loop=codex
git diff

Substitute your selected loop value. Never approve a regeneration diff without checking whether permissions, commands, or output paths changed.

Verification: A fresh checkout can run npm ci, install Chromium, and pass the suite without untracked secrets or machine-specific paths.

Best Practices

• Keep the Markdown plan authoritative. A generated test must implement its expected outcomes, not reinterpret them.
• Give agents the smallest useful context: config, seed, approved plan, and relevant fixtures. Extra files increase the chance of copying obsolete patterns.
• Use staging or disposable local data. Agent exploration performs real interactions and can submit forms, delete records, or trigger notifications.
• Prefer semantic locators and web-first assertions. They express what the user observes and inherit Playwright's retry behavior.
• Require a clean Git state before healing. A focused diff is the easiest way to detect weakened assertions or unrelated edits.
• Cap repair attempts. After two unsuccessful, materially different patches, stop and diagnose the application, data, network, and trace manually.
• Run the target test first, then the feature file, then the relevant project suite. Each wider ring catches a different class of side effect.
• Review generated tests with the same ownership rules as handwritten tests. An agent is an implementation tool, not an accountable author.

Troubleshooting

Problem: init-agents is an unknown command -> Run npx playwright --version and npm ls @playwright/test. Upgrade the package resolved in the current workspace to 1.56 or newer, then invoke the local CLI again. Installing a newer global package will not fix an older project-local binary.

Problem: The coding client does not show planner, generator, or healer -> Confirm that --loop matches the client, reload the repository window, and inspect the generated paths with git status --short. For VS Code, verify version 1.105 or newer. Do not rename generated definition files unless the client documentation explicitly requires it.

Problem: The planner cannot open the application -> Run the seed test outside the agent. Correct baseURL, start the configured web server, or resolve authentication and TLS problems before planning. The planner cannot repair an unavailable environment.

Problem: The generator produces brittle CSS or duplicate matches -> Strengthen the Markdown plan with unique data and observable roles, then ask the generator to recheck locators live. Scope repeated rows with filter({ hasText }) and prefer accessible names over positional selectors.

Problem: The healer removes an assertion or adds a skip -> Reject the patch and restore the specification's expectations. Determine whether the UI behavior is genuinely broken. A skipped test is an explicit coverage decision and requires human ownership.

Problem: A test passes alone but fails in the suite -> Look for shared accounts, reused storage state, order dependence, or parallel data collisions. Generate unique data per test, move setup into isolated fixtures, and use traces to compare the standalone and suite executions.

Interview Questions and Answers

Q: Why does this tutorial require Playwright 1.56 instead of 1.5?

Test Agents were introduced in 1.56. Version 1.5 predates the feature, so it cannot provide init-agents or the three maintained definitions. The assigned search phrase is preserved, but the executable prerequisite is corrected.

Q: What is the purpose of a seed test?

It executes the environment setup needed for exploration and demonstrates the repository's fixtures, hooks, and coding conventions. It should establish a deterministic starting page without duplicating the complete scenario.

Q: How are planner and generator responsibilities different?

The planner explores behavior and records scenarios, steps, data, and expected results in Markdown. The generator converts that approved contract into executable Playwright tests and validates its locators against the application.

Q: When should a healer refuse to make a test pass?

It should not weaken assertions when the product no longer meets an accepted expectation. In that case, preserve the failure and report a probable application defect for human triage.

Q: Why regenerate definitions after a Playwright upgrade?

The definitions contain Playwright-maintained instructions and tool integrations. Regeneration aligns them with the installed release and exposes the exact diff for review.

Practice explaining these boundaries aloud with the top Playwright interview questions, then demonstrate them with a small repository rather than describing agentic testing only in theory.

Where To Go Next

Move the TodoMVC example to a disposable environment for your own product. Replace the public baseURL, import your real fixtures in the seed, and ask the planner for one narrow, high-value user journey. Keep its first plan small enough that a reviewer can compare every expectation with one generated test.

Next, strengthen the surrounding framework through the Playwright TypeScript framework tutorial, apply the AI Playwright test review checklist, and learn systematic flaky test root cause analysis. You can also rehearse the design trade-offs in the Playwright interview question guide or run hands-on browser exercises in QAJobFit practice.

The durable workflow is simple: explore into a precise plan, generate against that plan, heal only implementation drift, and let reviewed assertions define success. That gives you the speed of Playwright Test Agents without surrendering test intent or engineering accountability.

Conclusion

You built a Playwright 1.56+ project with client-specific planner, generator, and healer definitions, a deterministic seed test, a reviewable Markdown plan, and executable TypeScript coverage. The workflow keeps test intent visible by separating planning, generation, and constrained repair. Your next step is to move the example to a disposable environment for your own application and generate one narrow, high-value journey. Review the plan, generated tests, and any healing diff with the same rigor as human-authored code.

Interview Questions and Answers

Frequently Asked Questions

Related Guides

• Playwright 1.5 API Testing TypeScript Tutorial (2026)
• Playwright Test Runner Tutorial for Beginners (2026)
• How to Debug a failing test in VS Code in Playwright (2026)
• How to Run a single test in Playwright (2026)
• How to Test a dropdown in Playwright (2026)
• How to Test an infinite scroll in Playwright (2026)