> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.tester.army/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.tester.army/_mcp/server.

# Environments

Environments are reusable run targets for a web project. They let the same tests
run against production, PR previews, staging, QA, regional deployments, or any
other stable URL without rewriting test steps.

## Mental model

An environment answers: **where should this run happen?**

Selecting a saved environment controls three things:

* The URL TesterArmy opens for the run.
* The environment name shown in results and run history.
* Any [environment-specific credential overrides](/auth/credentials#environment-overrides) that should replace the default test account for that target.

This is different from passing `environment: "staging"` to an API or webhook.
That field only labels the result. It does not choose a saved target, URL, or
credential override.

## Environment types

Every web project has two built-in environments and can have any number of saved
static environments:

| Environment                               | Use it for                                          | URL behavior                                      |
| ----------------------------------------- | --------------------------------------------------- | ------------------------------------------------- |
| Production                                | Scheduled checks and manual production verification | Uses the project URL                              |
| PR Preview                                | Pull request and deployment preview testing         | Resolved per run from GitHub, Vercel, or webhooks |
| Staging, QA, or another saved environment | Stable non-production deployments                   | Uses the HTTPS URL saved in Project Settings      |

* `production` is built in and mirrors the project's main URL.
* `pr_preview` is built in for pull request preview runs. It has no static URL because each run supplies the preview URL.
* `static` environments are named targets you create, such as Staging, QA, or EU Staging, with a stable HTTPS URL.

Production and PR Preview are managed by TesterArmy. You can create and delete
static environments only.

## Recommended setup

1. Use the project URL for Production.
2. Add saved environments for stable non-production targets, such as Staging or QA.
3. Keep PR Preview built in; preview URLs are supplied by GitHub, Vercel, Coolify, or your deployment webhook.
4. Add credential overrides only when the same test account role needs different login details for non-production environments.

For a one-off URL that you do not want to save, pass `targetUrl` to an API or
webhook run instead.

## Manage environments in the dashboard

1. Open the project.
2. Go to **Project Settings -> Test environments**.
3. Edit the **Production** target URL if the main project URL changed.
4. Click **Add environment** for each saved non-production target.
5. Enter an environment name, such as `Staging`, and its HTTPS target URL.
6. Click **Save Changes**.
7. Use **Copy ID** when you need the environment ID for API or webhook runs.

Environment names must be unique within the project. Names that conflict with
built-in environments, such as Production or PR Preview, are reserved. URLs must
use HTTPS; bare domains such as `staging.example.com` are accepted and normalized
to `https://staging.example.com`.

## Run against an environment

From the dashboard, choose an environment from the run menu for a single test or
group run. If no environment is selected, the run targets Production.

For automation, pass the saved environment ID as `projectEnvironmentId`. This is
different from `environment: "staging"`: `environment` only labels the result,
while `projectEnvironmentId` selects the saved environment row, URL, and
credential overrides.

## Choose the right field

Use `projectEnvironmentId` for saved targets and `targetUrl` for one-off URLs:

| Field                  | What it does                                          | Use it when                                     |
| ---------------------- | ----------------------------------------------------- | ----------------------------------------------- |
| `projectEnvironmentId` | Selects a saved environment, its URL, and credentials | Running staging, QA, or another reusable target |
| `targetUrl`            | Supplies a URL only for this run                      | Testing an unsaved preview or temporary URL     |
| `environment`          | Labels the result as production, staging, or preview  | You are not using a saved environment ID        |

When `projectEnvironmentId` points to Production, do not include `targetUrl`.
When it points to PR Preview, include `targetUrl` because PR Preview has no saved
static URL. When it points to a static environment, TesterArmy uses the saved URL;
if you also send `targetUrl`, it must match the saved URL.

## Credential overrides

Credentials are defined once under **Project -> Test Accounts**. If the same role
uses different login details on staging or QA, edit the credential and add an
environment override. For example, the test can keep using the `admin`
credential, while TesterArmy automatically swaps in the Staging username and
password for runs targeting the Staging environment.

Production always uses the default credential. It does not support environment
credential overrides.

Credential overrides apply when the run selects an environment ID from the
dashboard or passes `projectEnvironmentId` through the API or a webhook.
Passing only `targetUrl` or `environment: "staging"` does not select saved
environment credentials.

## API and webhook usage

For API-managed projects, use the project environments endpoints to list,
create, and delete static environments. The returned `id` is the value to pass as
`projectEnvironmentId` when triggering a group run or group webhook.

For a full deployment-triggered staging example, see [Testing Staging Environment](/guides/testing-staging). For endpoint details, see the API Reference.