An AI coding agent can help inspect a web app, but the result is useful only if you can trace it back to your app's actual tests and an expected user flow. This guide is for a maintainer who already controls a repository with Playwright Test configured. You supply the app, test data, allowed files and success criteria; the agent helps gather browser evidence and may propose a narrow change for your review. The commands below come from Microsoft's and Playwright's documentation, checked on 22 October 2026. We did not run them against a reader app.

The big change

  • What changed: Microsoft's Playwright CLI skills describe a route from a Playwright Test run paused with --debug=cli into a browser session the agent can inspect.
  • Why it matters: A maintainer can compare a real test result with browser evidence before deciding whether the app, test or setup needs work.
  • What to watch: The attach route depends on the installed runner and CLI versions. A passing test, a flaky test and an untested flow call for different conclusions.

@playwright/cli provides browser commands such as open, snapshot, console and requests. The repository's Playwright Test runner, invoked through npx playwright test or its existing package script, discovers and executes tests and produces their results. The CLI skill connects those tools through --debug=cli when the installed runner supports it. This is a local CLI workflow, not a Playwright MCP workflow. The CLI README, test skill and Playwright Test command reference document the separate commands.

1. Define the task and check the environment

Write down the Git revision, the user flow you want to check, its expected behavior, the selected existing test or approved missing coverage, the allowed local or staging URL, safe account and data, files the agent may inspect or edit, and the person who will approve any diff. Give the agent only the repo, origin, commands and data needed for that task. A test account and the project's existing authentication setup are preferable to production credentials. Saved browser state can contain cookies and headers capable of impersonating a user; keep it and any snapshots, screenshots, traces or reports in approved storage with suitable access. Playwright's authentication guide calls out this storage-state risk.

Start in the reader's app repository. The following examples use PowerShell on Windows; replace every angle-bracket value with a value read from your own project. Do not paste the brackets as literal file names or project names. If you use another shell or package manager, translate its commands and record what you actually ran.

PowerShell
git rev-parse HEAD
node --version
npm ls @playwright/test playwright --depth=0
Get-Content package.json
Get-ChildItem -Name *playwright*config*

Inspect the lockfile and actual Playwright config as well as this output. Find the configured projects, use.baseURL, webServer, reporters, trace policy and test scripts. If the runner is not locally installed, stop and use the project's approved dependency-install procedure; npx can otherwise offer to fetch a package. For an npm project with its locked dependencies already installed, npx --no-install playwright ... makes that boundary explicit. Do not replace the repository's pinned runner with a global CLI package. Discover the real test names and project names before choosing filters:

PowerShell
npx --no-install playwright test --list
npx --no-install playwright test --help

The CLI README currently states a Node.js 18+ minimum for @playwright/cli. Current Playwright Test installation guidance lists Node 22, 24 or 26 and supported Windows, macOS and Linux versions for the current Test release. Check the requirements of your locked Test version and its selected browser binary; the CLI minimum does not establish that the whole project can run on Node 18. The Microsoft repository showed CLI package version 0.1.22 on its main branch at our check, with alpha Playwright dependencies. That repository snapshot is not a compatibility promise for your installed versions.

In an approved development environment, the CLI README documents the following installation and skill commands. Record the resolved version and read --help after installation; installing a skill does not grant an agent repository, browser or account authority. Use the project's approved method to obtain any required Test browsers and system dependencies.

PowerShell
npm install -g @playwright/cli@latest
playwright-cli install --skills
playwright-cli --version
playwright-cli --help

2. Run an existing baseline

Use the actual test path and project name from --list and the config. The examples below are templates, not a claim that your project has a chromium project or a particular spec file. Run from the repository root. Record command, revision, exit code, number of passed, failed, skipped or flaky tests, and the configured report and trace locations. The HTML reporter can open automatically on failures, so the documented environment variable keeps the run noninteractive here.

If the test selection is by title, use the title or regular expression you read from --list, with -g '<real-test-title-or-regex>'. The Playwright config may start the app through webServer. Otherwise, start the app in a separate terminal with the repository's documented start command and verify the configured baseURL or approved staging address. A CLI browser does not start the app for the test runner. A server startup, fixture or login error is a setup result until evidence points to an app defect.

PowerShell
$env:PLAYWRIGHT_HTML_OPEN = 'never'
npx --no-install playwright test '<real-test-path>' --project='<real-project-name>'
$LASTEXITCODE

A pass is a valid baseline. If the intended flow is absent from the tests, record that gap and obtain an approved acceptance criterion before asking the agent to propose a test. An agent-generated assertion is a proposal to check, not evidence that the app works.

