How to Run All OpenLogi Tests Locally: Complete Workspace Guide

Run cargo test --workspace from the repository root to execute every unit and integration test across all OpenLogi workspace crates.

OpenLogi organizes its Rust codebase as a Cargo workspace containing multiple specialized crates, from core types to GUI components. To ensure comprehensive validation during local development, you need commands that execute the complete test matrix without manually entering each directory. This guide explains the exact commands and environment variables required to run all OpenLogi tests locally based on the current source tree.

Understanding the OpenLogi Test Structure

OpenLogi’s test suite is distributed across the workspace’s many crates. Understanding where tests live helps you interpret output and target specific failures.

Unit Tests Inside Source Files

Inside each crate’s src directory, unit tests are guarded by #[cfg(test)] modules. These compile conditionally during test runs and verify individual functions in isolation.

Integration Tests in Dedicated Directories

Integration tests reside in tests/ folders next to each crate’s source. According to the repository layout, these verify cross-crate functionality including HID++ handling, IPC layers, and agent communication across the full stack.

Running the Full Test Suite Locally

Using the Workspace-Wide Test Command

The most direct method to run all OpenLogi tests locally is invoking Cargo with the workspace flag. This command respects individual crate features and platform-specific code, covering macOS, Linux, and Windows targets.

cargo test --workspace

This builds each crate once, then executes all tests discovered via Cargo.toml, the top-level workspace manifest that lists every member crate.

Replicating the CI Environment with xtask

To match the continuous integration pipeline exactly, use the helper task defined in xtask/src/main.rs:

cargo xtask ci

This command runs the full CI sequence including clippy, fmt, and the complete test matrix. Running this locally ensures platform-specific failures surface identically to the CI environment.

Testing Without Hardware Dependencies

Using the Mock Agent

When developing locally, prevent the test suite from attempting to access physical hardware by using the mock agent provided in crates/openlogi-agent-mock/src/main.rs. Set the environment variable OPENLOGI_DEV_AGENT=0 before invoking Cargo:

OPENLOGI_DEV_AGENT=0 cargo test --workspace

This disables automatic spawning of a real agent process and instead uses the scripted inventory server, keeping test runs fast and deterministic without requiring attached Logitech devices.

Running Tests for Specific Crates

For targeted debugging of a single component, use the -p flag to specify a package name. For example, to test only the IPC layer:

cargo test -p openlogi-ipc

This is useful when iterating on specific logic without waiting for the entire workspace to rebuild.

Key Configuration Files

• Cargo.toml – The workspace root manifest that cargo test --workspace uses to discover all member crates and their test targets.
• docs/DEVELOPMENT.md – Documents the development workflow and explicitly references the cargo test --workspace command for local validation.
• xtask/src/main.rs – Contains the ci task implementation that orchestrates linting and testing to match remote CI behavior.
• crates/openlogi-agent-mock/src/main.rs – Implements the mock agent service used when OPENLOGI_DEV_AGENT=0 is set.

Summary

• Run cargo test --workspace to execute all tests across the OpenLogi workspace.
• Use cargo xtask ci to replicate the exact continuous integration environment locally.
• Set OPENLOGI_DEV_AGENT=0 to run tests using the mock agent and avoid hardware dependencies.
• Target individual crates with cargo test -p <crate-name> for faster iteration.
• The workspace configuration in Cargo.toml defines how Cargo discovers and runs tests across all crates.

Frequently Asked Questions

What command runs every OpenLogi test at once?

Execute cargo test --workspace from the repository root. This command builds and tests every crate listed in the workspace Cargo.toml, covering both unit tests in src files and integration tests in tests/ directories.

How do I run OpenLogi tests without connected hardware?

Set the environment variable OPENLOGI_DEV_AGENT=0 before running the test command. This flag instructs the test runner to use openlogi-agent-mock instead of spawning a real agent process, allowing the suite to run without physical devices attached.

How can I match the exact test configuration used in CI?

Run cargo xtask ci. This invokes the task defined in xtask/src/main.rs that executes the same sequence of clippy, fmt, and test commands used by the project's continuous integration pipeline.

Where are the integration tests located in the codebase?

Integration tests live in tests/ folders adjacent to each crate's source directory, while unit tests are embedded within #[cfg(test)] blocks inside the src files. The workspace structure defined in Cargo.toml ensures cargo test --workspace discovers and executes both types.

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