# Run and review an AI-assisted Playwright QA loop on your web app > Use your existing Playwright Test suite to establish a web-app baseline, inspect a real flow with Playwright CLI, then review any warranted fix and rerun the tests. By BIG CHANGE Editorial Published: 2026-10-22T05:05:38.615Z Updated: 2026-10-22T05:05:38.615Z Canonical: https://bigchange.ai/blog/playwright-cli-agent-web-app-qa-loop-guide ![Conceptual charcoal illustration of one person examining a mostly blank browser view on a desktop monitor, with a hand on an orange mouse.](https://bigchange.ai/api/media/file/playwright-browser-inspection-hero-v2.png) AI-generated conceptual illustration by BIG CHANGE. 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](https://github.com/microsoft/playwright-cli), [test skill](https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/playwright-tests.md) and [Playwright Test command reference](https://playwright.dev/docs/test-cli) 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](https://playwright.dev/docs/auth) 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](https://playwright.dev/docs/intro) 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](https://github.com/microsoft/playwright-cli) 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 ''`. The Playwright config may start the app through [`webServer`](https://playwright.dev/docs/test-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 '' --project='' $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 '' --project='' --debug=cli ``` In another terminal, replace the whole `` placeholder with the name from the paused test's output. Microsoft's [attach code](https://raw.githubusercontent.com/microsoft/playwright/main/packages/playwright-core/src/tools/cli-client/program.ts) 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](https://raw.githubusercontent.com/microsoft/playwright/main/packages/playwright-core/src/tools/cli-client/registry.ts) 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='' attach '' playwright-cli -s='' snapshot playwright-cli -s='' console error playwright-cli -s='' requests ``` The [official test skill](https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/playwright-tests.md) 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 ''` when one was retained; [Trace Viewer](https://playwright.dev/docs/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 '' 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](https://playwright.dev/docs/test-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](https://playwright.dev/docs/ci) 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 - [Microsoft Playwright CLI README](https://github.com/microsoft/playwright-cli) documents installation, skills, browser commands, sessions and headless behavior. Its current main-branch examples can change; confirm your installed CLI help. - [Microsoft's Playwright Tests skill](https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/playwright-tests.md) documents running the suite through Playwright Test and attaching the CLI to a paused `--debug=cli` test. It does not show a result for your app. - [Playwright Test command line](https://playwright.dev/docs/test-cli) documents test discovery, filters, projects and debug options. Your repository config supplies the names and paths. - [Playwright Test installation](https://playwright.dev/docs/intro) and [webServer configuration](https://playwright.dev/docs/test-webserver) explain current platform and app startup requirements; check the pinned version and actual config. - [Trace Viewer](https://playwright.dev/docs/trace-viewer), [reporters](https://playwright.dev/docs/test-reporters), [authentication](https://playwright.dev/docs/auth) and [CI](https://playwright.dev/docs/ci) cover evidence, sensitive state and optional pipeline verification. They do not establish that this workflow found or fixed a defect. ## Sources - [Microsoft Playwright CLI README](https://github.com/microsoft/playwright-cli) — Documents package and skill installation, Node minimum, browser commands and named sessions; main-branch examples do not verify the reader's installed CLI or app. - [Microsoft Playwright Tests skill](https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/playwright-tests.md) — Documents Test runner invocation and --debug=cli attach to a paused test; actual version support and session name must be read locally. - [Playwright Test command line](https://playwright.dev/docs/test-cli) — Documents test discovery, filters, projects and debug modes; project-specific names and results are not supplied. - [Playwright Test installation](https://playwright.dev/docs/intro) — Lists current Node/OS and browser requirements; a reader's locked release may differ. - [Playwright web server](https://playwright.dev/docs/test-webserver) — Explains configured app startup; actual command and base URL come from the reader's repo. - [Playwright Trace Viewer](https://playwright.dev/docs/trace-viewer) — Explains retained test-trace inspection; no trace was produced for this article. - [Playwright reporters](https://playwright.dev/docs/test-reporters) — Documents HTML/JSON results and configured outputs; no reader report path or outcome is known. - [Playwright authentication](https://playwright.dev/docs/auth) — Warns that saved authentication state can expose account access; reader policy controls storage. - [Playwright continuous integration](https://playwright.dev/docs/ci) — Describes CI setup; does not authorize or establish an existing successful reader job.