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

> Learn how to run tests for the iroh project using cargo-nextest. Execute the full test suite locally with this comprehensive guide and simple command.

- Repository: [number zero/iroh](https://github.com/n0-computer/iroh)
- Tags: how-to-guide
- Published: 2026-07-03

---

**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:

```bash
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:

```bash
cargo nextest run --workspace --profile ci

```

This command mirrors the implementation in [`.github/workflows/tests.yaml`](https://github.com/n0-computer/iroh/blob/main/.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`](https://github.com/n0-computer/iroh/blob/main/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:

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

```

## Using cargo-make Helper Tasks

The repository includes a [`Makefile.toml`](https://github.com/n0-computer/iroh/blob/main/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:

```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) (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:

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

```

**Flaky Test Detection**: The workflow defined in [`.github/workflows/flaky.yaml`](https://github.com/n0-computer/iroh/blob/main/.github/workflows/flaky.yaml) runs `cargo nextest` with aggressive flags to surface intermittent failures. Reproduce this locally with:

```bash
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:

```bash
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`](https://github.com/n0-computer/iroh/blob/main/Makefile.toml).
- **Debug flaky tests** using `--run-ignored all` and `--verbose` as implemented in [`.github/workflows/flaky.yaml`](https://github.com/n0-computer/iroh/blob/main/.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`](https://github.com/n0-computer/iroh/blob/main/.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`](https://github.com/n0-computer/iroh/blob/main/Makefile.toml) (line 42) and used throughout [`.github/workflows/tests.yaml`](https://github.com/n0-computer/iroh/blob/main/.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`](https://github.com/n0-computer/iroh/blob/main/.github/workflows/flaky.yaml), forcing execution of ignored tests and enabling verbose output to catch intermittent failures.