Masterclass › Playwright Agent CLI › Session 1
Open TTACart Start drills
▸
The Testing Academy · Masterclass

The Playwright Agent CLI.

A command line for browser automation built for coding agents. @playwright/cli gives token-efficient commands, ref-based accessibility snapshots, a persistent browser daemon, installable skills, and isolated sessions - so an AI agent can drive a real browser without burning its context window. This session teaches it end to end, practised on the live TTACart demo app.

Host
Pramod Dutta
Track
Playwright + Agents
Audience
QA / SDET
App under test
TTACart

Foundations

What is the Agent CLI?

The Playwright Agent CLI is a separate tool from the classic npx playwright test runner. The test runner is for humans authoring specs; the Agent CLI is for an AI agent driving a browser one command at a time, with output kept small so it fits in a limited context window.

Token-efficient

Concise output

Commands return compact results, and capabilities are discovered through installable skills instead of long help text - so the agent spends tokens on reasoning, not noise.

Daemon

Persistent browser

A background browser process stays alive across commands, so there is no per-command startup cost.

Ref snapshots

Deterministic targets

An accessibility snapshot gives each element a stable ref (like e21). The agent acts on the ref, not on brittle pixels.

Sessions

Isolated state

Multiple named sessions run side by side, each with its own cookies, storage, and tabs.

App under test

We practise on TTACart

Every command targets the same live demo store - login, inventory, cart, and a multi-step checkout - so you can paste and watch the agent CLI act on a real page.

Live

TTACart store

Open it, snapshot it, and drive the login to checkout flow from the terminal.

https://app.thetestingacademy.com/playwright/ttacart/

Flow

Login → cart → checkout

Use the credentials listed on the TTACart login screen - never hard-code secrets into shared scripts.

Why

Stable refs

Clear roles and test ids mean the accessibility snapshot returns clean, reusable element refs.

Getting started

Install and verify

terminal · install the agent CLI
# install globally (provides the playwright-cli binary)
npm install -g @playwright/cli

# print the resolved configuration
playwright-cli config-print

# install on-demand skills the agent can use
playwright-cli install --skills
Note: this is @playwright/cli (the agent CLI), which is different from @playwright/test (the classic test runner you scaffold with npm init playwright@latest). They complement each other - agents explore with this CLI, then you commit durable specs with the test runner.

Core concept

Ref snapshots - how the agent sees the page

Instead of guessing selectors, the agent asks for a snapshot. It gets an accessibility tree where every actionable element has a short ref. The agent then acts on that ref - deterministic and resilient.

terminal · snapshot then act on refs
# open the store (headed so you can watch)
playwright-cli open https://app.thetestingacademy.com/playwright/ttacart/ --headed

# capture the accessibility snapshot - elements come back with refs
playwright-cli snapshot

# act on a ref returned by the snapshot (example refs)
playwright-cli fill e12 "your-username"
playwright-cli click e18          # the Login button
playwright-cli snapshot           # re-snapshot to see the next screen
Vision mode: when a control is not in the accessibility tree (e.g. a canvas), the CLI can fall back to a screenshot-based vision mode so the agent can still locate and click it.

Hands-on

Drive TTACart end to end

A full login to checkout, one command at a time. Read the actual refs from each snapshot; the refs below are illustrative.

terminal · login to checkout
playwright-cli open https://app.thetestingacademy.com/playwright/ttacart/ --headed
playwright-cli snapshot
playwright-cli fill e12 "<username from login screen>"
playwright-cli fill e14 "<password from login screen>"
playwright-cli click e18                 # Login
playwright-cli snapshot                  # inventory page
playwright-cli click e27                 # Add to cart
playwright-cli click e09                 # Cart
playwright-cli click e31                 # Checkout
playwright-cli fill e40 "Pramod"         # first name
playwright-cli fill e41 "Dutta"          # last name
playwright-cli fill e42 "560001"         # postal code
playwright-cli click e44                 # Continue
playwright-cli click e50                 # Finish
playwright-cli screenshot                # capture the confirmation
playwright-cli close

Reference

The command surface

GroupCommands
Core actionsopen goto close click dblclick fill type select check uncheck hover drag upload
Readsnapshot screenshot pdf eval resize
Dialogsdialog-accept dialog-dismiss
Navigationgo-back go-forward reload
Keyboard & mousepress keydown keyup mousemove mousedown mouseup mousewheel
Tabstab-list tab-new tab-select tab-close
Storagestate-save state-load cookie-* localstorage-* sessionstorage-*
Networknetwork route route-list unroute
DevToolsconsole run-code tracing-start tracing-stop video-start video-stop show
Sessions-s=<name> list close-all kill-all delete-data
Config--headed --browser --persistent --profile --config attach --extension install --skills config-print

