How to Run Tests in iroh: Complete Guide to cargo-nextest and CI Workflows

The iroh workspace uses cargo-nextest with a dedicated CI profile to execute unit, integration, and binary tests in parallel, matching the exact configuration validated by GitHub Actions.

The n0-computer/iroh repository is a Rust workspace comprising multiple crates including iroh, iroh-relay, iroh-base, and iroh-dns-server. While standard Rust testing tools work, the project standardizes on cargo-nextest for faster parallel execution and reproducible CI behavior. Understanding how to run tests in iroh ensures your changes pass the same validation gates used in production workflows.

Installing the Test Runner

Before executing tests, install the required nextest tool. The CI workflow installs this via taiki-e/install-action@nextest, but locally you should use:

cargo install cargo-nextest --locked

This provides the cargo nextest command that supersedes the standard test harness with improved partitioning and reporting capabilities.

Running the Full Test Suite

To run tests in iroh exactly as the CI does, execute the workspace-wide command with the CI profile:

cargo nextest run --workspace --profile ci

This command mirrors the validation step found in .github/workflows/tests.yaml (lines 165-176). The --workspace flag ensures tests run across all member crates, while the --profile ci argument applies timeout and logging settings defined in Makefile.toml (line 42) that match the continuous integration environment.

Running Specific Tests

When working on a particular component, you can narrow the scope to reduce execution time.

Single Crate Execution

Target a specific package using the -p flag:

cargo nextest run -p iroh-relay

This runs only the tests within the iroh-relay crate, skipping unrelated components like iroh-dns-server.

Individual Test Names

Filter to a specific test binary or test function:

# Run a specific test binary

cargo nextest run -p iroh --test patchbay

# Run a specific test function

cargo nextest run -p iroh --test patchbay --filter patchbay::test_name

Integration Test Helpers with cargo-make

The repository includes a Makefile.toml that defines convenience tasks for complex integration tests. The patchbay task (lines 39-44) wraps nextest with appropriate flags for the patchbay integration test:

cargo make patchbay

This executes the test defined in iroh/tests/patchbay.rs (line 15), which validates network behavior between iroh nodes. Using cargo-make ensures you pass the exact environment variables and filters required for these specialized test scenarios.

Handling Flaky Tests

The project maintains a dedicated workflow for detecting intermittent failures. As defined in .github/workflows/flaky.yaml, you can surface hidden flakiness locally by running:

cargo nextest run --workspace --profile ci --run-ignored all --verbose

The --run-ignored all flag executes tests marked as ignored, which typically includes stress tests or those known to have timing sensitivities.

Using Standard cargo test (Fallback)

If nextest is unavailable, the standard Rust test harness remains functional:

cargo test --workspace

This executes the same test logic but lacks the parallelization, timeout handling, and JSON reporting that nextest provides. It serves as a reliable fallback when debugging requires the standard test output format.

Summary

• Install cargo-nextest using cargo install cargo-nextest --locked to match the CI toolchain.
• Run the full suite with cargo nextest run --workspace --profile ci to validate against the same configuration used in .github/workflows/tests.yaml.
• Target specific crates using -p iroh or similar flags when iterating on individual components.
• Use cargo-make for complex integration tests like patchbay via cargo make patchbay.
• Check for flakiness with --run-ignored all to ensure robustness before submitting changes.

Frequently Asked Questions

What is cargo-nextest and why does iroh use it?

cargo-nextest is a next-generation test runner for Rust that provides faster parallel execution, better isolation between tests, and structured JSON output. According to the iroh source code, the project uses it to reduce CI times and handle timeout configurations consistently across local and GitHub Actions environments.

How do I run only the iroh-relay tests?

Execute cargo nextest run -p iroh-relay to limit execution to only the relay crate. This is useful when modifying code in iroh-relay/src/ or iroh-relay/tests/ and you want immediate feedback without running the entire workspace suite.

What is the patchbay test and how do I run it?

The patchbay test is an integration test located in iroh/tests/patchbay.rs that validates inter-node communication protocols. You can run it via cargo make patchbay (using the task defined in Makefile.toml) or directly with cargo nextest run -p iroh --test patchbay.

How does iroh handle flaky tests in CI?

The repository uses a dedicated workflow in .github/workflows/flaky.yaml that runs cargo nextest with --run-ignored all and verbose flags to detect intermittent failures. Locally, you can reproduce this behavior to identify flaky tests before they disrupt the main CI pipeline.

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