How to Run Tests for the iroh Project: A Complete Guide

The iroh project uses cargo-nextest as its primary test runner, requiring you to install the tool and run cargo nextest run --workspace --profile ci to execute the full test suite locally.

The iroh repository by n0-computer is a Rust workspace containing multiple crates including iroh, iroh-relay, and iroh-base. While standard cargo test works as a fallback, the project officially supports cargo-nextest for faster, parallelized execution with CI-matching configuration. Understanding the specific flags and profiles defined in the source ensures your local runs match the continuous integration pipeline.

Installing cargo-nextest

Before running tests, install the cargo-nextest tool. The CI workflow installs it via the GitHub Action taiki-e/install-action@nextest, but locally you should use:

cargo install cargo-nextest --locked

This provides the nextest subcommand that the workspace relies on for parallel test execution and timeout handling.

Running the Full Test Suite

To execute all tests across every crate in the workspace—including iroh, iroh-relay, iroh-base, and iroh-dns-server—use the CI profile:

cargo nextest run --workspace --profile ci

This command mirrors the implementation in .github/workflows/tests.yaml (lines 165-176), where the CI invokes cargo nextest run with the ci profile. The --workspace flag ensures tests run for every member crate, while the ci profile (defined in Makefile.toml at line 42) applies specific timeout and logging settings used in automated builds.

Running Specific Tests

You can limit execution to a single crate, test binary, or individual test name:

• Single crate: cargo nextest run -p iroh
• Specific test binary: cargo nextest run --test patchbay
• Individual test: cargo nextest run -p iroh --test patchbay --filter patchbay::test_name

To skip binary examples and run only library tests, add the --lib flag:

cargo nextest run --workspace --lib --profile ci

Using cargo-make Helper Tasks

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

cargo make patchbay

This executes the test defined in iroh/tests/patchbay.rs (as documented in the source comment at line 15) using the correct profile and filters.

Debugging and Flaky Test Handling

The project maintains specific workflows for debugging test failures and handling intermittent issues.

JSON Output: To capture machine-readable results locally (similar to CI artifacts stored under output/), use:

cargo nextest run --workspace --profile ci --message-format json > test-results.json

Flaky Test Detection: The workflow defined in .github/workflows/flaky.yaml runs cargo nextest with aggressive flags to surface intermittent failures. Reproduce this locally with:

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

The --run-ignored all flag forces execution of tests normally marked as ignored, which helps identify unstable tests before they reach the main branch.

Fallback: Standard Cargo Test

If you cannot install cargo-nextest, the standard Rust test harness remains available:

cargo test --workspace

Note that this lacks the parallelization, timeout configuration, and CI-specific profile handling that nextest provides.

Summary

• Install cargo-nextest using cargo install cargo-nextest --locked before running tests.
• Execute the full suite with cargo nextest run --workspace --profile ci to match CI behavior.
• Target specific crates with -p <crate> or specific tests with --test and --filter flags.
• Use helper tasks like cargo make patchbay for integration tests defined in Makefile.toml.
• Debug flaky tests using --run-ignored all and --verbose as implemented in .github/workflows/flaky.yaml.

Frequently Asked Questions

Can I run iroh tests without installing cargo-nextest?

Yes, you can use cargo test --workspace as a fallback. However, this runs tests sequentially without the parallel execution, timeout management, and CI profile settings that cargo-nextest provides according to the project's .github/workflows/tests.yaml.

How do I run only the tests for the iroh-relay crate?

Use the package flag: cargo nextest run -p iroh-relay. This limits execution to the specific crate while still applying the nextest runner's parallelization and filtering capabilities.

What is the purpose of the ci profile in the test commands?

The ci profile, referenced in Makefile.toml (line 42) and used throughout .github/workflows/tests.yaml, configures specific timeout values and logging formats to ensure consistent behavior between local development and the continuous integration environment.

How do I reproduce the flaky test detection workflow locally?

Run cargo nextest run --workspace --profile ci --run-ignored all --verbose. This mirrors the configuration in .github/workflows/flaky.yaml, forcing execution of ignored tests and enabling verbose output to catch intermittent failures.

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