> For the complete documentation index, see [llms.txt](https://carec.gitbook.io/carec-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://carec.gitbook.io/carec-docs/documentation/simulation/headless-ci-and-regression-testing.md).

# Headless CI and Regression Testing

Most simulation tests should run without a GUI. Desktop visualization is for development and diagnosis; the release signal comes from repeatable headless execution.

| Tier             | Trigger                       | Scope                                       | Target duration         |
| ---------------- | ----------------------------- | ------------------------------------------- | ----------------------- |
| Lint/unit        | Every change                  | Formatting, static checks, pure logic       | Minutes                 |
| Smoke            | Every pull request            | Spawn, TF, controllers, sensors, stop chain | Minutes                 |
| Scenario subset  | Relevant pull requests        | Changed subsystem and critical safety cases | Under one CI job window |
| Full regression  | Nightly and release candidate | All supported worlds, seeds, and modes      | Scheduled               |
| Soak/performance | Scheduled                     | Long run, leaks, timing, resource use       | Extended                |

## CI requirements

* Build from a clean pinned image.
* Use explicit timeouts; a hang is a failure.
* Preserve logs and reports for every failure.
* Upload machine-readable results such as JUnit plus a concise HTML or Markdown summary.
* Mark nondeterministic tests as defects with an owner; do not normalize repeated retries.
* Quarantine only with an issue, reason, expiry date, and replacement coverage.
* Compare key metrics to an approved baseline and flag regressions.

## Merge gates

Changes affecting motion authority, safety, localization, planning, control, sensor health, or drive interfaces must pass the relevant safety scenario subset. A failing gate requires diagnosis and review, not a threshold increase without evidence.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://carec.gitbook.io/carec-docs/documentation/simulation/headless-ci-and-regression-testing.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.