How to Run the Tests for OpenLogi: A Complete Guide to the Rust Workspace Test Suite

You can run the tests for OpenLogi using cargo test --workspace for the full suite, cargo test -p <crate-name> for specific crates, or cargo xtask ci to replicate the GitHub Actions pipeline locally.

OpenLogi is a multi-crate Rust workspace that provides a modular architecture for Logitech device management. Whether you are contributing new features or verifying local changes, understanding how to run the tests for OpenLogi ensures you catch regressions before submitting pull requests. This guide covers every granularity of testing, from workspace-wide suites to hardware-independent GUI validation.

Running the Full Workspace Test Suite

To execute the comprehensive test suite that mirrors the continuous integration pipeline, run all tests across every crate in the workspace.

Use the following command from the repository root:

cargo test --workspace

This command targets every package defined in the workspace Cargo.toml, ensuring that changes in shared dependencies do not break downstream crates. According to the development guide in docs/DEVELOPMENT.md, this is the recommended pre-push gate to validate your changes before opening a pull request.

Testing Individual Crates in the OpenLogi Workspace

When working on a specific component, you can limit test execution to a single crate using the -p flag. This reduces feedback time during iterative development.

Run tests for a specific package:

cargo test -p <crate-name>

For example, to test only the IPC wire format implementation as documented in crates/openlogi-ipc/AGENTS.md:

cargo test -p openlogi-ipc --test wire_format

This pattern allows you to focus on the openlogi-ipc, openlogi-agent, or openlogi-desktop crates independently without compiling the entire workspace.

Replicating CI Tests Locally with xtask

OpenLogi includes an xtask helper that reproduces the exact jobs defined in .github/workflows/ci.yml. This ensures your local environment matches the CI environment before pushing commits.

Execute all reproducible CI jobs:

cargo xtask ci

To run a specific job, such as the check task that combines formatting, clippy, tests, and rustdoc verification:

devenv tasks run openlogi:check

The xtask/AGENTS.md file documents the mapping between GitHub Actions jobs and these local commands, making it possible to debug CI failures without pushing to the remote repository.

Testing the Desktop GUI and Internationalization

The desktop crate contains platform-specific tests, particularly for internationalization (i18n), that require macOS in the official CI environment but can be run locally on supported platforms.

Execute the desktop i18n tests:

cargo test -p openlogi-desktop i18n

As noted in crates/openlogi-desktop/AGENTS.md, these tests validate translation key integrity and UI rendering logic. While the CI restricts these to macOS runners, developers on Linux or Windows can still execute them if the necessary GUI dependencies are available.

Running Tests Without Hardware Using the Mock Agent

OpenLogi provides a mock agent that simulates Logitech hardware, enabling GUI development and testing without physical devices. This requires running two separate processes.

First, start the mock agent in one terminal:

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

Then, in a second terminal, run the desktop tests against the mock:

OPENLOGI_DEV_AGENT=0 cargo test -p openlogi-desktop

The OPENLOGI_DEV_AGENT=0 environment variable signals the test suite to connect to the mock agent rather than searching for physical hardware. This workflow is documented in docs/DEVELOPMENT.md under the section for developing the GUI without hardware.

Summary

• Run the full suite with cargo test --workspace to validate all crates as defined in Cargo.toml.
• Target specific crates using cargo test -p <crate-name> for faster iteration on individual components.
• Replicate CI locally via cargo xtask ci to match the GitHub Actions pipeline defined in .github/workflows/ci.yml.
• Test GUI features with cargo test -p openlogi-desktop i18n, noting platform-specific requirements.
• Use the mock agent (openlogi-agent-mock) with OPENLOGI_DEV_AGENT=0 to run integration tests without physical Logitech devices.

Frequently Asked Questions

How do I run only the tests for a specific crate in OpenLogi?

Use the -p flag followed by the crate name. For example, cargo test -p openlogi-ipc runs only the IPC crate tests. You can further narrow execution using --test <test-file> to target specific integration test files like wire_format as described in the IPC architecture documentation.

Can I run the OpenLogi CI tests on my local machine?

Yes. Install the repository's xtask helper and run cargo xtask ci to execute every job your host environment can reproduce. For specific checks that combine formatting, clippy, and tests, use devenv tasks run openlogi:check as documented in docs/DEVELOPMENT.md.

Do I need a Logitech device to run the OpenLogi tests?

No. While some integration tests assume hardware availability, you can run the full desktop test suite using the mock agent. Start cargo run -p openlogi-agent --bin openlogi-agent-mock in one terminal, then execute OPENLOGI_DEV_AGENT=0 cargo test -p openlogi-desktop in another to test the GUI against simulated hardware.

Why are some tests in the desktop crate skipped on Linux or Windows?

The i18n tests and certain GUI integration tests are restricted to macOS in the official CI configuration because they target platform-specific rendering pipelines. However, you can attempt to run them locally using cargo test -p openlogi-desktop i18n if your development environment supports the required graphics dependencies.

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