Playwright CLI for agent-driven workflows: sessions, debugging, and CI Sharding

Playwright has excellent tooling around browser automation, but most of the ecosystem still treats it as a test framework. For teams running AI coding agents and automated browser workflows, there is a different set of requirements: browser automation ↓ session persistence across runs ↓ debuggable traces when things go wrong ↓ parallel execution across CI shards The Playwright CLI directly addresses these gaps. It ships as a standalone npm package and exposes every browser operation as a CLI command; open, click, type, snapshot - without requiring a Node.js script or test runner. npm package: @playwright/cli GitHub: https://github.com/microsoft/playwright-cli The current implementation focuses on: session persistence with named instances and portable state video and trace recording built into every session CI sharding for parallel execution at scale The default behaviour keeps browser state in memory. Cookies and localStorage are preserved between CLI calls within the session, but cleared when the browser closes. For repeatable workflows, that breaks down fast — logging into an application before every run wastes time and introduces flakiness. Named sessions let you run multiple browser instances simultaneously and address them by name: playwright-cli -s=admin open https://app.example.com/admin playwright-cli -s=checkout open https://app.example.com/checkout Each session is an isolated browser instance. An agent can orchestrate workflows across multiple authenticated contexts without state leaking between them. The goal is straightforward: the same CLI binary should be able to maintain independent browser contexts for parallel workflows without requiring environment-specific configuration. The critical piece for CI and agent reuse is state persistence: log in once playwright-cli -s=admin open https://app.example.com/login playwright-cli -s=admin fill "#username" "admin" playwright-cli -s=admin fill "#password" "$ADMIN_PASS" playwright-cli -s=admin click "button[type=submit]" save cookies + localStorage to portable JSON playwright-cli -s=admin state-save admin-auth.json restore in any future session - no re-authentication playwright-cli -s=admin state-load admin-auth.json playwright-cli -s=admin open https://app.example.com/dashboard The state-save and state-load commands persist cookies, localStorage, and sessionStorage to a portable JSON file. Log in once, restore auth in every future session, no re-authenticating. For long-lived workflows that need full browser profile persistence across restarts: playwright-cli open https://app.example.com --persistent The --persistent flag saves the complete browser profile to disk. Session management at scale: playwright-cli list # list all active sessions playwright-cli -s=stale close # stop a named browser playwright-cli -s=stale delete-data # clean up user data playwright-cli close-all # close all browsers playwright-cli kill-all # forcefully kill all browser processes Agents can also pick up the session name from the environment: PLAYWRIGHT_CLI_SESSION=todo-app claude . Many teams rely on failure screenshots as their primary debugging signal. That approach tends to be fragile because: a screenshot captures one moment, not the sequence that led to it timing issues are invisible in a static image network requests and console errors are absent the agent performing the actions may interact with the page in unexpected ways Instead, the Playwright CLI provides two built-in recording mechanisms that capture the full execution context. The CLI can record .webm video of an entire session: playwright-cli video-start session-debug.webm playwright-cli -s=checkout open https://app.example.com/checkout playwright-cli -s=checkout click "#add-to-cart" playwright-cli -s=checkout click "#checkout" playwright-cli video-stop During recording, you can annotate actions with callouts and chapter markers: playwright-cli video-show-actions # annotate each action with a callout playwright-cli video-chapter "Login flow" playwright-cli video-chapter "Checkout flow" playwright-cli video-hide-actions # stop annotating This produces a timestamped, annotated video of exactly what happened. When an AI agent clicks the wrong element or navigates unexpectedly, the video shows the sequence as it occurred, not a single post-mortem screenshot. Video can also be enabled declaratively in the config file: json { "saveVideo": { "width": 1280, "height": 720 } } Traces go deeper than video. full DOM snapshots at each action network requests and responses console logs execution timeline Recording a trace: playwright-cli tracing-start playwright-cli -s=checkout open https://app.example.com/checkout playwright-cli -s=checkout click "#add-to-cart" playwright-cli -s=checkout click "#checkout" playwright-cli tracing-stop The output is a trace file inspectable in the Playwright Trace Viewer: npx playwright show-trace trace.zip Or open https://trace.playwright.dev in a browser and drop the file in. Inside the viewer you can step through every action, inspect the DOM at each point, examine network requests, view console output, and see exactly what the browser rendered at each step. This is critical when an agent does something unexpected; you are not guessing from a screenshot, you are replaying the entire session. Traces can also be enabled via environment variable: PLAYWRIGHT_MCP_SAVE_TRACE=1 For real-time observation of running agent sessions: playwright-cli show This opens a window with a session grid showing all active sessions grouped by workspace, each with a live screencast preview, current URL, and page title. Click any session to zoom in and take control, click into the viewport to drive the browser manually, press Escape to release. From the grid you can also close sessions or delete data for inactive ones. For design review and UI feedback, the dashboard supports annotations: playwright-cli show --annotate Sharding is where the CLI integrates with Playwright Test's parallel execution model. The core idea: split your test suite into N shards, run each shard on a separate CI job, and merge the results. Playwright Test natively supports sharding: npx playwright test --shard=1/4 npx playwright test --shard=2/4 npx playwright test --shard=3/4 npx playwright test --shard=4/4 Each shard runs an approximately equal portion of the test files. When fullyParallel: true is enabled in the config, sharding balances at the individual test level rather than the file level, producing more even distribution. The CLI session model composes naturally with sharded CI jobs. Each shard gets its own named session: CI job for shard 1 export PLAYWRIGHT_CLI_SESSION="shard-1" npx playwright test --shard=1/4 CI job for shard 2 export PLAYWRIGHT_CLI_SESSION="shard-2" npx playwright test --shard=2/4 This keeps browser state isolated between shards. Sessions run headlessly by default on CI; pass --headed to open only when you need to observe a specific session. Each shard produces its own report. typescript // playwright.config.ts export default defineConfig({ reporter: process.env.CI ? 'blob' : 'html', }); Blob reports contain all test results plus attachments; traces, screenshots, video. npx playwright merge-reports --reporter html ./all-blob-reports This produces a single HTML report in playwright-report/ with the combined results from every shard, including all traces and videos from every session. yaml name: Playwright Tests on: push: branches: [main] jobs: test: strategy: matrix: shardIndex: [1, 2, 3, 4] shardTotal: [4] runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 20 - run: npm ci - run: npx playwright install --with-deps - run: npx playwright test --shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }} env: PLAYWRIGHT_CLI_SESSION: "shard-${{ matrix.shardIndex }}" - uses: actions/upload-artifact@v4 if: always() with: name: blob-report-${{ matrix.shardIndex }} path: blob-report/ merge-reports: if: always() needs: [test] runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 20 - run: npm ci - uses: actions/download-artifact@v4 with: pattern: blob-report-* path: all-blob-reports - run: npx playwright merge-reports --reporter html ./all-blob-reports - uses: actions/upload-artifact@v4 with: name: html-report path: playwright-report/ Each shard runs independently, uploads its blob report, and a final job merges everything into a single HTML report with all traces and videos attached. The part I find most interesting is how these features compose into a debugging workflow for AI-driven browser automation. When an agent runs a workflow and something fails, the typical debugging approach involves: - thousands of log lines - screenshots - console output - stack traces This works, but scales poorly. With the CLI tooling, the debugging signal is structured from the start: 1. Open the merged HTML report → see which shard and which test failed 2. Open the trace for that session → step through every action frame by frame 3. Watch the session video → see the visual result of each action 4. Inspect network requests in the trace → confirm API calls returned expected data 5. Check console output in the trace → catch JavaScript errors on the page The goal is not just better debugging. The goal is to reduce the time between "something went wrong" and "I can see exactly what happened." Some areas I am currently exploring: should session state be committed to the repository for deterministic replay, or kept ephemeral? at what point does per-shard video recording become too expensive in storage? can trace diffs between passing and failing runs be automated to highlight the exact divergence point? should agents receive the full trace or a machine-readable summary first? how much of the debugging loop can be automated before human review becomes necessary? what is the smallest useful artifact set for an agent to diagnose a failure: one trace, one video, one screenshot, or all three? Current roadmap items include: deeper integration between CLI session state and Playwright Test fixtures automated trace diffing between baseline and failing runs agent-friendly failure summaries as structured output shard-aware video and trace artifact routing persistent session profiles as reusable CI artifacts locator stability analysis from trace data Curious how other teams running Playwright CLI in production agent-driven workflows are approaching these problems.