Testing with cargo test

The crate is designed so that your HIL suite is just ordinary Rust integration tests. These are files under tests/, run by cargo test, that live in the same repository as your firmware.

Structure

Point tests at a box with the LAGER_BOX_HOST environment variable and construct the client with LagerBox::from_env():

// tests/power.rs
use lager::LagerBox;

#[test]
fn dut_draws_less_than_100ma_idle() -> lager::Result<()> {
    let lager = LagerBox::from_env()?;
    let supply = lager.supply("DUT_POWER");

    supply.set_voltage(3.3)?;
    supply.enable()?;
    let current = supply.state()?.current.expect("supply reports current");
    assert!(current < 0.1, "idle draw {current} A");
    supply.disable()
}

LAGER_BOX_HOST=192.168.1.42 cargo test

Group tests by net or by DUT feature — one file per concern (boot.rs, power.rs, sensors.rs) keeps cargo test <name> filtering useful.

Parallel tests and instrument safety

cargo test runs tests on multiple threads by default. That is safe at the instrument level. The box serializes access per physical instrument: every net command runs under a per-device lock in the box’s single-owner hardware service. Because of that per-device lock, parallel tests can never interleave I/O on one instrument. Examples are a LabJack shared across GPIO/ADC/SPI nets, or a Keithley shared by supply and battery roles. Tests sharing a net still observe each other’s state changes (one test’s disable() is visible to another test reading the same supply). Either partition nets across tests, or serialize:

cargo test -- --test-threads=1

Timeouts

Timeout budgets mirror the Lager CLI. Quick commands use 10 s. Some operations block on the box for a caller-controlled duration: the watt and energy integration windows, and wait_for_level. Those operations widen or drop the client timeout automatically, so a healthy long measurement is never aborted mid-flight.

Hermetic tests vs. hardware tests

Mark tests that always need real hardware with #[ignore]. A plain cargo test then stays green on a laptop with no box, or in a PR check:

#[test]
#[ignore = "requires a Lager box"]
fn flash_and_boot() -> lager::Result<()> {
    // ...
}

Then opt in explicitly where a box is available:

LAGER_BOX_HOST=192.168.1.42 cargo test -- --ignored

This is the convention that the crate itself uses. Its own suite is hermetic, and cargo test runs against a mock box. Its hardware smoke tests run with cargo test --test hardware -- --ignored.

CI

A minimal GitHub Actions job, assuming the runner can reach the box (e.g. a self-hosted runner on the lab network or a Tailscale-connected runner):

jobs:
  hil:
    runs-on: [self-hosted, lab]
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
      - name: Run HIL suite
        env:
          LAGER_BOX_HOST: ${{ vars.LAGER_BOX_HOST }}
          # Only needed for boxes behind an authenticating gateway:
          LAGER_GATEWAY_TOKEN: ${{ secrets.LAGER_GATEWAY_TOKEN }}
        run: cargo test -- --ignored

For gateway-fronted boxes, see Authentication for how the token is attached and refreshed.

A harness that runs against any box

The crate’s own hardware suite uses a pattern worth copying. Every test is #[ignore]d, so cargo test stays hermetic. Each test reads its net name from an environment variable, and skips with a note when that variable is unset. The same suite then runs against whatever nets a given bench configures.

#![cfg(feature = "blocking")]

use lager::{LagerBox, Level};

fn lager() -> LagerBox {
    LagerBox::from_env().expect("set LAGER_BOX_HOST to a reachable box")
}

/// The net name in `var`, or None with a printed skip note.
fn net_from_env(var: &str) -> Option<String> {
    match std::env::var(var) {
        Ok(name) if !name.is_empty() => Some(name),
        _ => {
            eprintln!("skipping: set {var} to a configured net name to run this test");
            None
        }
    }
}

#[test]
#[ignore = "requires a live box + LAGER_TEST_GPIO_NET"]
fn gpio_toggles() {
    let Some(name) = net_from_env("LAGER_TEST_GPIO_NET") else { return };
    let lager = lager();
    let pin = lager.gpio(&name);

    pin.output(Level::High).unwrap();
    assert_eq!(pin.input().unwrap(), Level::High);
    pin.output(Level::Low).unwrap();
}

Run it by opting in:

LAGER_BOX_HOST=192.168.1.42 \
LAGER_TEST_GPIO_NET=gpio1 \
LAGER_TEST_SUPPLY_NET=supply1 \
  cargo test --test hardware -- --ignored --nocapture

The environment variables are a convention, not a crate feature — name them whatever suits your bench. What matters is that a test which cannot run says so and passes, rather than failing on a bench that simply lacks that instrument.

Skipping on an older box

A box too old for an endpoint answers with Error::UnsupportedByBox, which is a better signal than a panic when a fleet is mid-upgrade.

match lager.usb_devices() {
    Ok(devices) => assert!(!devices.is_empty()),
    Err(lager::Error::UnsupportedByBox { message }) => {
        eprintln!("skipping: {message}");
    }
    Err(e) => panic!("{e}"),
}

Teardown that actually runs

A test that panics mid-way skips everything after the panic, which on a bench means leaving a supply enabled or a firewall rule in place. Put the restore on a path that survives a failure.

fn with_power<T>(lager: &lager::LagerBox, body: impl FnOnce() -> T) -> lager::Result<T> {
    let supply = lager.supply("supply1");
    supply.set_voltage(3.3)?;
    supply.enable()?;

    let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(body));

    supply.disable()?;             // runs even if `body` panicked
    Ok(result.unwrap_or_else(|e| std::panic::resume_unwind(e)))
}

Reserve the whole box for the duration when a suite must not be interleaved with another job:

let _guard = lager.lock_guard("ci-job-4711")?;

BoxLockGuard releases on drop, including during a panic unwind.

Verifying against real hardware

Some behaviors only show up on a bench, and are worth knowing before you write an assertion around them:

A supply’s measurements can be None while its output is disabled, depending on the instrument. Assert on enabled and setpoints when the output is off.
state() returning Ok does not mean the instrument answered — check the error field.
An i2c.scan() hit does not guarantee a subsequent read will ACK.
erase() drops the debugger connection; reconnect before reading memory.

Getting Started

Development

Power & Simulation

Measurement

I/O & Communication

Utilities

Guides

Testing with cargo test

Structure

Parallel tests and instrument safety

Timeouts

Hermetic tests vs. hardware tests

CI

A harness that runs against any box

Skipping on an older box

Teardown that actually runs

Verifying against real hardware

​Structure

​Parallel tests and instrument safety

​Timeouts

​Hermetic tests vs. hardware tests

​CI

​A harness that runs against any box

​Skipping on an older box

​Teardown that actually runs

​Verifying against real hardware

Structure

Parallel tests and instrument safety

Timeouts

Hermetic tests vs. hardware tests

CI

A harness that runs against any box

Skipping on an older box

Teardown that actually runs

Verifying against real hardware