Projects

List, inspect, create, and update the typed (frontend or backend) projects that hold your tests.

A project is the top-level container: a name, a type (frontend or backend), and named environments with the URLs TestSprite opens. Every test belongs to one project. Projects are shared with the Web Portal.

Listing and getting projects

testsprite project list
testsprite project get <project-id>

ID              NAME               TYPE       FROM     CREATED      DEFAULT ENV   ENVS
proj_8f0f6      Checkout App       frontend   cli      2026-05-10   Default       2

project get prints the same fields plus the default environment and environment count. --page-size <n> (1–100, default 25), --starting-token <token> (the nextToken printed under a full page) and --max-items <n> page through results.

Creating a project

testsprite project create --type frontend --name "Checkout App" --url https://app.example.com

Flag	Description
--type <frontend|backend>	Required.
--name <name>	Required.
--url <url>	Required for frontend unless --local. For backend, the base URL of the API under test. Public http(s), or a loopback http origin with an explicit port and no path (frontend only). Excludes --local
--local <port>	Local-only frontend project: stores http://localhost:<port>. Runs open a tunnel automatically
--skip-preflight	Skip the listener check before local creation
--username <user>, --password <pw> / --password-file <path>	Basic-auth credentials for the target URL (prefer the file in scripts)
--instruction <text>	Hint for frontend plan generation
--test-id-attributes <list>	DOM attributes the engine prefers as locators, highest priority first (data-element,data-testid)
--idempotency-key <token>	Pin a stable value for safe retries

testsprite project create --type frontend --name "Local App" --local 3000

For local apps, see Test an app on your machine. If project create --local exits 7 (local-origin-requires-v3), your account is not on the current project platform yet: create the project in the Portal or with --url.

A backend project can be created without --url, but on the V3 execution path its first run fails with exit 5 (no-target-resolvable) until you run testsprite project update <project-id> --url <url>. Check your routing with testsprite auth status.

Outside loopback, --url must be a public http(s) address; private IPs are refused, and the backend also checks DNS. Backend tests and test rerun cannot tunnel. See Common Issues if a URL is rejected.

Updating a project

testsprite project update <project-id> --name "Checkout App v2"

Pass at least one flag, or the command exits 5. It accepts the same flags as create (--name, --url, --local, --skip-preflight, --username, --password, --password-file, --instruction, --test-id-attributes, --idempotency-key) plus --clear-test-id-attributes, which removes the list so the engine falls back to data-testid; --test-id-attributes replaces it. --local is frontend only; some older projects cannot be switched and exit 7 (local-origin-requires-native-project), so create a new project with --local.

For separate deployment targets, use named environments (project env create, --env, --target-url), which also cover plan limits.

Backend test credentials

Inject auth into every backend test run, either a static credential or an auto-refreshed token:

testsprite project credential <project-id> --type "Bearer token" --credential-file ./token.txt

testsprite project auto-auth <project-id> --method refresh_token --inject bearer \
  --token-endpoint https://auth.example.com/oauth/token \
  --client-id my-client-id --client-secret-file ./client-secret.txt \
  --refresh-token-file ./refresh-token.txt

See the Command Reference for all flags.

Where to Go Next

Creating Tests

Author a frontend plan or backend code file

Running Tests

Trigger runs and poll for verdicts