Skip to main content
This page is for you if a coding agent — Claude Code, Codex, Cursor, Cline, Windsurf, Copilot — writes most of your code. You install the CLI once; from then on you describe what you want in plain language and the agent drives the CLI: it creates tests, triggers real cloud runs, reads the failure bundles, fixes the code, and reruns. By the end of this page your agent will have set up TestSprite in your repo, created a first test, and run it against your live app to a pass/fail verdict — without you typing another testsprite command.
Prefer to type the commands yourself? The human-oriented Quickstart walks the same loop from the terminal.

​
Step 1: Install and run setup (the only terminal step)

Run testsprite setup from your repo root. It chains three things:
  1. Prompts for your API key (created in the Portal under Settings → API Keys — see API Keys) and verifies it against the platform.
  2. Stores the key in ~/.testsprite/credentials.
  3. Installs the TestSprite agent skills into your agent’s project configuration — for Claude Code that’s .claude/skills/testsprite-verify/SKILL.md and .claude/skills/testsprite-onboard/SKILL.md.
Run it once per project. That’s the entire manual surface — everything after this step happens through your agent.
You can even delegate this step: paste the two commands above into your agent and let it run them. setup supports a fully non-interactive form (TESTSPRITE_API_KEY=$KEY testsprite setup --from-env --yes) for exactly this.
The skill install is pure-local — it only writes files inside your repo, makes no network requests, and needs no credentials. Eight agent targets are supported (claude, codex, cline, antigravity, kiro, windsurf, copilot, cursor); see Coding Agent Integration for where each skill file lands and how to install for multiple agents at once.

​
Step 2: The two skills your agent just learned

testsprite setup installed two skill files. They are the difference between an agent that has a CLI and an agent that knows when and how to use it — you never have to spell out the mechanics in a prompt.

​
testsprite-onboard — seed a suite in an empty project

What it does. The agent reads your codebase first — routes, handlers, the 4–8 most important user flows — instead of blindly crawling. It then creates a TestSprite project (frontend projects always get a target URL, plus login credentials if your flows need them), authors roughly 8–15 tests with concrete, observable assertions, batch-creates them, and smoke-runs only the 2–3 highest-value happy paths. What you should expect to see:
  • The agent asks for your deployed app URL (and login credentials, if needed) before creating a frontend project.
  • A report like: “Your project now has 12 tests covering login, checkout, search… I smoke-ran 3 — here are the results and dashboard links.”
  • It will not auto-run the full suite — running everything costs credits, so it quotes the cost and leaves that choice to you.

​
testsprite-verify — verify every change before “done”

What it does. After finishing a feature or fix, the agent preflights (testsprite --version, testsprite auth status), finds the right project, and picks the cheapest honest verification: rerun an existing test that covers the behavior, or author a new one (a plain-language plan file for frontend, a Python script for backend). It runs to a terminal verdict with --wait, and on failure pulls the failure bundle before deciding whether your change caused it. What you should expect to see:
  • The agent shows you the drafted plan or test code before creating it — one short confirmation, since creating writes to your project.
  • Every shipped change ends with a verdict line: test id, name, and passed / failed / blocked / inconclusive, plus a dashboard link.
  • On failure, a one-line root-cause hypothesis from the bundle — but the agent does not auto-fix on that hypothesis alone; it reads the evidence first.
  • If it can’t run a test (no credentials, no reachable URL, repo not linked), it says so explicitly — “shipped but unverified because X” — rather than pretending. That honesty is by design.
Both skills are versioned with the CLI. After upgrading, testsprite agent status tells you if an installed skill file is stale or was hand-modified — it exits 1 when anything needs attention, so it’s CI-gateable. See Checking skill health.

​
Step 3: What to say to your agent

You don’t need to name commands or flags — the skills carry the mechanics. Describe the behavior you care about and ask for a verdict. Copy-paste starters: Your first test (right after setup):
The agent onboards: creates the project, authors a suite from what it finds in your code, smoke-runs the top flows, and hands you dashboard links. You’ve gone from “installed” to “first real test run” in one prompt. Verify a change (the everyday prompt):
The agent finds or creates the covering test, runs it against your deployed app, and reports the verdict. Target a specific behavior:
Drive the fix loop:
The phrase “run it to a verdict” is the useful one: it tells the agent a drafted-but-never-run plan doesn’t count. The verify skill already enforces this — at least one terminal verdict per shipped change — but saying it keeps expectations aligned.

​
Step 4: The loop, end to end

Here’s what a real session looks like once the skills are in place:
1

You ask for a feature

“Add a coupon-code field to checkout, and verify it with TestSprite.” The agent writes the code and gets it deployed somewhere reachable (a preview or staging URL) — the cloud runner tests deployed apps, not your working tree.
2

The agent creates and runs a test

It drafts a plan describing the behavior in user-intent terms, shows it to you, then:
A real browser exercises your live app. Exit 0 = passed, 1 = failed.
3

On failure, it reads the bundle — not the tea leaves

One self-consistent bundle: the failing step and neighbors, DOM snapshots rendered as text, the test source, a root-cause hypothesis, and a recommended fix target — all from the same run.
4

It fixes and reruns until green

Frontend reruns replay the saved script — free unless auto-heal repairs a drifted step. The confirmed pass is banked into your durable suite, so the next change reruns rather than recreates. Coverage compounds.

The Agent Loop

Why the loop is designed this way — self-consistent bundles, compounding coverage, and the machine-readable contract underneath.

​
Step 5: Keep the agent on track

A few conventions make the agent-driven flow reliable: Pin the project. The verify skill resolves which project to run against in priority order: the TESTSPRITE_PROJECT_ID environment variable → a projectId in .testsprite/config.json at the repo root → a name match from testsprite project list → asking you. The first two are conventions read by the skill (your agent), not by the CLI itself. Committing a pin removes the ambiguity:
.testsprite/config.json
Keep credentials in place. The skills preflight testsprite auth status and stop with a clear message if the CLI is missing or unauthenticated — they never install software or configure keys behind your back. If your agent reports either, re-run Step 1. Give it a deployed URL. The CLI tests reachable http(s):// deployments and rejects localhost. If your change only runs locally, the agent will hand off to the MCP Server (which owns the localhost tunnel) when it’s available, or honestly report the change as unverified — both are expected behavior, not failures. Heed the nudge. If you run test or auth commands in a repo where no verify skill is installed, the CLI prints a one-line reminder to stderr. Silence it with TESTSPRITE_NO_SKILL_WARNING=1 if you’re deliberately driving the CLI by hand. Know the cost model. Onboarding smoke-runs 2–3 tests, not the whole suite; full-suite runs are always your explicit call, with the credit cost stated up front. Frontend reruns of unchanged tests are free.

​
Where to Go Next

Coding Agent Integration

All eight agent targets, install flags, skill health checks, and the managed-section model for Codex

The Agent Loop

The concepts behind create → run → read → fix → rerun and why coverage compounds

Creating Tests

Plan files, code files, batch create, and dependency authoring — what your agent writes under the hood

Quickstart

The same loop, driven by a human at the terminal