Creating Tests

Author frontend test plans and backend test code, then create individual tests or batches from the CLI.

Two kinds of tests

TestSprite has two test types, and the authoring model differs between them:

	Frontend	Backend
What it is	An ordered list of steps — interactions a real browser performs against your live app	Code that calls your API and asserts on the responses — typically Python with pytest
You author	A plan file (JSON)	The test code locally
Pass it with	--plan-from	--code-file
TestSprite runs it as	A real browser session in the cloud	Code in an isolated cloud sandbox

TestSprite stores and executes all test code as Python: frontend tests run as async Playwright scripts, backend tests as requests + pytest-style assertions. Accordingly, test code put --language accepts only python.

Create a frontend test from a plan

testsprite test create \
  --plan-from ./checkout-flow.plan.json

The plan file is a JSON document that holds the full test definition — projectId, type, name, and the planSteps array. Because everything is in the file, --project, --type, --name, --description, and --priority are ignored when --plan-from is set; use the fields inside the JSON instead.

Plan files must be ≤ 256 KB.

Example plan file structure:

{
  "projectId": "proj_8f0f6",
  "type": "frontend",
  "name": "Guest checkout — credit card",
  "planSteps": [
    { "type": "action", "description": "Navigate to https://app.example.com/cart" },
    { "type": "action", "description": "Click the checkout button" },
    { "type": "action", "description": "Fill the card number field with a test card number" },
    { "type": "action", "description": "Click the Pay button" },
    { "type": "assertion", "description": "The order confirmation message is visible" }
  ]
}

On success, the CLI prints the new testId, codeVersion, createdAt, and — when the backend supplies it — a dashboardUrl deep-linking to the Portal.

Create a backend test from code

testsprite test create \
  --project proj_8f0f6 \
  --type backend \
  --name "Create order" \
  --code-file ./tests/create_order.py

Code files must be ≤ 350 KB. In code-file mode, --project, --type, and --name are all required.

Flag	Description
--project <id>	Required. Project this test belongs to
--type <frontend|backend>	Required. Test type
--name <name>	Required. Display name (≤ 200 characters)
--code-file <path>	Required. File containing the test code (≤ 350 KB). Mutually exclusive with --plan-from
--description <text>	Optional description (≤ 2000 characters)
--priority <p0|p1|p2|p3>	Optional priority level

Backend dependency authoring

Backend tests can declare the variables they produce and consume. TestSprite uses these declarations to determine run order — producers execute before consumers, and teardown tests run last — both on test run --all and on rerun.

Flag	Description
--produces <var>	Variable this test captures (repeatable). Example: --produces orderId
--needs <var>	Variable this test requires from an upstream producer (repeatable). Example: --needs orderId
--category <str>	Use teardown or cleanup to mark a final-wave cleanup test

These flags are backend-only and are ignored for frontend tests.

# Producer: creates an order, exposes orderId downstream
testsprite test create \
  --project proj_8f0f6 --type backend \
  --name "Create order" \
  --code-file ./tests/create_order.py \
  --produces orderId

# Consumer: needs orderId from the producer above
testsprite test create \
  --project proj_8f0f6 --type backend \
  --name "Fetch order details" \
  --code-file ./tests/fetch_order.py \
  --needs orderId

# Teardown: runs after all others, cleans up state
testsprite test create \
  --project proj_8f0f6 --type backend \
  --name "Delete test orders" \
  --code-file ./tests/cleanup.py \
  --category teardown

Create and run in one command

Pass --run to trigger a cloud run immediately after the test is created. Add --wait to block until the run reaches a terminal status. Add --output json to get a machine-readable result your agent can parse.

testsprite test create \
  --project proj_8f0f6 \
  --type frontend \
  --plan-from ./checkout-flow.plan.json \
  --run --wait \
  --output json

Exit 0 means the run passed. Any non-zero exit means the run failed, was blocked, or timed out — your script can branch directly on $?. See Running Tests for the full run surface, including --timeout, --target-url, and how to resume a timed-out run with test wait <run-id>.

Creating many tests at once

Use test create-batch to create up to 50 frontend tests in a single call. This command is frontend-only.

# From a JSONL file — one plan-from spec per line
testsprite test create-batch --plans ./flows.jsonl

# From a directory of *.json plan files, sorted by filename
testsprite test create-batch --plan-from-dir ./plans/

Flag	Description
--plans <path>	JSONL file, one plan spec per line (≤ 50 specs, ≤ 5 MB). Mutually exclusive with --plan-from-dir
--plan-from-dir <dir>	Directory of *.json plan files, one spec each (≤ 50 files, ≤ 5 MB total; processed in filename order)
--run	Trigger a run for each created test
--wait	With --run, block until all runs reach a terminal status
--timeout <s>	With --run --wait, max seconds to wait (default 600)
--target-url <url>	With --run, override the project default target URL for all triggered runs
--max-concurrency <n>	With --run, max in-flight run triggers (1–100, default 50)
--idempotency-key <token>	Pin for safe retries

The server caps run triggers at 60 per minute per key. The CLI throttles to 50 per minute and auto-retries rate-limited requests — you do not need to handle this yourself.

Editing a test’s metadata, replacing its plan or code, and deleting tests all live in Editing & Deleting Tests.

Where to Go Next

Editing & Deleting Tests

Update metadata, replace a plan or code, and delete tests

Running Tests

Trigger runs, poll for verdicts, and handle timeouts

Reading Results

Fetch failure bundles, steps, and run history

Command Reference

Full flag listing for every command