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 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 |
