Integration Tests in Rust and the Tests Directory Explained
Files in the tests directory are separate crates that use your library like any outside user. Learn the layout, shared helpers without duplicate test binaries and testing a binary crate.

A unit test checks that a function does what it says. An integration test checks that the crate does what its documentation says, from the outside. Cargo supports the second with a directory and no configuration, and the structure has two quirks: every file is a separate crate, and shared helpers go in a place Cargo ignores. This post shows both. It is the second layer in the testing in Rust guide.
Rust 1.90, edition 2024.
The layout
my-crate/
Cargo.toml
src/lib.rs
tests/
common/mod.rs
signup.rs
billing.rspub fn total_cents(prices: &[u32], tax_percent: u32) -> u32 {
let sum: u32 = prices.iter().sum();
sum + sum * tax_percent / 100
}pub fn sample_prices() -> Vec<u32> {
vec![1000, 250, 750]
}mod common;
use my_crate::total_cents;
#[test]
fn adds_tax_to_the_sum() {
let prices = common::sample_prices();
assert_eq!(total_cents(&prices, 10), 2200);
}cargo test runs unit tests, then each file in tests/, then doc tests, and prints a result block for each. use my_crate::total_cents works because the test file links the library like any dependency. The arithmetic: 1000 + 250 + 750 is 2000, plus 10 percent is 2200.
Why common/mod.rs and not common.rs
A file tests/common.rs would be compiled as a test binary of its own and show up in the output with "running 0 tests". A directory with mod.rs is not built as a test; it is only compiled where a test file says mod common;. Each test file that declares mod common; gets its own copy, so unused helper warnings can appear; add #![allow(dead_code)] at the top of common/mod.rs.
Speed and link time
Every file in tests/ is a separate executable that must be linked against your crate. For many files this becomes the slowest part of cargo test. The remedy is to have one file that declares modules:
tests/
integration.rs // mod signup; mod billing;
integration/
signup.rs
billing.rsNow there is one test binary, one link step, and the same tests. Run a subset with cargo test --test integration signup.
Binary crates
If the package has only src/main.rs, tests/*.rs cannot use anything from it. Either split the logic into lib.rs (library or binary) or test the executable itself with assert_cmd (testing CLI tools). Cargo also sets CARGO_BIN_EXE_<name> for integration tests, giving the path of the built binary.
Resources and isolation
Tests run in parallel threads within one binary. Do not share a file, a port or a database table between them without coordination: bind port 0 (address already in use), use tempfile::tempdir(), create a schema per test. State shared across files is safe in the sense that each file is a separate process, but the same external database is not.
Fixtures
Read fixture files relative to the manifest:
let path = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("tests/fixtures/input.txt");The test then works when run from the workspace root or from the crate folder.
Limits
Integration tests are slower and less precise about the cause of a failure than unit tests. Use them for contracts, and unit tests for details. The Rust book describes the layout in integration tests.


