Running Tests

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

Trigger a run

testsprite test run test_3a9f21c7

Without --wait, the command exits 0 as soon as the backend accepts the run and prints a runId:

Run queued.
runId:  run_5c1d9a2b
status: queued

Wait for the verdict

--wait blocks until the run reaches a terminal status. --timeout <seconds> sets how long the CLI polls (1–3600, default 600; 1200 through a tunnel):

testsprite test run test_3a9f21c7 --wait --timeout 300

Exit	Meaning
0	passed
1	failed, blocked, or cancelled
7	Timeout before a terminal status. Resume with testsprite test wait <run-id>, except for a self-minted --local run, which cancels by default and closes its tunnel (see Ctrl-C and timeout)

On exit 7 the CLI still prints a partial object to stdout, usually { "runId": "...", "status": "running" }, so a script can recover the ID. This is a fallback, not a fresh server observation.

Resuming a run

testsprite test wait run_5c1d9a2b

test wait takes the same --timeout and returns the same exit codes. At a terminal status it prints 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

The dashboard: line (dashboardUrl in JSON, absent under --dry-run) opens the Portal run view with steps, video, and analysis.

Ctrl-C and timeout

Ctrl-C during --wait detaches the CLI. The run keeps executing and billing on the server (exit 130); stop it with testsprite test cancel <run-id>. A self-minted --local run is the exception: it requests cancellation by default and closes its tunnel. Details, refunds, and --no-cancel-on-interrupt are in Cancelling a Run.

Running against another environment

Each run targets one project environment. Omit --env for Default, or name an existing one:

testsprite test run test_3a9f21c7 --env staging --wait

An unknown name fails and never falls back to Default. A step that names another of the project’s environments is pointed at the run’s environment at dispatch; assertions and the stored plan are not changed. Creating environments, plan limits, and URLs embedded in test steps are covered in Environments.

Run against a URL without creating an environment

--target-url runs a frontend test against a URL, such as a pull-request preview:

testsprite test run test_3a9f21c7 --wait --target-url https://preview-123.example.com
testsprite test run --all --project proj_8f0f6 --wait --target-url https://preview-123.example.com

The run uses the environment that already points at that origin, or a temporary environment that is removed when the run finishes. Temporary environments are not listed and do not count toward your plan’s limit.

• Sign-in. Without --env, the run signs in with the Default environment’s test account. With --env <name>, that environment’s settings are used against the URL.
• Where it works. test run (including --all --project <id>), test create --run, and test create-batch --run. Not test rerun or testlist run.
• Reachability. A loopback URL such as http://localhost:3000 opens a tunnel automatically. Other private addresses are refused (exit 5). A reachability probe runs from your machine first (exit 5 if clearly unreachable); --skip-preflight skips it. --target-url cannot be combined with --local.
• Status. A --target-url run is recorded under its temporary environment and does not change the status shown by test list / test get (see Reading Results).

With --env, a target on a different origin is refused (exit 6, reason frontend-auth-target-origin-mismatch, nothing charged) when that environment signs in with a recorded browser session (manual or SSO login), a one-time code (OTP), or a login-once step. An environment that signs in with a username and password works against any origin, including loopback. Omit --env, or pick an environment on the target’s origin.

Without --env, the refusal applies only when the Default environment uses a recorded session. Password and one-time-code sign-in are copied to the temporary environment (one-time codes are not available through a tunnel).

Testing a locally running app

When a run resolves to a loopback environment URL, the CLI opens a tunnel for you; nothing is deployed or made public. You need the app running and a key with the run:tunnel scope (existing keys already have it; see Scopes).

testsprite test run test_3a9f21c7                   # Default environment is http://localhost:3000
testsprite test run test_3a9f21c7 --env local-dev
testsprite test run test_3a9f21c7 --local 3000      # one-off port not saved as an environment

This applies to test run (one, several, or --all), test rerun, test create --run, test create-batch --run, and testlist run. --local is accepted only by test run; it implies --wait. --no-wait is refused before dispatch, without charge (tunnel-required, exit 6).

• Frontend tests only. Backend local runs are rejected.
• --local with --env. --env staging --local 5173 runs against your local app and signs in with staging’s settings. A port matching no saved environment runs in a temporary environment that copies the Default sign-in.
• Several tests. Pass several IDs or --all --project <id> to share one tunnel.

Setup, sign-in, long-lived tunnels, limits, and troubleshooting are in Environments.

In a local batch each run has its own timeout; Ctrl-C behavior is in Cancelling a Run.

Running a whole suite

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

Pass --project or set TESTSPRITE_PROJECT_ID. Every test runs (each billed like any run) in dependency waves from --produces / --needs annotations: producers first, teardown last. See Creating Tests.

testsprite test run --all --project proj_8f0f6 --filter "checkout" --wait --max-concurrency 10

Flag	Default	Description
--all	—	Run all tests in the project (with --local, in listing order)
--project <id>	—	Project to run
--filter <substr>	—	Case-insensitive name filter
--max-concurrency <n>	50	Max in-flight polls (1–100); with --local, max runs through one tunnel (1–10, default 5)

A project holds one type of test, frontend or backend. If a batch is served by the legacy backend-only engine, frontend tests come back in skippedFrontend with an advisory; run those individually.

Exit codes

Exit 6 means a run is already in flight (wait for it) or a tunnel precondition failed (check the error reason). All codes: Exit Codes.

Where to Go Next

Reading Results

Inspect steps, pull failure bundles, and navigate run history

Rerun & Auto-Heal

Re-run a saved test, 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