Proof

proof

Capture evidence that code works. Terminal replays, browser videos, structured reports.

When to use this skill

• User asks to record or capture test execution
• User wants visual evidence of a command running
• User needs to generate a proof report
• User wants to attach test recordings to PRs or share them
• User wants to record an iOS Simulator or Android emulator while running mobile UI tests
• User mentions "proof", "evidence", or "capture" in the context of testing

Install

proof ships as a standalone binary. No Node.js required.

# macOS / Linux
curl -fsSL https://automaze.io/install/proof | sh

# Homebrew
brew install automazeio/tap/proof

# npm (if you have Node.js)
npm install -g @automaze/proof

# Verify
proof --version

Choose your interface

All SDKs are thin wrappers around the same CLI binary.

CLI (works everywhere)

The CLI outputs JSON to stdout, making it ideal for agent consumption and scripting.

Terminal capture

# Default: produces .cast + .html interactive player
proof capture \
  --app <app-name> \
  --command "<shell command>" \
  --mode terminal \
  --label <label> \
  --dir <output-dir> \
  --run <run-name> \
  --description "<what this captures>"

# Video export: produces .mp4 for embedding in Linear / Jira comments
proof capture \
  --app <app-name> \
  --command "<shell command>" \
  --mode terminal \
  --format video \
  --label <label> \
  --dir <output-dir>

Browser capture

proof capture \
  --app <app-name> \
  --test-file <path/to/test.spec.ts> \
  --mode browser \
  --label <label> \
  --dir <output-dir>

Simulator capture (iOS)

Records the iOS Simulator screen while running XCUITest (or any command). Requires Xcode and at least one simulator runtime installed locally.

proof capture \
  --app <app-name> \
  --mode simulator \
  --platform ios \
  --device-name "iPhone 17 Pro" \
  --command "xcodebuild test \
    -project MyApp.xcodeproj \
    -scheme MyApp \
    -destination 'platform=iOS Simulator,name=iPhone 17 Pro' \
    -parallel-testing-enabled NO \
    -disable-concurrent-destination-testing" \
  --label ui-tests \
  --dir <output-dir>

For pixel-accurate tap indicators, add ProofTapLogger.swift to the XCUITest target and replace element.tap() with element.proofTap(). Proof reads the tap log after the test and overlays red dot + ripple rings at the correct positions.

Simulator capture (Android)

Records the Android emulator screen while running Espresso or any command. Requires Android SDK and at least one AVD created locally.

proof capture \
  --app <app-name> \
  --mode simulator \
  --platform android \
  --device-name "Pixel_3a" \
  --command "./gradlew connectedAndroidTest" \
  --label ui-tests \
  --dir <output-dir>

For tap indicators, write a JSON tap log from your test script:

cat > /tmp/proof-android-taps.json << 'EOF'
[
  { "element": "Login", "x": 540, "y": 1200, "offsetMs": 1000 },
  { "element": "Submit", "x": 540, "y": 1800, "offsetMs": 3500 }
]
EOF

Proof reads $PROOF_TAP_LOG (default /tmp/proof-android-taps.json) after recording and overlays indicators.

Generate report

proof report --app <app-name> --dir <output-dir> --run <run-name> --format md
proof report --app <app-name> --dir <output-dir> --run <run-name> --format html
proof report --app <app-name> --dir <output-dir> --run <run-name> --format md,html,archive

JSON stdin mode (multi-capture)

echo '{
  "action": "capture",
  "appName": "my-app",
  "proofDir": "./evidence",
  "run": "full-suite",
  "captures": [
    { "command": "npm test", "mode": "terminal", "label": "unit" },
    { "command": "npm run lint", "mode": "terminal", "label": "lint" }
  ]
}' | proof --json

CLI output format

{
  "action": "capture",
  "appName": "my-app",
  "run": "deploy-v2",
  "recordings": [
    {
      "path": "/absolute/path/to/unit-143012.html",
      "mode": "terminal",
      "duration": 1200,
      "label": "unit",
      "exitCode": 0
    }
  ]
}

exitCode is the wrapped command's exit code (0 = success). It is always present.

Gating on test results (exit codes)

By default proof capture exits 0 even when the wrapped command fails — capturing evidence is separate from the tests passing, so dropping proof into a pipeline never changes its outcome. Read exitCode from the JSON to know whether the tests actually passed.

