Screenshots and recordings

Capture screenshots and video recordings of Maestro flows for debugging, regression review, and release notes.

Screenshots and screen recordings are the most useful artifact a flow run produces, and the easiest one to forget to enable. This guide covers when to take them, how to organise them, and how to keep your CI artifacts under control.

TL;DR

Use takeScreenshot for explicit checkpoints in a flow, --debug-output for automatic per-step capture, and startRecording / stopRecording for video. In CI, upload the artifact directory and clean it up nightly — screenshots add up fast.

Explicit screenshots

The simplest form:

- launchApp
- takeScreenshot: "home"
- tapOn: "Sign in"
- takeScreenshot: "auth-form"

Files land next to the flow as home.png, auth-form.png. Use kebab-case names — they end up in artifact paths and shell-friendly names matter.

Per-step debug capture

For investigations, capture every step automatically:

maestro test .maestro/ --debug-output ./debug

Output structure:

debug/
  flow-name/
    01-launchApp.png
    02-tapOn-Sign-in.png
    ...
    hierarchy.json
    log.txt

This is overkill for green runs but invaluable when a flow fails at step 14 and you want the screen at step 13.

Video recording

Wrap a section of the flow with start/stop:

- startRecording: "checkout"
- tapOn: "Add to cart"
- tapOn: "Checkout"
- stopRecording

Recording is more expensive than screenshots. Don't wrap entire flows in it by default — the file size and IO cost adds up across shards.

Comparing runs

For visual regression, name screenshots stably across runs and diff:

# Last green run lives in baseline/
maestro test .maestro/
diff -r baseline/ .maestro-runs/latest/screenshots/ || true

For pixel-diffing, pipe each pair through compare (ImageMagick) or use a tool like Pixelmatch. Don't fail CI on pixel diff for the whole suite — fonts and rounded corners shift between OS versions. Reserve pixel diff for a curated set of UI snapshots.

Storage in CI

Per-run artifacts grow fast. A 200-flow suite with --debug-output produces 1–2 GB. Strategies:

Upload only on failure: most CI providers accept an if: failure() condition on the upload step.
Limit retention: keep PR artifacts 7 days, main 30 days, releases forever.
Compress: tar -czf debug.tar.gz debug/ typically halves the size for screenshots.

- name: Upload debug
  if: failure()
  uses: actions/upload-artifact@v4
  with:
    name: maestro-debug-${{ matrix.shard }}
    path: ./debug
    retention-days: 7

Sensitive data

Screenshots leak whatever was on screen. If your flow uses real-looking PII (emails, phone numbers, card numbers), every screenshot has it. Best practices:

Use a dedicated test fixture user with synthetic data.
Mask the keyboard frame: don't takeScreenshot immediately after inputText of a password.
Treat the artifact bucket as if it were production logs — same retention, same access controls.

Maestro Deck's run history

The desktop client keeps a local history of every run with screenshots inline. Click any step to see its screenshot and the diff against the previous run of the same flow. This is the fastest way to spot a UI regression — visually, before the assertion catches it.

Common pitfalls

Forgetting to upload on failure. The most common CI mistake: green runs upload, red runs don't. Use if: always() or if: failure() explicitly.
Screenshot before animation. A takeScreenshot immediately after tapOn may capture the in-flight transition, not the destination. Add extendedWaitUntil for the target element first.
Different DPRs. Simulators and emulators report different device pixel ratios. Diff at logical resolution, not pixel.

Screenshots and recordings

On this page