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.

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
| Kind | Where | Can see |
|---|---|---|
| Unit | #[cfg(test)] mod tests in the source file | private items too |
| Integration | crate/tests/*.rs | public API only |
| Doc tests | /// examples | public API only |
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
crates/billing/
src/lib.rs
tests/
it/
main.rs mod invoices; mod refunds;
invoices.rs
refunds.rsCargo 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
[package]
name = "test-support"
version = "0.0.0"
edition.workspace = true
publish = false
[dependencies]
tempfile = "3"[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
#[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 --workspacelocally, but run one crate with-pwhile working.
The broader map is testing Rust.


