Hardware testing

A plugin’s tests run on four surfaces, in order of cost and fidelity. All three SDKs ship a test harness: ados.sdk.testing in Python, ados_sdk::testing in Rust, and @altnautica/plugin-sdk/harness in TypeScript.

1. Agent-side unit tests with a mock backend

The cheapest pass. Driver plugins ship a mock backend that the driver constructor accepts in place of the real device: the FLIR Lepton plugin ships MockUvcBackend, and the MAVLink Gimbal v2 plugin ships a mock router. For a Python agent half, ados.sdk.testing adds PluginTestHarness, FakeVisionEngine and load_fixture. PluginTestHarness wires an in-process plugin context to a fake IPC client, so lifecycle hooks run under pytest without the plugin host, sockets or subprocesses. Grant capabilities explicitly and assert against captured events.

import pytest

@pytest.mark.asyncio
async def test_open_yields_correct_capabilities():
    backend = MockUvcBackend(width=160, height=120)
    driver = LeptonUvcDriver(backend)
    candidate = (await driver.discover())[0]
    session = await driver.open(candidate, {})
    caps = driver.capabilities(session)
    assert caps.width == 160
    assert caps.radiometric is True

Run the suite through the agent CLI, which validates the manifest first and sets the harness environment:

ados plugin test ./my-plugin
ados plugin test ./my-plugin --tests-dir tests -k capabilities --json

For a Rust agent half, ados_sdk::testing::FakeVisionEngine emits synthetic frames through the same callback a plugin registers with ctx.vision.subscribe_frames, and captures the detections the plugin publishes:

use ados_sdk::testing::FakeVisionEngine;
use ados_protocol::framebus::FrameFormat;

#[tokio::test]
async fn detects_a_solid_frame() {
    let mut engine = FakeVisionEngine::new("uvc-0", 64, 48, FrameFormat::Rgb24);
    engine.push_solid(0x80);
    engine.deliver_all();
    // assert against the captured detection sink
}

See the FakeVisionEngine tests in crates/ados-sdk/src/testing/mod.rs for a worked example.

2. The plugin harness, GCS side

@altnautica/plugin-sdk/harness mounts your plugin against an in-memory transport, captures every RPC, and lets you inject telemetry, events, config changes and theme updates without running Mission Control.

import { createPluginHarness } from "@altnautica/plugin-sdk/harness";

const harness = createPluginHarness({
  grantedCapabilities: ["telemetry.subscribe.battery"],
  mount: async (ctx) => {
    await ctx.telemetry.subscribe("battery", store.ingest);
  },
});
await harness.start();
harness.pushTelemetry("battery", mockSample);
expect(harness.notifications).toMatchObject([{ severity: "warning" }]);
await harness.teardown();

The full harness reference is on TypeScript SDK.

3. SITL (software in the loop)

ArduPilot SITL covers the flight-controller side: arming, modes, missions, parameters, mount commands and ROI. The agent binds TCP 5760 itself, so SITL on the same host at 5760 collides. Run SITL (sim_vehicle.py) on another machine, or expose it on another port, then point the agent at it:

mavlink:
  source: tcp
  serial_port: "tcp:192.168.1.50:5770"

SITL does not simulate cameras, LiDARs, payloads or vendor serial protocols. For those, use the mock backend.

SITL tests that arm, take off or upload missions use the same commands as a real vehicle. Read Safety before pointing a test at real hardware.

4. Hardware in the loop on a bench rig

The full pass: a real board with the agent installed, the real device on USB or serial, and your plugin packed and installed with ados plugin install <archive>. Bench testing closes the loop on accuracy, timing jitter, hotplug behaviour and vendor-binary integration. Run it before you tag a release. A good bench session captures:

The plugin’s log while you exercise the device: ados plugin logs <id> --follow. The file lives at /var/log/ados/plugins/<id-with-dashes>-<hash>.log; find the unit with systemctl list-units 'ados-plugin-*'.
A telemetry log over the test window.
A photo or short video of the rig and the device under test.

Attach them to your release notes.

What the reference plugins ship

Plugin	Mock backend	Harness	SITL	Bench
FLIR Lepton USB UVC	`MockUvcBackend`	yes	n/a	not published (no UVC backend)
MAVLink Gimbal v2	mock router	yes	no (mock router)	before each release tag

Next steps

Linting

Analyze the packed archive.

Python SDK

The ados.sdk.testing reference.

Start here

Tutorials

Reference

SDKs

Deep dives

Test and distribute

1. Agent-side unit tests with a mock backend

2. The plugin harness, GCS side

3. SITL (software in the loop)

4. Hardware in the loop on a bench rig

What the reference plugins ship

Next steps

Linting

Python SDK

​1. Agent-side unit tests with a mock backend

​2. The plugin harness, GCS side

​3. SITL (software in the loop)

​4. Hardware in the loop on a bench rig

​What the reference plugins ship

​Next steps

Linting

Python SDK

1. Agent-side unit tests with a mock backend

2. The plugin harness, GCS side

3. SITL (software in the loop)

4. Hardware in the loop on a bench rig

What the reference plugins ship

Next steps