3. Inspect the real browser path

Give the coding agent a bounded brief: the observed baseline, expected flow, allowed origin and files, safe account, commands it may run, evidence to retain and a stop point before edits or CI. Ask it to identify what it saw, which criterion it compared against and any proposed diff. The browser may expose private page data to the agent's provider; use your organization's access and retention rules.

For a selected test on an installed runner whose test --help lists --debug=cli, start a second PowerShell terminal and leave the test process running. This mode pauses at the start and prints debugging instructions. Use its actual printed session name, not the example name in Microsoft's docs:

PowerShell
$env:PLAYWRIGHT_HTML_OPEN = 'never'
npx --no-install playwright test '<real-test-path>' --project='<real-project-name>' --debug=cli

In another terminal, replace the whole <printed-session-name> placeholder with the name from the paused test's output. Microsoft's attach code uses that target as the CLI session name unless a session is explicitly selected. Specify -s on attach and every later command so they address the same browser, even if your environment selects another session. The session resolver sends a bare command to the environment-selected session or default. Read the fresh snapshot before using a reference such as e15, because those refs belong to the current page state. Inspect the permitted flow and relevant console or request errors; retain paths to the evidence you save. If you use the CLI's tracing-start and tracing-stop, select this same session on both commands. That optional CLI trace is separate from the Test runner's trace.

PowerShell
playwright-cli -s='<printed-session-name>' attach '<printed-session-name>'
playwright-cli -s='<printed-session-name>' snapshot
playwright-cli -s='<printed-session-name>' console error
playwright-cli -s='<printed-session-name>' requests

The official test skill says to keep the paused test alive during inspection and stop it when finished. Debug mode is headed and changes timing, so reproduce an issue in a normal test run as well before attributing it to app code. If --debug=cli is absent, fails, or never prints an attach name, record the exact version and output. Do not claim an attachment. Review an existing Test trace with the documented npx --no-install playwright show-trace '<actual-trace-file.zip>' when one was retained; Trace Viewer explains its actions and snapshots. You can also inspect the authorized flow in a separate named CLI session after the app is actually running:

PowerShell
playwright-cli -s=qa-review open '<approved-app-url>'
playwright-cli -s=qa-review snapshot
playwright-cli -s=qa-review console error
playwright-cli -s=qa-review requests

That fallback browser has its own state and timing. Note any differences from the failing test's fixture, account or environment. The CLI is headless by default; open ... --headed shows the browser when a human needs to watch. Avoid a persistent CLI profile for sensitive work unless the task requires and authorizes it.

4. Decide whether any change is warranted

Compare the failed assertion and browser evidence with the approved expected behavior. The cause could be app code, a locator or stale assertion, fixture data, timing, authentication, or the environment. Ask the agent for the smallest proposed app or test diff only when the evidence supports a correction within its permitted files. Review the proposed change and approve its scope before it is applied. Do not weaken an assertion or update a snapshot solely to make the result green.

If the baseline passes and the inspected flow meets the criterion, record that observation and make no defect fix. If the desired behavior has no test, review a proposed test against the real criterion and run it; do not invent a failure to justify an app change. A failure that disappears on retry remains a flaky or unresolved finding until its cause is established. Preserve the first trace and the repeat count.

5. Rerun, review and close

After an approved change, rerun the affected test with the same config, project and data, then run the relevant wider suite using the repository's established command. Review the Git diff and the final reporter and trace output at the recorded revision. Where configured, Playwright's HTML and JSON reporters give test and error detail; read the project's actual output path instead of assuming one. A targeted pass does not establish that the wider suite or the entire app works. Keep regressions and unrun checks visible, and leave an unresolved diff unaccepted.

An existing, authorized CI pipeline can add a second result after local review. Check the job's revision, environment, browser installation, test selection and report. Do not create or trigger CI without the owner's allowed scope. Record usage of any coding agent or hosted runner under the actual account; there is no fixed token saving or guaranteed speedup.

Finally, record the repo revision, installed runner and CLI versions, Node/OS/browser, app URL type, selected flow and criterion, initial result, browser evidence, any approved diff, targeted and broader reruns, optional CI result, open failures and the owner decision. Close only the named CLI session and debug or app processes started for this task. Check playwright-cli list first and keep evidence files under the approved retention policy; close-all could end somebody else's session.

PowerShell
playwright-cli list
playwright-cli -s=qa-review close

If no separate qa-review session was opened, omit that close command. Stop the paused Test process in its own terminal after inspection. A completed QA record may say “passed,” “failed,” “no coverage,” or “held pending evidence.” It should say exactly which result was observed.

Sources & further reading