Metadata-Version: 2.4
Name: roboticks-sdk
Version: 0.3.0
Summary: ROS2 test SDK for the Roboticks V&V platform — @confirms decorator, rclpy/rclcpp assertion helpers, MCAP capture, fault injection.
Project-URL: Homepage, https://roboticks.io
Project-URL: Documentation, https://docs.roboticks.io/sdk
Project-URL: Repository, https://github.com/roboticks-ai/roboticks-sdk
Project-URL: Wire contract, https://docs.roboticks.io/sdk/confirms-contract
Author-email: Roboticks <support@roboticks.io>
License-Expression: MIT
License-File: LICENSE
Keywords: pytest,rclpy,robotics,ros2,testing,v&v,validation,verification
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Pytest
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: pytest-cov>=4.1; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: types-pyyaml; extra == 'dev'
Provides-Extra: docs
Requires-Dist: myst-parser>=2.0; extra == 'docs'
Requires-Dist: sphinx-rtd-theme>=2.0; extra == 'docs'
Requires-Dist: sphinx>=7.0; extra == 'docs'
Provides-Extra: mcap
Requires-Dist: mcap-ros2-support>=0.5.0; extra == 'mcap'
Requires-Dist: mcap>=1.1.0; extra == 'mcap'
Description-Content-Type: text/markdown

# roboticks-sdk

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

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Schema version](https://img.shields.io/badge/wire--schema-v1-blue.svg)](schemas/junit_with_confirms.xsd)

---

## 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.

```python
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

```bash
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:

```cpp
#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`](schemas/junit_with_confirms.xsd)
for the formal schema and the [SDK contract doc](https://docs.roboticks.io/sdk/confirms-contract)
for the prose explanation.

```xml
<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](https://github.com/roboticks-ai/roboticks/blob/pivot/roboticks_pivot_plan.md). 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](https://docs.roboticks.io/) 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

```bash
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](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](https://github.com/roboticks-ai/roboticks/blob/pivot/roboticks_pivot_plan.md)
for the full roadmap.
