> ## Documentation Index
> Fetch the complete documentation index at: https://docs.empirical.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Concurrency Limits

> Control how concurrent test runs are handled within a project

Concurrency limits let you control what happens when multiple test runs are triggered at the same time.
This is configured with two settings: **scope** and **behavior**.

## Scope

The scope setting (`test_run_concurrency_limit`) defines the boundary within which only one run can be active at a time.

| Value                | What it means                                         |
| -------------------- | ----------------------------------------------------- |
| `none`               | No limits — unlimited concurrent runs (default)       |
| `project`            | Max 1 active run per project, across all environments |
| `environment`        | Max 1 active run per environment                      |
| `branch_environment` | Max 1 active run per branch + environment combination |

## Behavior

The behavior setting (`test_run_concurrency_behavior`) defines what happens when a new run is triggered
while the concurrency limit is reached.

| Value             | What it means                                                        |
| ----------------- | -------------------------------------------------------------------- |
| `cancel_previous` | Cancel the in-progress run and start the new run immediately         |
| `queue_new`       | Keep the existing run, queue the new run until capacity is available |

## How queueing works

When `queue_new` is enabled:

* Only one run can be active (running) per scope at a time
* If a new run is triggered while one is already running, it enters a **Pending** state
* If another run is triggered while one is already pending, the older pending run is **cancelled** and replaced by the newer one
* When the active run finishes, the most recent pending run is dispatched automatically

This "keep latest" strategy ensures you never waste resources running stale test runs.

## Examples

| Scope                | Behavior          | What happens                                              |
| -------------------- | ----------------- | --------------------------------------------------------- |
| `none`               | —                 | All runs execute immediately, no limits                   |
| `project`            | `cancel_previous` | New run cancels any running run in the project            |
| `environment`        | `queue_new`       | New run waits for the current run in the same environment |
| `branch_environment` | `cancel_previous` | New run cancels the running run on the same branch + env  |