Playwright Concepts

Section 2

AI Agents

MCP gave the model hands. Agents give it a plan. This section explains what an agent really is — without any jargon.

What is an AI Agent?

The formal definition

An agent is a loop: observe → think → act → observe again. The model looks at the current state, decides on an action, calls a tool (very often through MCP), reads the result, and repeats. It stops when the goal is achieved, when it hits a guardrail, or when it needs a human decision.

AI Assistant vs AI Agent

Why agents are becoming popular

Real-world examples

QA examples

Section 2.1

Why Do We Need Agents?

Traditional automation is one long human loop. Agentic testing splits that loop into specialists.

Section 2.2

Agent Architecture

A single “super agent” is hard to control. Real systems use a planner, a task manager, and a team of narrow specialists. Hover any agent to see its job.

Section 3

Playwright Agents

A Playwright Agent is not one big robot. It is a multi-agent architecture in which different agents own different responsibilities in the test lifecycle — planning, generating and healing.

Section 3.1

Planner Agent

The Planner is the analyst of the team. Give it a requirement and a URL; it gives you back a test plan a human can review before a single line of code is written.

Responsibilities

• ✓ Understand the requirement — read the story, ticket or acceptance criteria
• ✓ Analyze the prompt — separate what is in scope from what is not
• ✓ Break the task down — modules, pages, user journeys, edge cases
• ✓ Create an execution strategy — order, dependencies, test data, parallelism
• ✓ Generate the plan — a reviewable document, not code

# Test Plan — Checkout Module
Under test: shop.qaautomationlabs.com
Pages found: /cart.php, /checkout.php, /order-confirm.php

TC-01  Guest checkout — happy path            [P1]
        add product → cart → checkout → pay → confirmation id shown
TC-02  Checkout with empty cart is blocked    [P1]
TC-03  Required address fields validated      [P2]
TC-04  Cart total = sum(line items)           [P1]
TC-05  Quantity update recalculates total     [P2]
TC-06  Cart survives a page reload            [P2]

Test data:  demo@demo.com / demo  ·  product ids 1–20
Order:      TC-01 first (seeds state), rest independent
Not in scope: real payment gateway, email delivery

Section 3.2

Generator Agent

The Generator is the developer of the team. It takes the approved plan and writes real, runnable Playwright code — using locators read from the live DOM, not invented from memory.

Responsibilities

• ✓ Create Playwright code — idiomatic, typed, lint-clean
• ✓ Create Page Objects — one class per page, actions not selectors leaking into specs
• ✓ Generate locators — prefer getByRole / getByTestId over CSS chains
• ✓ Assertions — web-first, auto-retrying expect()
• ✓ Fixtures — login state, seeded data, cleanup
• ✓ Test data — deterministic, isolated per worker
• ✓ Reports — wire up HTML reporter, traces, videos on failure

// pages/CartPage.ts — generated page object
import { Page, Locator, expect } from '@playwright/test';

export class CartPage {
  readonly badge: Locator;
  readonly checkoutBtn: Locator;

  constructor(private readonly page: Page) {
    // locators read from the live DOM via Playwright MCP
    this.badge       = page.getByTestId('cart-count');
    this.checkoutBtn = page.getByRole('button', { name: 'Proceed to Checkout' });
  }

  async expectItemCount(n: number) {
    await expect(this.badge).toHaveText(String(n));
  }
}

// tests/checkout.spec.ts — generated spec
test('TC-01 guest checkout happy path', async ({ page }) => {
  const cart = new CartPage(page);
  await page.goto('/womens-wear.php');
  await page.getByTestId('add-to-cart-1').click();
  await cart.expectItemCount(1);
  await cart.checkoutBtn.click();
  await expect(page.getByTestId('order-id')).toBeVisible();
});

Section 3.3

Healer Agent

The Healer is the maintainer — and for most teams it is the agent that saves the most time. Suites rarely fail because the test logic is wrong; they fail because the UI moved.

When a test fails, the Healer does what an experienced engineer does: read the error, look at the page as it is now, compare it with what the test expected, find the element that clearly corresponds, and switch to a locator that will not break again. Then it re-runs the test — because a fix you have not verified is just a guess.

Responsibilities

• ✓ Detect failures — distinguish a broken locator from a genuine product bug
• ✓ Analyze logs — error message, stack, console, network, trace
• ✓ Find better locators — role + accessible name, or a stable test id
• ✓ Retry safely — only where a retry is legitimate, never to mask a real bug
• ✓ Repair selectors — edit the page object, not fifty specs
• ✓ Suggest fixes — propose a diff for human review rather than silently rewriting

✗ TC-01 guest checkout happy path
  TimeoutError: locator.click: Timeout 30000ms exceeded.
  waiting for locator('.btn-checkout')

— Healer: reading the current accessibility snapshot …
  button "Proceed to Checkout"  [data-testid="checkout-btn"]
  → same text, same position, class renamed by the UI refactor

— Healer: proposed patch
- checkoutBtn = page.locator('.btn-checkout');
+ checkoutBtn = page.getByRole('button', { name: 'Proceed to Checkout' });

— Healer: re-running TC-01 …
✓ TC-01 guest checkout happy path (4.1s)

Section 3.4

Complete Playwright Agent Workflow

All three agents together, including the failure branch that loops back through the Healer. Hover any node for detail.

Section 3.5

Traditional Playwright vs Playwright Agent

Same framework, same browsers, same assertions — a very different day-to-day.

Section 3.6

Real World Workflow

How the pieces sit inside a normal delivery pipeline, from a requirement landing in the backlog to a dashboard the whole team watches.

Track 3

Playwright CLI Skills

There is a second way to hand a coding agent a browser — not through MCP tool schemas, but through a shell command it already knows how to run. That is @playwright/cli.

Watch the CLI loop

The real TodoMVC walkthrough from the Playwright docs. Press Play and watch each command return a fresh snapshot that the next command depends on.

Track 3.1

Playwright CLI vs MCP

Two doors into the same browser. They are not rivals — they suit different jobs.

Track 3.2

Install & Skills

Node.js 20+ and a coding agent (Claude Code, Copilot, Cursor…) are the only prerequisites.

npm install -g @playwright/cli@latest
playwright-cli --help

playwright-cli install-browser                # chromium (default)
playwright-cli install-browser firefox        # a specific browser
playwright-cli install-browser --with-deps    # + Linux system deps

playwright-cli install --skills

PLAYWRIGHT_CLI_SESSION=todo-app claude .

install-browser flags

Track 3.3

The snapshot → ref → command loop

Every CLI interaction follows the same four beats. Once this clicks, the whole command set makes sense.

What the CLI prints after every command

### Page
- Page URL: https://demo.playwright.dev/todomvc/#/
- Page Title: React - TodoMVC

### Snapshot
[Snapshot](.playwright-cli/page-2026-02-14T19-22-42-679Z.yml)

Short by design. The heavy accessibility tree lives in the .yml file; only the pointer goes into the agent’s context. That is the token trick.

Track 3.4

Command reference

The full surface, grouped the way the docs group it. Click a category.

Global options

Track 3.5

What the skills teach your agent

Running playwright-cli install --skills gives the agent structured reference guides it can pull in on demand — instead of you pasting instructions into every prompt.

No skills? Still fine.

You can point an agent at the CLI and let it discover the commands itself:

Test the "add todo" flow on https://demo.playwright.dev/todomvc
using playwright-cli. Check playwright-cli --help for available commands.

Skills work with Claude Code, GitHub Copilot, Cursor and any agent that supports locally installed skills.

Track 3.6

Which one should you reach for?