Output & Scripting

The stable JSON contract, piping into jq, and composing the verification loop in a script or CI job.

Scripts and agents rely on two stable contracts: --output json and exit codes.

The JSON contract

--output json is machine-readable and changes only additively: new fields may appear, existing fields and exit codes won’t change within a major version. --output text may change freely, so script against JSON.

--dry-run emits canned data in the live response shape, so you can test a script before wiring up auth (see global flags):

testsprite --dry-run test run example_test --wait --output json

Piping into jq

RUN_ID=$(testsprite test run test_3a9f21c7 --output json | jq -r '.runId')
testsprite test wait "$RUN_ID" --timeout 600 --output json || echo "run did not pass"

testsprite test result test_3a9f21c7 --include-analysis --output json \
  | jq '{hypothesis: .analysis.rootCauseHypothesis, fix: .analysis.recommendedFixTarget}'

Branching on exit codes

testsprite test rerun test_3a9f21c7 --wait --output json
case $? in
  0)  echo "passed" ;;
  1)  mkdir -p .testsprite; testsprite test failure get test_3a9f21c7 --out ./.testsprite/failure ;;
  7)  echo "timed out — resume with: testsprite test wait <run-id>" ;;
  12) echo "out of credits" ;;
  *)  echo "other error" ;;
esac

Timeouts still leave a result

On a --wait timeout (exit 7) the CLI prints a partial object to stdout first, so you keep the runId:

testsprite test run test_3a9f21c7 --wait --timeout 30 --output json > result.json
testsprite test wait "$(jq -r .runId result.json)" --output json

The partial is { "runId": "...", "status": "running" } for an ordinary run and for a --local run adopted with --tunnel-client. A run on a tunnel the CLI opened itself is cancelled by default and reports status: "cancelled"; don’t resume it. See Cancelling a Run and Exit Codes.

A local batch prints one { tunnel, maxConcurrency, results, skipped, summary } object. results lists every requested test in input order (not-run if never started); tunnel is absent if none opened; summary is { total, passed, failed, timedOut, notRun } and excludes backend tests, which appear in skipped. The --summary-file JSON differs: { total, passed, failed, skipped, timedOut, runs[] }, with not-run tests counted as skipped. See Test an app on your machine.

A minimal CI gate

#!/usr/bin/env bash
set -euo pipefail
# Auth comes from TESTSPRITE_API_KEY; the credentials file is never touched.
testsprite test rerun --all --project "$PROJECT_ID" \
  --env staging --wait --timeout 900 --max-concurrency 4 --output json

See CI/CD for a full GitHub Actions workflow. testsprite agent install writes skill files that encode these patterns (Agent Integration).

Debugging a script

• --verbose: retry, backoff and polling messages.
• --debug: HTTP method, path, request id, latency and retry decisions. The API key is never included.

Both write to stderr, as do prompts and onboarding text, so stdout stays a single parseable payload.

An interactive run checks npm for a newer CLI once every 24 hours and prints a one-line stderr notice. It is skipped in CI, without a TTY, under --output json and under --dry-run; disable it with TESTSPRITE_NO_UPDATE_NOTIFIER=1.