Integration Tests and Test Layout

You write use mylib::Config; at the top of tests/api.rs and the compiler answers unresolved import mylib — or, once the path resolves, function is private. The cause is structural, not a path typo: each .rs file directly under tests/ is compiled as its own crate that links your library exactly the way a downstream application would.

mylib/
├── src/
│   ├── lib.rs        → the library crate `mylib`
│   ├── config.rs     → a module inside that crate
│   └── main.rs       → a binary crate, if you have one
└── tests/
    ├── api.rs        → its own crate, links `mylib`
    └── cli.rs        → another own crate, links `mylib`

Follow the consequences, each of which surprises someone once:

• Files do not share scope. api.rs cannot see anything declared in cli.rs; there is no global test file to import from.
• Only the public API is reachable — items exported from lib.rs. Private helpers in config.rs are invisible from here. Testing them means a unit test inside mod tests, as Unit Tests and Assertions set up.
• Every file becomes its own test binary. Thirty files under tests/ means thirty binaries to compile and run, and cargo test --test api executes only the one named.
• Subdirectories are not auto-discovered as targets. Only top-level .rs files become test crates; their mod trees compile into that crate.

The test itself uses an external-crate path, not crate:::

// tests/api.rs
use mylib::{parse, Config}; // dependency path, exactly like a user's code

#[test]
fn parses_timeout() {
    let cfg = parse("timeout=5").unwrap();
    assert_eq!(cfg.timeout, 5);
}

Because the test sees the library as a dependency, it can only use what a real user can use — and that is the point. Integration tests test the contract, not the implementation. If an internal refactor forces you to rewrite them, your public API leaked. Keep them few, high-level, and outcome-focused; anything deeper belongs beside the code as a unit test.

Two Cargo.toml details complete the picture. Dev-dependencies are available to unit tests, integration tests, tests' helpers, and benches, but never to the shipping build — put tempfile, tokio-test, and pretty_assertions under [dev-dependencies] so they cannot leak into production:

[dev-dependencies]
tempfile = "3"
pretty_assertions = "1"

Auto-discovery can be turned off or made explicit with [autotests] and [[test]] entries (name, path, harness) if your layout is unusual; the default covers nearly everything.

Integration tests also drive your binaries. Cargo hands every test target a compile-time environment variable pointing at the built executable, so a CLI gets end-to-end coverage without hard-coded paths:

// tests/cli.rs
use std::process::Command;

fn bin() -> Command {
    Command::new(env!("CARGO_BIN_EXE_myapp"))
}

#[test]
fn rejects_missing_flag() {
    let out = bin().arg("--config").output().unwrap();
    assert!(!out.status.success());
    assert!(String::from_utf8_lossy(&out.stderr).contains("missing value"));
}

CARGO_BIN_EXE_<name> is set while compiling integration tests, and Cargo builds the binary first — which is exactly why cargo test --test cli runs slower than a unit test: there is a real process, real I/O, and a real exit code. Those are the properties no in-process test can assert.

In a workspace the layout rules are unchanged — only the selection changes: cargo test -p mylib runs one member's suite, cargo test --workspace runs all of them. Knowing that split matters as soon as CI time starts climbing, which is the subject of the last chapter of this topic.

One interview question follows directly from this structure: "where would you test a private helper versus a public API?" Answer with the crate boundary — a child module can see privates, an external crate cannot — and the placement decision falls out on its own.

Five files under tests/, each re-declaring fn seed_user() -> User { … }. You change the fixture and edit five places — and miss the fifth one.

Cargo's rules create the temptation: test targets are only top-level .rs files under tests/, and a target can reach your library's public API plus its own mod tree. Nothing else is in scope, so duplicated helpers feel inevitable. The supported answer is a module directory:

tests/
├── common/
│   └── mod.rs        ← helpers; never becomes its own test target
├── orders.rs         ← `mod common;`
└── billing.rs        ← `mod common;`

// tests/common/mod.rs
use mylib::User;
use std::time::Duration;

pub fn seed_users() -> Vec<User> {
    vec![User::new("ada"), User::new("grace")]
}

pub const TIMEOUT: Duration = Duration::from_secs(2);

// tests/orders.rs
mod common; // pulls tests/common/mod.rs into THIS target only

#[test]
fn orders_belong_to_the_user() {
    let users = common::seed_users();
    assert!(orders_for(&users[0]).iter().all(|o| o.owner == "ada"));
}

mod common; at the top of every test file is the price of the pattern — there is no automatic global import. In exchange, pub fn inside common is visible only to the test crates that declare it: common is a private module of each test target, not of your library. Nothing leaks into the shipped API, and nothing needs pub on your real types. Shared within tests/, invisible outside it — that is the whole trick.