State

Sessions and saved auth

Run isolated browsers in parallel, and save a logged-in state once so every later session starts authenticated.

terminal · named sessions + saved state
# run a named, isolated session
playwright-cli -s=cart open https://app.thetestingacademy.com/playwright/ttacart/ --headed

# list running sessions
playwright-cli list

# save the logged-in state, then reuse it later
playwright-cli -s=cart state-save auth.json
playwright-cli -s=checkout state-load auth.json

# tidy up
playwright-cli close-all
playwright-cli kill-all
Teach: log in once, state-save, then have every other session state-load so the agent skips the login screen and focuses on the feature under test.

Network & storage

Mock, inspect, and persist

terminal · network and storage
# inspect network activity
playwright-cli network

# mock or block a request with a route
playwright-cli route "**/api/**"
playwright-cli route-list
playwright-cli unroute "**/api/**"

# read and set cookies / storage
playwright-cli cookie-list
playwright-cli localstorage-get tta-cart
playwright-cli sessionstorage-set key value

Developer tools

Console, tracing, and video

Inspect

console & eval

Read console messages and run code in the page with run-code / eval.

Evidence

tracing

tracing-start then tracing-stop records a trace you can open in the viewer.

Record

video & show

video-start / video-stop capture the run; show opens the dashboard.

terminal · capture evidence
playwright-cli tracing-start
# ... drive the flow ...
playwright-cli tracing-stop trace.zip
playwright-cli show                 # open the dashboard / viewer
playwright-cli pdf checkout.pdf     # save the page as PDF

For agents

Skills installed on demand

Rather than dumping a giant help text into the agent's context, the CLI exposes capabilities as skills the agent installs only when it needs them. This keeps the context window lean.

terminal · skills
# install the skill set the agent can call
playwright-cli install --skills

# the agent discovers and uses skills as needed,
# instead of reading verbose --help for every command

For agents

Use it from a coding agent

The Agent CLI is designed for tools like Claude Code and Copilot working inside large codebases. The agent loops: snapshot to perceive, decide the next action, run one command, then re-snapshot - all with output small enough to leave room for reasoning.

1 Perceive

snapshot

Get the ref tree of the current page.

2 Act

one command

click / fill / type on a specific ref.

3 Verify

re-snapshot

Confirm the result, then loop or assert.

Guardrail: keep a human in the loop for destructive steps, bound the number of actions, and have the agent emit a durable @playwright/test spec once a flow is proven - do not run unbounded agents against production.

Reference

Quick cheat sheet

CommandPurpose
npm install -g @playwright/cliInstall the agent CLI.
playwright-cli open <url> --headedOpen a page in a visible browser.
playwright-cli snapshotAccessibility snapshot with element refs.
playwright-cli click <ref>Click an element by ref.
playwright-cli fill <ref> "text"Fill an input by ref.
playwright-cli type "text"Type into the focused element.
playwright-cli press EnterPress a key.
playwright-cli screenshotCapture a screenshot.
playwright-cli -s=<name> ...Run in a named, isolated session.
playwright-cli state-save / state-loadSave / reuse logged-in state.
playwright-cli tracing-start / -stopRecord a trace.
playwright-cli install --skillsInstall agent skills.
playwright-cli list / close-all / kill-allManage sessions.
playwright-cli config-printPrint resolved config.

Hands-on

Six Agent CLI drills on TTACart

A

Open & snapshot

Install the CLI, open TTACart headed, and read the first snapshot - find the login refs.

B

Log in by ref

Use fill + click on refs with the on-screen credentials, then state-save the session.

C

Checkout

Add an item, go to the cart, and complete checkout one command at a time.

D

Sessions

Run two named sessions in parallel; state-load auth into both and compare.

E

Trace it

tracing-start, drive the flow, tracing-stop, then show the result.

F

Promote to a spec

Once the flow works, write the durable @playwright/test spec and commit it.

Sources

Official references

ReferenceURL
Agent CLI - Introductionhttps://playwright.dev/agent-cli/introduction
Agent CLI - Getting startedhttps://playwright.dev/agent-cli/getting-started
Snapshots & capabilitieshttps://playwright.dev/agent-cli/snapshots
Sessions & dashboardhttps://playwright.dev/agent-cli/sessions
Classic Playwright test CLIhttps://playwright.dev/docs/test-cli
TTACart demo apphttps://app.thetestingacademy.com/playwright/ttacart/
Class dismissed. You can now install the Playwright Agent CLI, snapshot a page into refs, drive TTACart end to end, manage sessions and saved auth, capture traces, and hand a proven flow to an AI agent - then promote it to a committed Playwright spec.