roboticks-sdk 0.3.0

ROS2 test SDK for the Roboticks V&V platform — @confirms decorator, rclpy/rclcpp assertion helpers, MCAP capture, fault injection.

roboticks-sdk

ROS2 test SDK for the Roboticks V&V platform. pip install roboticks-sdk, drop @confirms("REQ-014") on your pytest test, and the platform builds the traceability matrix automatically.

---

What is this

A small, focused SDK that lets you tag ROS2 / pytest tests with the requirements they confirm. The annotations are emitted as standard JUnit XML <property> entries the Roboticks platform parses to build your traceability matrix and audit-ready evidence packs.

The SDK does not lock you in: without the Roboticks platform, your tests still run and the JUnit XML is still valid. The metadata is additive.

from roboticks import confirms, assert_topic_published

@confirms("REQ-014")
def test_estop_halts_within_100ms(ros_node):
    publish_estop()
    cmd = assert_topic_published(ros_node, "/cmd_vel", "geometry_msgs/Twist", within_seconds=0.1)
    assert cmd.linear.x == 0.0

Install

pip install roboticks-sdk                # decorators + reporters only
pip install 'roboticks[mcap]'        # + MCAP recording
pip install 'roboticks[dev]'         # + pytest, mypy, ruff for contributors

ROS2-specific helpers (roboticks.assertions, roboticks.fault_injection, roboticks.launch_testing_helpers) require a sourced ROS2 environment. Decorators and metadata work without ROS2.

What's in the box

Module	Purpose
roboticks.decorators	@confirms, @tags, @requires_sim, @deadline
roboticks.reporters	JUnit-with-confirms wire-format constants + metadata helpers
roboticks.pytest_plugin	Auto-loaded pytest plugin that injects metadata into JUnit XML
roboticks.assertions	assert_topic_published, assert_service_response, assert_action_result, assert_param_equals, assert_tf_transform
roboticks.fault_injection	drop_messages, delay_messages, corrupt_topic, kill_node
roboticks.mcap_capture	Per-test MCAP recording context manager
roboticks.launch_testing_helpers	Wrappers around launch_testing boilerplate

C++ counterpart (cpp/roboticks_cpp/) ships matching primitives:

#include <roboticks/confirms.hpp>

ROBOTICKS_CONFIRMS(SafetyTests_EmergencyStop, "REQ-014")
TEST(SafetyTests, EmergencyStop) { ... }

Wire format

The SDK emits a small, versioned extension to JUnit XML. See schemas/junit_with_confirms.xsd for the formal schema and the SDK contract doc for the prose explanation.

<testcase classname="tests.safety.test_estop" name="test_halts_in_100ms" time="0.234">
  <properties>
    <property name="roboticks.confirms" value="REQ-014"/>
    <property name="roboticks.tags" value="safety,estop"/>
    <property name="roboticks.mcap" value="s3://bucket/run-42/estop.mcap"/>
  </properties>
</testcase>

Schema version: 1. Locked per plan §23.1. Never break minor versions.

How it integrates with the platform

1. Install the SDK and the Roboticks GitHub App.
2. Annotate tests with @confirms("REQ-XXX").
3. Push to GitHub.
4. Your CI runs pytest --junitxml=results.xml.
5. The included roboticks-test-action (separate repo) uploads results.xml to the platform.
6. The platform parses <property name="roboticks.confirms"/> entries and builds the traceability matrix.
7. Generate evidence packs from the matrix at audit time.

Standards reference

The SDK is designed for V&V workflows targeted at:

• EU Machinery Regulation 2023/1230 (in force 2027)
• ISO 10218-1:2025 / ISO 10218-2:2025 (industrial robot safety)
• ISO 13849-1 (safety-related control system parts)
• IEC 61508 (functional safety, foundational)
• ISO 26262 / SOTIF (automotive; complement, don't compete with qualified tools)
• DO-178C / DO-330 (airborne software; we feed your qualified toolchain, we are not qualified)

We assemble evidence — we don't certify. See the Roboticks platform docs for the full positioning.

Repository layout

src/roboticks/             — Python SDK (this PyPI package)
cpp/roboticks_cpp/         — C++ counterpart (ament_cmake header-only)
schemas/                   — JSON Schema + XSD wire contracts
examples/                  — Sample tests + requirements files
docs/                      — Sphinx source (publishes to docs.roboticks.io/sdk)
legacy/                    — Frozen pre-pivot C++ runtime (tag v0.x-legacy-fleet-runtime)

Development

pip install -e '.[dev]'
ruff check src tests
mypy src/roboticks
pytest tests --cov=roboticks

Coverage floor: 90% on assertion helpers, 80% overall.

License

MIT — see LICENSE.

Status

Phase 8 alpha. Wire format is stable (locked at v1); some helpers are minimum-viable and will be expanded as the platform reaches GA. See the pivot plan for the full roadmap.