Skip to content
rusthacks.dev
Testing

Test Organization in Rust for Large Workspaces Explained

Organize Rust tests in a large workspace: unit tests beside code, integration tests per crate, a shared test-support crate, slow test gating and what to run in CI.

2 min read
Summarize in AI
Flat illustration for the post “Test Organization in Rust for Large Workspaces Explained”, composed around deploy.

A test suite for one crate fits in a head. A workspace with fifteen crates needs rules, or the suite becomes slow, flaky and impossible to navigate. Everything compiles on Rust 1.90 with edition 2024 and Cargo from the same release.

Three kinds, three places

KindWhereCan see
Unit#[cfg(test)] mod tests in the source fileprivate items too
Integrationcrate/tests/*.rspublic API only
Doc tests/// examplespublic API only
src/price.rsrust
pub fn with_tax(cents: u64, rate_bp: u64) -> u64 {
    cents + cents * rate_bp / 10_000
}

fn round_half_up(n: u64, d: u64) -> u64 {
    (n + d / 2) / d
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn adds_tax() {
        assert_eq!(with_tax(1000, 2000), 1200);
    }

    #[test]
    fn rounds() {
        assert_eq!(round_half_up(5, 2), 3);
    }
}

The second test touches the private round_half_up. Unit tests stay near the code they check, so they are read and updated with it. The standard layouts are in unit test modules and integration tests.

One binary for integration tests

Text
crates/billing/
  src/lib.rs
  tests/
    it/
      main.rs        mod invoices; mod refunds;
      invoices.rs
      refunds.rs

Cargo treats tests/it/main.rs as one test target, so the linker runs once instead of once per file. Compile time for a big suite can drop noticeably, at the price of one shared process for those tests (they must not rely on global state).

A shared support crate

crates/test-support/Cargo.tomlTOML
[package]
name = "test-support"
version = "0.0.0"
edition.workspace = true
publish = false

[dependencies]
tempfile = "3"
crates/billing/Cargo.tomlTOML
[dev-dependencies]
test-support = { path = "../test-support" }

Put builders (an_invoice().paid().build()), fake clocks and temp-directory helpers there. publish = false keeps it off crates.io. Because dev-dependencies are not built for dependents, none of this reaches production binaries.

Slow tests

rust
#[test]
#[ignore = "needs DATABASE_URL"]
fn writes_to_postgres() {
    // ...
}

cargo test skips it; cargo test -- --ignored runs only ignored tests, and -- --include-ignored runs everything. A feature gate (#[cfg(feature = "integration")]) works too and keeps the slow tests out of compilation. Write the reason in the attribute so the skip list explains itself (filtering tests).

CI tiers

1. Every push: cargo fmt --check, cargo clippy --workspace --all-targets, cargo nextest run --workspace. 2. Pull requests: add feature combinations (testing feature combinations) and doc tests (cargo test --doc, which nextest does not run). 3. Nightly or merge queue: ignored tests with real services, fuzzing, mutation testing.

Habits that scale

  • Name tests for behavior (rejects_duplicate_email), not for functions.
  • Keep unit tests free of the file system and clock; put those behind injectable parts (injected clocks).
  • A test that needs a long setup is telling you the code has too many dependencies.
  • Use workspace-level cargo test --workspace locally, but run one crate with -p while working.

The broader map is testing Rust.

Share

Keep reading

Get new posts by email

We send one email when a new post is published. No spam.

Unsubscribe in one click. No spam, ever.