Skip to content
rusthacks.dev
Testing

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.

3 min read
Summarize in AI
Flat illustration for the post “Integration Tests in Rust and the Tests Directory Explained”, composed around borrow.

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

Text
my-crate/
  Cargo.toml
  src/lib.rs
  tests/
    common/mod.rs
    signup.rs
    billing.rs
src/lib.rsrust
pub fn total_cents(prices: &[u32], tax_percent: u32) -> u32 {
    let sum: u32 = prices.iter().sum();
    sum + sum * tax_percent / 100
}
tests/common/mod.rsrust
pub fn sample_prices() -> Vec<u32> {
    vec![1000, 250, 750]
}
tests/billing.rsrust
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.

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:

Text
tests/
  integration.rs      // mod signup; mod billing;
  integration/
    signup.rs
    billing.rs

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

rust
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.

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.