Creating Tests

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

Two kinds of tests

	Frontend	Backend
What it is	Ordered steps a real browser performs against your live app	Code that calls your API and asserts on responses (Python, pytest-style)
You author	A plan file (JSON)	The test code
Pass it with	--plan-from	--code-file

All test code is stored and run as Python, so 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 (≤ 256 KB) holds the whole definition, so --project, --type, --name, --description and --priority are ignored when --plan-from is set.

{
  "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" }
  ]
}

The CLI prints the new testId, codeVersion, createdAt and, when available, a dashboardUrl.

Create a backend test from code

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

Flag	Description
--project <id>	Required (with --code-file)
--type <frontend|backend>	Required
--name <name>	Required, ≤ 200 characters
--code-file <path>	Required, ≤ 350 KB. Excludes --plan-from
--description <text>	≤ 2000 characters
--priority <p0|p1|p2|p3>	Priority level

Dependencies between backend tests

Declare the variables a test produces and consumes; producers run before consumers and teardown tests run last, on test run --all and on rerun. These flags are backend-only.

Flag	Description
--produces <var>	Variable this test captures (repeatable)
--needs <var>	Variable required from an upstream producer (repeatable)
--category <str>	teardown or cleanup marks a final-wave cleanup test

testsprite test create --project proj_8f0f6 --type backend --name "Create order" \
  --code-file ./tests/create_order.py --produces orderId
testsprite test create --project proj_8f0f6 --type backend --name "Fetch order" \
  --code-file ./tests/fetch_order.py --needs orderId
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

--run starts a cloud run right after creation; --wait blocks until a terminal status.

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 other code means it failed, was blocked or timed out (see Exit Codes). Without --env, the run uses the Default environment. --env <name> picks another, and --target-url <url> runs a frontend test against a URL without creating an environment; both are covered in Environments. For --timeout and resuming with test wait <run-id>, see Running Tests.

Creating many tests at once

test create-batch creates up to 50 frontend tests per call (frontend only):

testsprite test create-batch --plans ./flows.jsonl        # one plan spec per line
testsprite test create-batch --plan-from-dir ./plans/     # *.json files, in filename order

Flag	Description
--plans <path>	JSONL file (≤ 50 specs, ≤ 5 MB). Excludes --plan-from-dir
--plan-from-dir <dir>	Directory of *.json plan files (≤ 50 files, ≤ 5 MB total)
--run	Run each created test
--wait	With --run, wait for all runs to finish
--timeout <s>	With --run --wait, max seconds (default 600)
--env <name>	With --run, run in this environment; default is Default
--target-url <url>	With --run, run against a URL as with test create; with --env, that environment’s settings apply
--max-concurrency <n>	With --run, max in-flight triggers (1–100, default 50)
--idempotency-key <token>	Pin for safe retries

The server allows 60 run triggers per minute per key; the CLI throttles and retries for you.

To change or delete tests, see Editing & Deleting Tests.

Where to Go Next

Running Tests

Trigger runs, poll for verdicts, handle timeouts

Reading Results

Failure bundles, steps, and run history