# OpenLogi Agent Mock: Testing Without Hardware Using `openlogi-agent-mock`

> Test Logitech HID++ interfaces without hardware using openlogi-agent-mock. Run the mock to serve a scripted device inventory over IPC and streamline your development workflow.

- Repository: [Xuan Zhang/OpenLogi](https://github.com/AprilNEA/OpenLogi)
- Tags: testing
- Published: 2026-08-31

---

**The OpenLogi agent mock lets you develop and test Logitech HID++ device management interfaces without any physical hardware by running `cargo run -p openlogi-agent --bin openlogi-agent-mock` to serve a scripted device inventory over IPC.**

The `openlogi-agent-mock` binary in the AprilNEA/OpenLogi repository provides a complete software-only replacement for the real hardware agent. It implements the same IPC contract as the production agent, enabling GUI development, integration testing, and debugging when no Logitech devices are available. This guide covers how to run the mock, configure its behavior, and integrate it into your development workflow.

## What Is the OpenLogi Agent Mock?

The mock agent is a **hardware-free simulation** that ships as a separate binary within the `openlogi-agent` crate. Located at [`crates/openlogi-agent/src/bin/mock_agent.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-agent/src/bin/mock_agent.rs), it:

- Serves a **scripted device inventory** over the agent IPC socket
- Uses the **`openlogi-dev`** profile by default (equivalent to `OPENLOGI_PROFILE=dev`)
- Reports a version string with `-mock` suffix for easy identification
- Competes for the **same single-instance lock** as the real agent

The mock **does not implement hardware-dependent actions** like SmartShift torque control or Actions Ring actuation. However, it fully supports the IPC surface required by the UI for device discovery, capability enumeration, and state management.

## Running openlogi-agent-mock

### Basic Startup

Start the mock agent with Cargo:

```bash
cargo run -p openlogi-agent --bin openlogi-agent-mock

```

This compiles and runs the mock binary defined in [`crates/openlogi-agent/Cargo.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-agent/Cargo.toml) (lines 17–22), which points `path = "src/bin/mock_agent.rs"` to the mock implementation.

### Connecting a Client

With the mock running, launch any client in a second terminal:

```bash

# Start the desktop UI

cargo run -p openlogi-desktop

```

The GUI automatically discovers and connects to the mock's IPC socket, displaying the scripted device inventory as if real hardware were present.

### Verifying Mock Mode

Check that your client detects the mock session by examining the agent version string. The mock appends `-mock` to its version (e.g., `0.9.0-mock`), which the UI displays wherever agent version information appears.

## Configuration Options

### Profile Selection

The mock defaults to the `openlogi-dev` profile. Override this with environment variables:

```bash

# Explicitly use the development profile

OPENLOGI_PROFILE=dev cargo run -p openlogi-agent --bin openlogi-agent-mock

# Use a custom profile you've defined

OPENLOGI_PROFILE=staging cargo run -p openlogi-agent --bin openlogi-agent-mock

```

Additional configuration patterns are documented in [`docs/DEVELOPMENT.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/DEVELOPMENT.md) (lines 123–150), which covers environment setup and mock integration workflows.

## Critical Usage Constraints

### Single-Instance Lock Behavior

The mock competes for the **same system-wide lock** as the real `openlogi-agent` binary. To avoid conflicts:

- **Start the mock before the real agent**, or
- **Run the mock in complete isolation** with no other agent instances

Attempting to run both simultaneously results in a lock contention failure in the second process.

### Hardware Action Limitations

The mock explicitly **refuses hardware-dependent operations**:

| Capability | Mock Support | Real Agent |
|------------|-----------|------------|
| Device discovery & inventory | ✅ Full | ✅ Full |
| Capability enumeration | ✅ Full | ✅ Full |
| State reading | ✅ Full | ✅ Full |
| SmartShift torque adjustment | ❌ None | ✅ Hardware |
| Actions Ring activation | ❌ None | ✅ Hardware |
| LED/DPI hardware control | ❌ None | ✅ Hardware |

Design your tests around these boundaries—verify hardware interactions through integration tests with physical devices when needed.

## Complete Development Workflow

For comprehensive GUI development without hardware:

```bash

# Terminal 1: Start the mock agent

cargo run -p openlogi-agent --bin openlogi-agent-mock

# Terminal 2: Launch the desktop application

cargo run -p openlogi-desktop

# Terminal 3: Optional—run automated tests against the mock

cargo test -p openlogi-desktop -- --test-threads=1

```

The mock's scripted inventory remains consistent across restarts, enabling reproducible test scenarios that would be impossible with physical hardware state variations.

## Key Source Files

Understanding these files deepens your ability to extend or debug the mock:

- **[`crates/openlogi-agent/src/bin/mock_agent.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-agent/src/bin/mock_agent.rs)** — Core mock implementation with scripted inventory serving and IPC handling
- **[`crates/openlogi-agent/Cargo.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-agent/Cargo.toml)** — Binary declaration for `openlogi-agent-mock`
- **[`docs/DEVELOPMENT.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/DEVELOPMENT.md)** — Official development guide with mock usage patterns
- **[`AGENTS.md`](https://github.com/AprilNEA/OpenLogi/blob/main/AGENTS.md)** — High-level agent architecture overview with mock references (lines 177–180)

## Summary

- **The `openlogi-agent-mock` binary** provides complete hardware-free testing for OpenLogi development
- **Run with `cargo run -p openlogi-agent --bin openlogi-agent-mock`** to start the IPC server
- **Single-instance lock** requires isolation from the real agent—start mock first or run exclusively
- **`-mock` version suffix** enables client-side detection of mock sessions
- **Hardware actions are stubbed**—torque, ring, and LED controls return errors or no-ops

## Frequently Asked Questions

### How do I know if my UI is connected to the mock or real agent?

Check the agent version string displayed in your UI's connection status or about dialog. The mock reports a version ending in `-mock` (e.g., `0.9.0-mock`), while the real agent reports a clean semantic version without this suffix. This distinction is implemented in [`mock_agent.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/mock_agent.rs) to prevent confusion during development.

### Can I run the mock and real agent simultaneously on the same machine?

No. Both binaries acquire a system-wide single-instance lock, causing the second process to fail on startup. Per [`AGENTS.md`](https://github.com/AprilNEA/OpenLogi/blob/main/AGENTS.md), you must either start the mock before any real agent instance, or ensure no other agent process is running. For CI environments, consider container isolation or dedicated mock-only test runners.

### What device capabilities are actually simulated by the mock?

The mock serves a **static scripted inventory** that includes complete device metadata, capability flags, and readable state values. However, any IPC call requiring hardware manipulation—such as SmartShift torque configuration, Actions Ring hardware triggers, or DPI/lift-off distance changes—receives an error response or silent no-op. The exact capability matrix depends on the scripted inventory defined in the mock source.

### Is the mock suitable for production deployments?

Absolutely not. The mock is **strictly a development tool** as documented in [`docs/DEVELOPMENT.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/DEVELOPMENT.md). It never accesses HID++ devices, provides no hardware control, and is excluded from production release builds. Deploying the mock in production would result in non-functional device management and potential security implications from its permissive simulated state.