Running Tests

Trigger a test run from the CLI, wait for a verdict, and understand every exit code the runner emits.

Trigger a run

Pass a test ID to kick off a run immediately:

testsprite test run test_3a9f21c7

Without --wait, the command returns as soon as the run is accepted by the backend — exit 0. You get a runId you can use later:

Run queued.
runId:  run_5c1d9a2b
status: queued

The test starts executing in the cloud. Come back to it with testsprite test wait <run-id> whenever you’re ready.

Wait for the verdict

Add --wait to block until the run reaches a terminal status:

testsprite test run test_3a9f21c7 --wait

Control how long the CLI polls before giving up with --timeout <seconds> (range 1–3600, default 600):

testsprite test run test_3a9f21c7 --wait --timeout 300

Exit codes when --wait is used:

Exit	Meaning
0	Run reached passed
1	Run reached failed, blocked, or cancelled
7	Timeout elapsed before a terminal status — resume with testsprite test wait <run-id>

A timeout doesn’t cost you the runId: even on exit 7, the CLI prints a partial object ({ "runId": "...", "status": "running" }) to stdout before exiting, so a script can grab the ID and resume without having captured it earlier.

Resuming a run

If a run times out or you triggered it without --wait, resume polling with the run ID:

testsprite test wait run_5c1d9a2b

test wait accepts the same --timeout flag and emits the same exit codes as test run --wait. When a terminal status arrives, you see the run card:

runId:      run_5c1d9a2b
status:     passed
targetUrl:  https://app.example.com
codeVersion: v4
startedAt:  2026-06-15T10:02:11Z
finishedAt: 2026-06-15T10:04:38Z
steps:      12 passed, 0 failed
dashboard:  https://www.testsprite.com/dashboard/tests/proj_8f0f6/test/test_3a9f21c7

Interrupting a wait vs cancelling the run

Ctrl-C during any --wait only detaches the CLI — the run keeps executing (and billing) on the server. The CLI exits 130 after printing the partial { "runId": "...", "status": "running" } plus a re-attach hint and a cancel hint, so nothing is lost. To actually stop the run server-side:

testsprite test cancel run_5c1d9a2b

The run flips to cancelled, the test is immediately re-runnable, and the test’s last verdict is untouched. Already-charged credits are not refunded.

Cancelling a Run

Detach vs cancel, idempotent re-cancel, multi-id summaries, and the CI cleanup pattern

Overriding the target URL

By default the run hits the URL stored on the project. Override it for a single run with --target-url:

testsprite test run test_3a9f21c7 --wait --target-url https://staging.example.com

The URL must be a public http(s) address; localhost and private IPs are rejected before any network call (exit 5).

Common Issues

What to check if a URL is rejected

Testing against a localhost target requires the MCP Server and its built-in tunnel, not the CLI. The CLI is designed for cloud-accessible environments and CI.

Running a whole suite

Run every test in a project in a single wave-ordered batch:

testsprite test run --all --project proj_8f0f6 --wait

--all requires --project. It triggers every test in the project (each billed like any run) and respects dependency waves derived from --produces / --needs annotations set at backend test-creation time — producer tests run before the consumers that depend on their output variables, with teardown tests last.

Creating Tests

How to declare --produces / --needs annotations

Narrow the batch with a name substring filter:

testsprite test run --all --project proj_8f0f6 --filter "checkout" --wait

Control how many runs execute simultaneously:

testsprite test run --all --project proj_8f0f6 --wait --max-concurrency 10

Flag	Type	Default	Description
--all	bool	—	Run all tests in the project (wave-ordered)
--project <id>	string	—	Required with --all
--filter <substr>	string	—	Case-insensitive name filter
--max-concurrency <n>	number	50	Max simultaneous triggers (1–100)

--all runs every test in the project in wave order. A project holds a single type of test — frontend or backend, set by --type at project create — so don’t mix both in one project. For backend projects, producers run first and teardown tests last, so dependencies are always satisfied. If a batch is served by the legacy backend-only engine, frontend tests come back in skippedFrontend with an advisory — trigger those individually with testsprite test run <test-id>.

Run status and exit codes

Every test run and test wait exits with a code your script or agent can branch on:

Exit code	Meaning
0	passed (or run queued without --wait)
1	failed, blocked, or cancelled
3	Auth error — check your API key or scopes
4	Test or run not found
5	Validation error — bad flag value or URL rejected
6	Conflict — this test already has a run in flight
7	Timeout — resume with testsprite test wait <run-id>
10	Transport failure — retriable
11	Rate limited — honor Retry-After

Exit Codes

The full exit-code table, including codes for other commands

Exit 6 means a run is already in flight for this test. Wait for it to finish (or use testsprite test wait <run-id>) before triggering another.

The dashboard link

When a run completes, the CLI prints a dashboard: line in text mode and includes dashboardUrl in JSON output (when available). That link deep-dives directly into the Portal run view — steps, video recording, analysis, and the full failure bundle — without any manual navigation.

testsprite test run test_3a9f21c7 --wait --output json | jq '.run.dashboardUrl'

The dashboardUrl is absent under --dry-run.

Where to Go Next

Reading Results

Inspect steps, pull failure bundles, and navigate run history

Rerun & Auto-Heal

Replay a saved script cheaply, or let AI repair UI drift automatically

Exit Codes

Complete exit-code reference for scripts and CI pipelines

CI/CD Integration

Wire the CLI into GitHub Actions or any pipeline