Skip to main content

​
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:
ExitMeaning
0Run reached passed
1Run reached failed, blocked, or cancelled
7Timeout elapsed before a terminal status — resume with testsprite test wait <run-id>

​
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

​
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 backend suite

Run every backend test in a project in a single wave-ordered batch: 
testsprite test run --all --project proj_8f0f6 --wait
--all requires --project. The run respects dependency waves derived from --produces / --needs annotations set at test-creation time — producer tests run before the consumers that depend on their output variables.

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
FlagTypeDefaultDescription
--allbool—Run all BE tests in the project (wave-ordered)
--project <id>string—Required with --all
--filter <substr>string—Case-insensitive name filter
--max-concurrency <n>number50Max simultaneous triggers (1–100)
--all is backend-only in the current release. To batch-trigger frontend tests, use testsprite test create-batch --run --wait when creating, or rerun an existing suite with testsprite test rerun --all --project.

​
Run status and exit codes

Every test run and test wait exits with a code your script or agent can branch on:
Exit codeMeaning
0passed (or run queued without --wait)
1failed, blocked, or cancelled
3Auth error — check your API key or scopes
4Test or run not found
5Validation error — bad flag value or URL rejected
6Conflict — this test already has a run in flight
7Timeout — resume with testsprite test wait <run-id>
10Transport failure — retriable
11Rate 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.
When a run completes, the CLI prints a dashboard: line in text mode and includes dashboardUrl in JSON output. That link deep-dives directly into the Portal run view — steps, screenshots, 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