To make proof itself fail when the wrapped command fails (pre-push hooks, CI gates), opt in with --fail-on-error or PROOF_FAIL_ON_ERROR=1:

# Exits with npm test's exit code instead of 0
proof capture --app my-app --command "npm test" --mode terminal --fail-on-error

In JSON multi-capture mode, set "failOnError": true; the CLI emits the full JSON for every capture, then exits with the first non-zero code. This replaces the old --command "npm test; echo $? > .status" sentinel-file hack.

TypeScript SDK

import { Proof } from "@automaze/proof";

const proof = new Proof({
  appName: "my-app",
  proofDir: "./evidence",
  run: "deploy-v2",
});

await proof.capture({
  command: "npm test",
  mode: "terminal",
  label: "unit-tests",
  description: "Unit test suite",
});

await proof.report();
await proof.report({ format: "html" });
await proof.report({ format: "archive" });

See TypeScript SDK reference for full API.

Python SDK

pip install automaze-proof

from proof import Proof

p = Proof(app_name="my-app", proof_dir="./evidence", run="deploy-v2")

rec = p.capture(command="pytest tests/ -v", mode="terminal", label="tests")
print(rec.path)      # /abs/path/tests-143012.html
print(rec.duration)  # 2400

p.report()
p.report(format="html")

pytest fixture

# conftest.py
import pytest
from proof import Proof

@pytest.fixture(scope="session", autouse=True)
def proof_session(tmp_path_factory):
    p = Proof(app_name="my-app", proof_dir="./evidence")
    yield p
    p.report()

See Python SDK reference for full API.

Go SDK

go get github.com/automazeio/proof-go

import "github.com/automazeio/proof-go/proof"

p, err := proof.New(proof.Config{AppName: "my-app", ProofDir: "./evidence"})
rec, err := p.Capture(proof.CaptureOptions{
    Command: "go test ./...",
    Mode:    "terminal",
    Label:   "tests",
})
fmt.Println(rec.Path, rec.Duration)

p.Report(proof.ReportOptions{})

The Go SDK auto-downloads the binary on first use if not on PATH.

See Go SDK reference for full API.

Report formats

Output structure

<proofDir>/<appName>/<YYYYMMDD>/<run>/
  label-HHMMSS.cast        # asciicast v2 recording
  label-HHMMSS.html        # self-contained terminal player
  label-HHMMSS.mp4         # terminal video export (format=video only)
  label-HHMMSS.webm        # browser video (if browser mode)
  proof.json                # manifest with all entries
  report.md                 # generated report

Common agent workflows

Record test execution after making changes

proof capture --app my-app --command "npm test" --mode terminal \
  --label tests --dir ./evidence --run "$(date +%H%M)" \
  --description "Tests after implementing feature X"

Record multiple test suites

echo '{
  "action": "capture",
  "appName": "my-app",
  "proofDir": "./evidence",
  "run": "full-suite",
  "captures": [
    { "command": "npm run test:unit", "mode": "terminal", "label": "unit" },
    { "command": "npm run test:integration", "mode": "terminal", "label": "integration" },
    { "command": "npm run lint", "mode": "terminal", "label": "lint" }
  ]
}' | proof --json

Generate report for a PR

proof report --app my-app --dir ./evidence --run full-suite --format md

Gate a commit or CI step on test results

# Records evidence AND fails (non-zero exit) if the tests fail
proof capture --app my-app --command "npm test" --mode terminal \
  --label tests --dir ./evidence --fail-on-error

Key constraints

• Terminal mode requires --command
• Browser mode requires --test-file
• Simulator mode requires --command and --platform
• --format video only applies to terminal mode; requires Playwright Chromium (npx playwright install chromium) and ffmpeg
• --app is always required
• proof capture exits 0 by default even if the wrapped command fails; the command's real exit code is in each recording's exitCode. Use --fail-on-error (or PROOF_FAIL_ON_ERROR=1) to propagate it to the process exit code
• CLI always outputs JSON to stdout, errors go to stderr
• Report generation requires at least one capture in the run
• Simulator mode requires the simulator/emulator to be installed locally -- proof does not download or provision them
• For iOS xcodebuild tests, always pass -parallel-testing-enabled NO -disable-concurrent-destination-testing or the recording will capture an idle screen (xcodebuild clones the simulator by default)

References

• CLI guide
• TypeScript SDK
• Python SDK
• Go SDK