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

# Browser runs

> What a run is, how one starts, and the limits it runs under.

A run is one execution of one test in one real Chromium browser, against one
address.

## Ways to start one

<CardGroup cols={2}>
  <Card title="Chat" icon="message-square">
    Describe a test in the project's chat. The planner writes the steps, then
    they execute.
  </Card>

  <Card title="Replay a saved test" icon="repeat">
    Run a procedure. No planning: the recorded steps execute directly.
  </Card>

  <Card title="Schedule" icon="calendar">
    A cron expression on a procedure, dispatched server-side. **Run now** is
    available from the same screen.
  </Card>

  <Card title="API or CLI" icon="terminal">
    `POST /api/runs/trigger`, or `testorim run`. Both accept a saved
    procedure or an ad-hoc description.
  </Card>
</CardGroup>

A pull request in a [linked GitHub repository](/integrations/github) also
triggers runs automatically.

## What a run does

1. Checks the workspace's allowance and concurrency limit.
2. Creates the run record and starts a liveness heartbeat.
3. Plans the steps (chat and ad-hoc runs only).
4. Launches a browser at the base address, applying any environment overrides
   (alternate base URL, extra headers, cookies, timezone, locale,
   geolocation), and any saved login state.
5. Blocks every request the page makes to a private or internal host.
6. Streams screenshots while the steps execute.
7. Settles the page, takes a final screenshot, scans for accessibility issues
   and collects performance metrics.
8. Writes the report, fires alerts, and comments on the pull request if one is
   linked.

## Overriding the address

Every trigger path accepts a base-URL override, so the same test can point at a
PR preview without editing it:

```bash theme={null}
testorim run <procedure-id> --base-url https://preview-42.staging.example.com
```

Named [environments](/projects/environments) do the same thing plus headers and
cookies, and are the better choice for anything you run repeatedly.

## Limits

| Limit                 | Behaviour                                                                                                |
| --------------------- | -------------------------------------------------------------------------------------------------------- |
| **Time limit**        | 5 to 120 minutes, 10 by default. Step timeouts and cleanup thresholds scale with it.                     |
| **Concurrency**       | Set by your plan. Runs over the limit are refused with a retryable error rather than queued forever.     |
| **Monthly allowance** | Runs and browser minutes per billing period. Exhausting either refuses new runs until the period resets. |
| **Plan gating**       | Form fuzzing and the role probe require a paid plan.                                                     |

## Cancelling

Cancel from the chat, the run page, or the active-runs toast. Cancelling marks
the run and tears down the browser within seconds. The remaining steps are
marked skipped and any pending prompt is released.

`POST /api/runs/batch/{batchId}/cancel` cancels every run in a batch at once,
which is how you stop a fuzz batch.

## When a run dies

A live run pings a heartbeat every 60 seconds. A sweeper runs every 5 minutes
and cancels a run whose heartbeat is more than 3 minutes old, or whose age has
passed its time limit. A separate safety net kills orphaned browser processes.

The heartbeat is what lets a legitimate 30-minute scrape survive while a
crashed run is reclaimed quickly.


## Related topics

- [Browser failures](/troubleshooting/browser-failures.md)
- [Run and inspect a test](/getting-started/run-and-inspect.md)
- [Core capabilities](/introduction/core-capabilities.md)
- [What is Testorim](/index.md)
- [Environments](/projects/environments.md)