Skip to main content
GSD Browser treats every recorded session as a first-class audit artifact. A recording captures network traffic, annotated screenshots, and a full narration log — all packaged into a portable evidence bundle you can share, archive, or automatically convert into a Playwright regression test. This workflow is designed for flows that need to be reproduced, audited, or handed to a compliance team.

​
Start and Stop a Recording

Begin a recording before you start the actions you want to capture: 
gsd-browser record-start --name checkout-bug-2026-05
Perform your browser actions — through the CLI, MCP tools, or manual takeover in the live viewer. Then stop the recording: 
gsd-browser record-stop
In MCP mode, use browser_record_start and browser_record_stop. Recordings started during an active live viewer session are automatically enriched with human annotations and frame-level context.

​
List and Export Recordings

List all saved recordings: 
gsd-browser recordings
Export a completed recording into a self-contained, shareable bundle: 
gsd-browser recording-export <id> --output ./evidence/

​
What a Recording Bundle Contains

HAR file

A complete HTTP Archive of every network request and response made during the session, including headers and bodies.

Key screenshots

Automatic screenshots captured at key interaction points, plus any manual screenshots taken during the session.

Narration log

A timestamped, annotated action timeline showing every step the agent (or human) took, with success/failure state.

Recording manifest

A manifest.json documenting the recording metadata, redaction details, and state restoration hints.

​
Validate a Bundle

Before sharing or archiving a bundle, validate it to confirm it is complete: 
gsd-browser recording-validate ./evidence/checkout-bug-2026-05
The validator confirms the bundle manifest, redaction details, and state restoration hints are all present.

​
Generate a Playwright Test

Turn any recording into a Playwright regression test from the action timeline automatically: 
gsd-browser generate-test --name checkout-flow --output tests/checkout.spec.ts
Always review the generated test before committing it. The generator uses versioned refs (@vN:eM) as starting locators — replace them with stable Playwright locators (getByRole, getByText, etc.) and tune assertion strictness before running in CI. The generator embeds review comments directly in the output to guide you.
The generated test includes:
  • A test.describe block with step-by-step replay of every recorded action
  • DOM assertions per step (element counts, text content)
  • Screenshot reference comments for visual cross-checking

​
Take Screenshots and Save PDFs

Capture the current page state at any point during a session: 
gsd-browser screenshot --output page.png
Screenshots and PDFs can be included as supporting evidence alongside exported recording bundles.

​
Export Network Traffic

Export all network requests captured during the session as a HAR file at any time: 
gsd-browser har-export --filename session.har

​
CI Integration

Use exported bundles and generated tests in your CI pipeline:
.github/workflows/regression.yml
- name: Validate evidence bundle
  run: gsd-browser recording-validate "$BUNDLE_DIR" --json

- name: Run reviewed regression test
  run: npx playwright test tests/checkout-regression.spec.ts --reporter=list
Store reviewed generated tests in your repository under tests/e2e/. Store exported bundles as CI artifacts for audit and replay. Re-record when major UI changes invalidate the existing test.

​
Full Evidence Workflow

1

Start the recording

gsd-browser --session checkout record-start --name checkout-regression
2

Perform the flow

Run your browser actions via CLI, MCP, or manual takeover. Use annotation-request at key decision points to embed “why this step matters” notes in the narration log.
gsd-browser --session checkout annotation-request "Confirm total before payment"
3

Stop the recording

gsd-browser --session checkout record-stop
4

List and export the bundle

gsd-browser recordings
gsd-browser recording-export <id> --output ./evidence/checkout-regression
5

Validate

gsd-browser recording-validate ./evidence/checkout-regression
6

Generate the regression test

gsd-browser generate-test \
  --name checkout-regression \
  --output tests/e2e/checkout.spec.ts
7

Review, curate, and commit

Open tests/e2e/checkout.spec.ts, replace ephemeral refs with stable locators, and run npx playwright test locally before committing.