Skip to main content

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.

​
MCAP capture

MCAP is the open-source successor to ROS bag files. Roboticks’s mcap_capture context manager records the topics you care about, only during the test, and uploads the resulting .mcap to the platform automatically when the test fails (or always, if you ask).
Per-test recording, not session-wide. A failing nightly suite produces one MCAP per failing test — no 30-GB monolith to scrub through.

​
Install

MCAP is an optional extra to keep the SDK install light for users who don’t record: 
pip install 'roboticks[mcap]'
This pulls in mcap and mcap-ros2-support. Without the extra, importing the context manager raises a clear error pointing at this install line.

​
The context manager

from roboticks import mcap_capture

with mcap_capture(
    topics=["/cmd_vel", "/scan", "/odom"],   # allowlist
    path="captures/test_estop.mcap",         # local path
    upload_on="failure",                     # "failure" | "always" | "never"
) as bag:
    run_the_scenario()
Parameters:
ParameterTypeDefaultBehaviour
topicslist[str]["*"]Topic allowlist. Wildcards permitted. Subscribe-on-first-seen.
pathstr | Pathauto, under test_results/Where to write the MCAP locally.
upload_onLiteral["failure", "always", "never"]"failure"When the runner uploads the bag to platform storage.
compressionLiteral["zstd", "lz4", "none"]"zstd"Per-chunk compression.
Full reference: SDK MCAP capture.

​
Use the allowlist

The allowlist is the difference between a 3 MB bag and a 3 GB one. Subscribe-to-all is rarely what you want; most safety-relevant tests only need 2–5 topics. 
with mcap_capture(topics=["/cmd_vel", "/safety/*"]):
    ...
Wildcards follow rosbag2 semantics: /safety/* matches every immediate child of /safety; ** matches recursively.

​
A typical safety test

import pytest
from roboticks import confirms, deadline, mcap_capture
from roboticks.assertions import assert_topic_published
from std_msgs.msg import Bool

@confirms("REQ-014")
@deadline(milliseconds=200)
def test_estop_with_recording(ros_context, robot_node):
    with mcap_capture(
        topics=["/cmd_vel", "/safety/estop_engaged", "/safety/heartbeat"],
        upload_on="failure",
    ):
        robot_node.command_velocity(1.0)
        robot_node.trigger_estop()
        assert_topic_published(
            "/safety/estop_engaged", Bool,
            within=0.1, predicate=lambda m: m.data is True,
        )
When this test fails, the platform shows the MCAP under the test-run detail page. When it passes, no upload, no storage charge.

​
How MCAPs surface in the UI

Each failing test in the run detail UI gets:
  1. A download link to the raw .mcap.
  2. A Foxglove deep-link that opens the bag in Foxglove Studio with the relevant topics pre-selected.
  3. An LLM triage block that references timestamps inside the bag (“at t=4.2 s, /safety/estop_engaged is still false; expected true per @deadline(200)”).

​
Storage cost

MCAPs land in S3 standard for 90 days, then Glacier Deep Archive. See pricing.
  • Free tier: MCAPs auto-expire after 30 days.
  • Team / Enterprise: 0.05/GB−monthhot,0.05 / GB-month hot, 0.005 / GB-month archive.
A typical safety test produces 200 KB to 5 MB depending on topic rate. A nightly suite of 1,000 tests with 5% failure rate (upload_on="failure") and average 2 MB per failure is ~100 MB / night, or ~3 GB / month — well under $1 / month at hot pricing.
Set upload_on="always" on the handful of tests that always benefit from a bag (interactive perception tuning, regression hunts). Leave the rest on "failure".

​
Multi-test sessions

For session-scoped recording (one bag per session, not per test) use a session-level pytest fixture instead. That’s an explicit choice — the default is per-test for noise isolation. 
@pytest.fixture(scope="session")
def session_bag():
    with mcap_capture(path="captures/full_session.mcap", upload_on="always") as bag:
        yield bag

​
Interaction with fault injection

mcap_capture records the post-fault topic — exactly what the system under test observed. Pair it with delay_messages or drop_messages to capture the degraded signal an auditor will want to see: 
with mcap_capture(topics=["/scan", "/cmd_vel"]):
    with delay_messages("/scan", ms=300):
        ...

​
Next

MCAP API reference

Full parameter list and edge cases.

Fault injection

Often paired with MCAP for failure forensics.

LLM triage

How the platform reads your MCAP to explain failures.

Pricing

Storage costs in detail.