Skip to main content

​
Inspecting a test

Get the current state of a single test by ID: 
testsprite test get test_3a9f21c7
The response shows the test’s status, type, plan step count, when it was created, and which surface last authored it: 
id:            test_3a9f21c7
projectId:     proj_8f0f6
name:          Checkout flow — guest user
type:          frontend
createdFrom:   cli
status:        passed
planStepCount: 12
createdAt:     2026-06-10T08:14:22Z
updatedAt:     2026-06-15T10:04:38Z
List all tests in a project with filters: 
testsprite test list --project proj_8f0f6
Narrow by type, originating surface, or status: 
testsprite test list --project proj_8f0f6 --type frontend --status failed,blocked
testsprite test list --project proj_8f0f6 --created-from cli
FlagValuesDescription
--typefrontend | backendFilter by test type
--created-fromportal | mcp | cliFilter by authoring surface
--statuscomma-separated listAny of: draft, ready, queued, running, passed, failed, blocked, cancelled, unknown
--page-size <n>1–100, default 25Items per page
--starting-token <token>opaque cursorContinue from a previous page

​
Step-by-step results

test steps returns the cumulative execution log for a test — every step from every run, in order: 
testsprite test steps test_3a9f21c7
Scope the output to a single run with --run-id: 
testsprite test steps test_3a9f21c7 --run-id run_5c1d9a2b
Each entry shows the step name, its status (passed or failed), and the run it belongs to. Use --page-size and --max-items for large histories.
Steps logged before run IDs were tracked are excluded when you supply --run-id. If you need those older entries, query without the flag.

​
The latest result

test result returns the outcome of the most recent completed run for a test: 
testsprite test result test_3a9f21c7
Add --include-analysis to attach the AI triage block — root-cause hypothesis, recommended fix target, failure kind, and the snapshot ID that ties all artifacts together: 
testsprite test result test_3a9f21c7 --include-analysis
The analysis fields are especially useful when piping to an agent: 
testsprite test result test_3a9f21c7 --include-analysis --output json \
  | jq '{hypothesis: .analysis.rootCauseHypothesis, fix: .analysis.recommendedFixTarget}'

​
Run history

Pass --history to list prior runs instead of the latest result: 
testsprite test result test_3a9f21c7 --history
Filter by trigger source or time window: 
testsprite test result test_3a9f21c7 --history --source cli --since 7d
testsprite test result test_3a9f21c7 --history --source portal --since 2026-06-10T00:00:00Z
Paginate long histories: 
testsprite test result test_3a9f21c7 --history --page-size 10 --cursor <token>
FlagValuesDescription
--sourcecli | portal | mcp | schedule | github_actionFilter by what triggered the run
--since24h, 7d, or ISO timestampEarliest createdAt to include
--page-size <n>1–100, default 20Items per page
--cursor <token>opaque cursorContinue from a previous page

​
Triaging a failure

When a test is failed, start with the one-screen triage card: 
testsprite test failure summary test_3a9f21c7
This prints the status, failure kind, root-cause hypothesis, and recommended fix target — everything you need to decide what to do next, without downloading anything. To pull the full failure bundle to disk: 
testsprite test failure get test_3a9f21c7 --out ./.testsprite/failure
The bundle is one self-consistent, run-scoped package — failing step, DOM snapshots as text, test source, and root-cause analysis, all anchored to one snapshotId. See Failure Bundle for the full contents. Add --failed-only to keep only the failing step and its neighbors (±1), trimming the bundle for faster agent context loading: 
testsprite test failure get test_3a9f21c7 --out ./.testsprite/failure --failed-only

​
Pinning to a specific run

test failure get always returns the latest failing run for a test — that pointer moves if a new run comes in. When multiple runs might be in flight simultaneously, pin to an exact run with test artifact get: 
testsprite test artifact get run_5c1d9a2b --out ./.testsprite/runs/run_5c1d9a2b
The artifact bundle for a specific run is immutable — a concurrent Portal or schedule run cannot overwrite it. This is the safe path for agents and CI pipelines where two runs of the same test might overlap.
Use test failure get <test-id> for the interactive triage loop. Use test artifact get <run-id> in scripts and CI where you need a stable, run-scoped bundle that a concurrent run can’t shift under you.
The default output directory is ./.testsprite/runs/<run-id>/. The parent directory must exist before you run the command.

​
Reading test code

Print the generated test code to stdout: 
testsprite test code get test_3a9f21c7
Save it to a file instead: 
testsprite test code get test_3a9f21c7 --out ./tests/checkout_flow.py
The response includes the language, framework, code content, and the codeVersion token — useful if you plan to update the code with testsprite test code put and want protection against overwriting a concurrent edit.

​
Where to Go Next

Running Tests

Trigger runs, wait for verdicts, and understand exit codes

Rerun & Auto-Heal

Replay a test cheaply or let AI repair UI drift

Key Terms

runId, codeVersion, snapshotId, and the rest of the vocabulary

Command Reference

Full flag listing for every CLI command