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

# Testing Overview

> How Roboticks turns ROS2 tests into traceable verification evidence. Frameworks, the V-model diagonals, and the path from a green CI run to an audit-ready evidence pack.

# Testing in Roboticks

Roboticks treats every test as a **verification artifact**. A test is not just a green or red dot — it is the bottom diagonal of the V-model, the thing that proves a requirement on the left is implemented by the code on the right.

<Info>
  **The job is traceability.** Roboticks doesn't replace pytest, gtest, or launch\_testing. It records what each test *confirms*, ties that to a requirement, and packages the result for an auditor.
</Info>

## The V-model diagonals

The V-model splits product development into two arms: requirements decomposition on the left, integration and verification on the right. The diagonals connecting the two are the only thing a regulator cares about.

```mermaid theme={null}
%%{init: {"theme": "neutral", "themeVariables": {"primaryColor": "#4040ff"}} }%%
flowchart LR
    subgraph Left["Decomposition"]
        SR["System requirement"] --> HR["Hardware / sub-system"]
        HR --> UR["Unit-level requirement"]
    end
    subgraph Right["Verification"]
        UT["Unit test"] --> IT["Integration test"]
        IT --> ST["System test"]
    end
    UR -.->|@confirms| UT
    HR -.->|@confirms| IT
    SR -.->|@confirms| ST
```

Roboticks owns the dotted arrows. Every passing test on the right closes a diagonal back to a requirement on the left.

## Supported frameworks

| Framework           | Language | Use for                                                                                |
| ------------------- | -------- | -------------------------------------------------------------------------------------- |
| **pytest**          | Python   | Unit + integration tests using rclpy assertion helpers, fault injection, MCAP capture  |
| **gtest**           | C++      | Unit + integration tests inside ament\_cmake packages with the `roboticks_cpp` library |
| **launch\_testing** | Python   | System tests that bring up multiple nodes and assert on their interactions             |

All three emit JUnit XML extended with `@confirms` metadata. See [Wire contract](/testing/wire-contract) for the exact shape.

## How a test becomes a traceability link

1. You import `roboticks` and decorate a test with `@confirms("REQ-014")`.
2. The pytest11 plugin (registered automatically by the entry point) intercepts the decoration and writes it into the JUnit XML as a `<property name="roboticks.confirms" value="REQ-014"/>`.
3. The runner uploads the JUnit XML to the Roboticks platform.
4. The traceability engine parses the property, looks up `REQ-014`, and records: **this test, this commit, this result, confirms this requirement**.
5. The [matrix UI](/traceability/matrix) and the next [evidence pack](/evidence/generation) reflect the link.

The same shape works for C++ via [`ROBOTICKS_CONFIRMS`](/sdk/cpp-reference) and for launch\_testing via the standard pytest mechanism.

## Where tests run

<CardGroup cols={2}>
  <Card title="Locally" icon="laptop-code" href="/testing/local-vs-cloud">
    Run `pytest` or `colcon test` as you always have. The SDK still emits `@confirms`; you can upload the JUnit XML afterwards or trigger a cloud run with the CLI.
  </Card>

  <Card title="Hosted runners" icon="cloud" href="/runners/overview">
    Fargate Spot for headless ROS2; G4dn.xlarge Spot Fleet for Gazebo Harmonic and Webots GPU jobs. Sim-minute metered.
  </Card>

  <Card title="Self-hosted runners" icon="server" href="/runners/installation">
    Run the [`roboticks-runner`](https://github.com/roboticks-io/roboticks-runner) Go binary on your own hardware. Compute is always free of charge.
  </Card>

  <Card title="Air-gapped" icon="shield-halved" href="/runners/air-gapped">
    Enterprise mode for regulated networks. Same wire contract, no outbound calls.
  </Card>
</CardGroup>

## What you get

* A **Check Run** on every PR with the requirement-coverage delta.
* A live **traceability matrix** at `app.roboticks.io` for the head of every branch.
* An **evidence pack** per release: PDF + ReqIF + ZIP with a tamper-evident hash chain.
* An **LLM triage** verdict on each failing test, citing logs, MCAPs, and the confirming requirement.

## Where to start

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Install the GitHub App, mark one test, see the matrix update.
  </Card>

  <Card title="Write tests in pytest" icon="python" href="/testing/writing-tests-pytest">
    `@confirms`, rclpy assertion helpers, conftest patterns.
  </Card>

  <Card title="Write tests in C++" icon="code" href="/testing/writing-tests-cpp">
    gtest with the `ROBOTICKS_CONFIRMS` macro and `roboticks_cpp`.
  </Card>

  <Card title="Wire contract" icon="file-code" href="/testing/wire-contract">
    The JUnit-with-confirms schema, versioning, and forward-compat rules.
  </Card>
</CardGroup>