# How to Run Tests in iroh: Complete Guide to cargo-nextest and CI Workflows > Learn to run tests in iroh using cargo-nextest and CI workflows. This guide covers parallel execution for unit, integration, and binary tests, mirroring GitHub Actions configuration. - Repository: [number zero/iroh](https://github.com/n0-computer/iroh) - Tags: tutorial - Published: 2026-07-12 --- **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: ```bash 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: ```bash cargo nextest run --workspace --profile ci ``` This command mirrors the validation step found in [`.github/workflows/tests.yaml`](https://github.com/n0-computer/iroh/blob/main/.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`](https://github.com/n0-computer/iroh/blob/main/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: ```bash 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: ```bash # 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`](https://github.com/n0-computer/iroh/blob/main/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: ```bash cargo make patchbay ``` This executes the test defined in [`iroh/tests/patchbay.rs`](https://github.com/n0-computer/iroh/blob/main/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`](https://github.com/n0-computer/iroh/blob/main/.github/workflows/flaky.yaml), you can surface hidden flakiness locally by running: ```bash 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: ```bash 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`](https://github.com/n0-computer/iroh/blob/main/.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`](https://github.com/n0-computer/iroh/blob/main/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`](https://github.com/n0-computer/iroh/blob/main/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`](https://github.com/n0-computer/iroh/blob/main/.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.