Watch two sharp edges. Unused helpers trigger dead-code warnings in whichever target declares them; tag genuinely optional helpers #[allow(dead_code)] in common/mod.rs. And helpers that need your library's internals cannot live here at all — this module sees only the public API, same as any test file, so internal-state fixtures belong in #[cfg(test)] mod helpers inside the source file.

Decide placement with one question: who needs this helper?

Feature-gating deserves a warning: #[cfg(feature = "test-utils")] pub fn … becomes real, documented API surface the moment a downstream crate enables that feature in release builds. Keep fixtures in tests/ unless you are deliberately publishing a testing utility.

A shared module is also the right home for a builder, which removes even more duplication than a plain function:

// tests/common/mod.rs
pub struct OrderBuilder {
    order: Order,
}

impl OrderBuilder {
    pub fn new(owner: &str) -> Self {
        Self { order: Order::new(owner) }
    }
    pub fn with_item(mut self, sku: &str, qty: u32) -> Self {
        self.order.add(sku, qty);
        self
    }
    pub fn build(self) -> Order {
        self.order
    }
}

Now a test states only what differs about its case — OrderBuilder::new("ada").with_item("A-1", 2).build() — and the fixture's shape can change in one place. That is the real measure of test organization: how much can change before your tests have to.

There is a third sharing story that costs nothing: doc tests. An example inside /// runs as its own test against the public API, so the snippet you would have written in documentation anyway doubles as a contract check — see the final chapter for how to run and select them.

In interviews, "how do you avoid duplicated test setup?" gets a much better answer than "a base class": this directory pattern plus a crate-level fixture builder, with the reasoning that test targets are separate crates — which is also exactly why the duplication existed in the first place.

With fixtures centralized, the remaining problem is scheduling: which slice of the suite runs where, locally and in CI. That is the next chapter's subject.

CI runs fourteen hundred tests across a workspace; you changed one crate. Waiting for the whole suite — or re-running everything locally after each edit — is a workflow bug, and the fix is Cargo's selection flags.

cargo test -p mylib                  # one workspace member
cargo test -p mylib --test orders    # one integration target
cargo test --workspace               # every member
cargo test timeout                   # substring filter on test names
cargo test --lib config              # unit tests only, name-filtered
cargo test -- --exact tests::parses_timeout
cargo test --doc                     # doc tests only
cargo test --no-run                  # compile everything, execute nothing

-p (--package) takes a package name from Cargo.toml — not a path, not a directory. cargo test ./crates/mylib is the common first mistake and fails with a manifest error. In a workspace that sets default-members, bare cargo test already restricts itself; otherwise it builds every member.

Doc tests are a third suite

/// Add two integers.
///
/// ```
/// use mathy::add;
/// assert_eq!(add(2, 2), 4);
/// ```
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

cargo test extracts each fenced Rust block from doc comments, wraps it in fn main implicitly, and compiles and runs it as an independent test with the crate available by name. The rules that bite people:

• text blocks (and ignore) are skipped; no_run compiles without executing — right for examples that open sockets.
• Lines prefixed with # are hidden in rendered docs but included in the compiled test, which is how you hide use statements and setup.
• A doc example that fails to compile is a failing test, so examples cannot rot silently.

Slicing the pipeline

A practical CI layout splits by suite so failures are attributable at a glance:

cargo test --workspace --all-targets   # unit + integration + benches compile
cargo test --doc                       # documentation examples
cargo clippy --all-targets -- -D warnings

Add per-crate caching keyed on Cargo.lock, and --no-run as a separate compilation step: in a monorepo the feedback loop drops from minutes to seconds because unchanged crates stay cached. Locally, a cargo watch-style loop keeps the cycle under a second while you iterate.

For suites past a few hundred tests, swap the runner rather than the tests: cargo nextest run executes each test in its own process, which gives three things libtest cannot — one crashing test cannot take down the rest, per-test timing is reported accurately, and tests run in parallel across processes instead of threads (a real win when your tests touch static state). The test functions themselves do not change.

Interviewers ask "how do you keep a large suite fast?" Answer with three levers: selection (-p, --test, name filters so only affected crates run), parallelism (the harness defaults to one thread per core, and --test-threads=1 is a debugging tool, not a default), and honest test design — anything needing a real network or a slow external service belongs in an #[ignore]d tier that CI runs nightly, not on every push.

Notice what selection does not solve: if a test needs to talk to a database it cannot reach in CI, no flag fixes that. The answer is substituting the dependency, which is where Test Doubles with Traits begins.