Skip to main content
An environment is a named target within a project: the URL to test plus what a run needs there, such as sign-in settings and custom variables. Names are unique per project. Every run uses exactly one environment: the project’s Default (DEFAULT yes in project env list) unless you pass --env <name>. An unknown name fails and lists available names; it never falls back to Default. An environment whose origin is a loopback address opens a tunnel automatically; see Testing Local Apps.

​
Manage environments

On a legacy-engine project, project env exits 7 (environments-unsupported-on-v2); use project update <project-id> --url <url> instead.
  • create needs --name and exactly one of --url or --local. --url takes a public HTTP(S) URL or a loopback origin. Prefer --password-file; passwords are write-only.
  • With no stored account, --username and --password-file go together (exit 5 otherwise).
  • Repeatable --var KEY=VALUE sets custom variables for frontend runs; update merges by key. Values are shown in plain text, so do not store secrets in them. Keys start with a letter or underscore and use letters, digits, and underscores (up to 64 characters); up to 50 variables, 4096 bytes per value.
  • --clear-credentials removes the stored username and password and turns off account sign-in; it cannot be combined with --username, --password, or --password-file.
  • Delete is soft: the name can be reused and history keeps the old name. Change the Default before deleting it.

​
Sign-in modes

Sign-in is a property of the environment. Read or change it with project sign-in (without --env, the Default environment):
  • For manual, log in once in the Portal under Project, Settings, Environments, the environment name, Log in. The CLI warns when no session is captured. --session-ttl takes 1 to 2592000 seconds, or never. Selecting SSO needs a feature flag on your account; without it the command exits 13 (FEATURE_GATED).
  • SSO and OTP environments keep no username or password: project env update --username on one exits 6.
  • Loopback environments support only public and account. A temporary environment has no settable sign-in.

​
Plan limits

Free and Starter allow one environment per project (the Default counts), Standard 3, Pro and Enterprise unlimited; temporary environments do not count. Going over fails with exit 13 (FEATURE_GATED). On one environment, change the Default’s URL with project update <project-id> --url <url>, or use --target-url for a single run.

​
Choose an environment for a run

test run --all, test create, and test create-batch take --env too; without it they use Default. A backend test picks up an environment’s URL only if its code uses the environment URL placeholder; a URL written into the code stays as written. Check backend targets before using --env as a staging gate.

​
Ad-hoc targets and temporary environments

--target-url <url> runs a frontend test against an address that is not saved as an environment, such as a pull-request preview. --local <port> does the same for a port on your machine; the two cannot be combined. The temporary environment (see the diagram above) is removed when the run finishes. See Running Tests.
  • Sign-in comes from --env <name> if given (--env staging --local 5173 is allowed; the CLI notes it on stderr), else from the Default (same test account or one-time-code setup).
  • Results keep the run’s address as targetUrl (userinfo removed), even after the environment’s URL changes.
  • A recorded session is not cloned. A Default that signs in with a recorded session (manual or SSO) only works on its own origin. An ad-hoc target on another origin without --env is refused before any charge: exit 6, frontend-auth-target-origin-mismatch. Pass --env <name> for an environment that can sign in at the target, or save the address as an environment. A named environment is refused on another origin when it uses a recorded session, a one-time code, or a login-once step; a test-account environment is not.
  • Temporary environments are hidden from project env list and statusByEnvironment, and do not count toward the plan limit. They appear in test result --history.
Changing an environment’s URL keeps test IDs, code versions, and history, but does not rewrite hosts written into a test’s steps. A hard-coded host that no longer belongs to any of the project’s environments keeps pointing at the old site. Review steps with testsprite test get <test-id> and fix them with testsprite test plan put <test-id> --steps <file>.

​
Runs follow their own environment

If a test’s steps name one of the project’s environments (for example Navigate to https://staging.example.com) and you run it on another saved environment, TestSprite points those steps at the run’s environment at dispatch; the stored plan is unchanged. Tunnel runs and cross-origin target overrides repoint navigation the same way. A URL that belongs to none of the project’s environments is left as written.

​
Status per environment

test list and test get show each test’s latest result in the Default environment. JSON keeps status and adds statusByEnvironment (saved environments only); the text table has an ENV column. To read another environment:
A test with no result there shows ready. Schedules follow environments too; see Test Lists & Schedules. For every flag, see Command Reference.