What Is the Role of openlogi-fixture in Testing Device Behavior?

The openlogi-fixture crate supplies host-free fixture schemas, synthetic device identities, and replay-ready cassettes that enable deterministic, hardware-independent testing of HID++ device interactions.

The openlogi-fixture crate acts as the simulation backbone for the AprilNEA/OpenLogi repository. By compiling static JSON assets directly into the binary and exposing deterministic generation APIs, it provides the synthetic data required to validate complex HID++ protocol logic without requiring physical hardware connected to the host.

Core Responsibilities of openlogi-fixture

Embedding Static Fixture Assets

At the heart of the crate, crates/openlogi-fixture/src/lib.rs embeds canonical device descriptions using include_str! macros. These assets—typically profile.json and manifest.json—describe a synthetic device’s capabilities, identity, and configuration topology. By compiling these files into the crate at build time, the test suite guarantees that fixture data remains version-locked with the codebase and available in offline environments.

Generating Deterministic Manifests

The generate.rs module transforms raw JSON assets into fully validated FixtureManifest structures. This process, orchestrated alongside manifest.rs, performs structural checks such as duplicate case detection and schema conformance. The resulting manifest serves as the single source of truth for device topology during test execution, ensuring that every test run operates against an identical device description.

Validating Fixture Integrity

Before any fixture enters the test pipeline, crates/openlogi-fixture/src/verify.rs executes a multi-stage validation pipeline. This verification layer wraps failures in a strongly-typed FixtureError, pinpointing the specific validation stage—such as schema mismatch or consistency violation—that caused the rejection. This strict validation prevents malformed fixtures from propagating into integration tests, where they could trigger misleading failures in device-behavior assertions.

Isolating Tests from Physical Hardware

Synthetic Device Profiles

By consuming fixtures instead of scanning for real HID devices, the OpenLogi test suite achieves complete host independence. The DeviceProfile structures exported by openlogi-fixture encode synthetic identities that mimic real peripherals, allowing the ReplayBackend to simulate device responses without USB or Bluetooth connectivity.

Replay-Ready Cassettes

The crate re-exports HidCassette objects that pair with device profiles to drive record-and-replay testing. Tests found in openlogi-hid/src/recording/cassette/tests.rs import openlogi_fixture::{HidCassette, DeviceProfile} to instantiate pre-recorded interaction sequences. These cassettes capture raw HID traffic and replay it deterministically, eliminating flaky behavior caused by timing variations or hardware-specific quirks.

Practical Usage in Device Testing

To utilize the fixture in a test scenario, developers invoke the crate’s generation APIs to obtain a verified manifest, profile, and cassette tuple:

use openlogi_fixture::{HidCassette, DeviceProfile, FixtureManifest};

/// Create a synthetic device fixture for testing.
fn create_fixture() -> (FixtureManifest, DeviceProfile, HidCassette) {
    // The crate ships with built-in JSON assets (profile & manifest) compiled in.
    // These are turned into a verified manifest at runtime.
    openlogi_fixture::case_fixture()
}

The resulting objects integrate directly with the ReplayBackend to simulate hardware interactions:

// Using the fixture with the ReplayBackend (found in openlogi-device tests)
let (manifest, profile, cassette) = create_fixture();
let backend = ReplayBackend::new(manifest.topology, vec![cassette])
    .expect("fixture backend should be valid");

// Now the test can issue HID++ commands against `backend` without any real hardware.
let dpi = get_dpi(&backend, &profile.route).await.unwrap();
assert_eq!(dpi, expected_value);

Summary

• openlogi-fixture embeds static JSON assets via include_str! in src/lib.rs, ensuring fixtures are always available offline.
• The generate.rs and manifest.rs modules produce deterministic, schema-validated FixtureManifest instances.
• verify.rs enforces multi-stage integrity checks, surfacing FixtureError for any malformed data.
• The crate exports HidCassette and DeviceProfile types that power the ReplayBackend, enabling deterministic replay of HID traffic without physical devices.
• By isolating the test suite from hardware dependencies, openlogi-fixture guarantees consistent, reproducible validation of HID++ protocol behavior.

Frequently Asked Questions

What is openlogi-fixture?

openlogi-fixture is a dedicated test-support crate within the AprilNEA/OpenLogi repository. It provides synthetic device descriptions, validation logic, and replay cassettes that enable the OpenLogi test suite to simulate HID++ device behavior without requiring physical peripherals.

How does openlogi-fixture enable offline testing?

The crate compiles static JSON assets—such as profile.json and manifest.json—directly into the binary using include_str! macros. Because all device data is embedded at build time, tests can generate FixtureManifest and HidCassette objects and execute against the ReplayBackend entirely offline, with no USB or Bluetooth hardware present.

What validation does openlogi-fixture perform?

According to crates/openlogi-fixture/src/verify.rs, the crate runs a multi-stage verification pipeline that checks schema conformance, duplicate case detection, and structural consistency. Failures are encapsulated in FixtureError variants that indicate the specific validation stage, preventing invalid fixtures from reaching integration tests.

How do I use openlogi-fixture in my own tests?

Import the crate and call openlogi_fixture::case_fixture() to obtain a tuple of (FixtureManifest, DeviceProfile, HidCassette). Pass the manifest’s topology and the cassette vector to ReplayBackend::new() to create a simulated device backend. You can then issue HID++ commands against this backend and assert on the responses as if communicating with real hardware.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}