skip to content

In a Rust package, what does Cargo build from each file in the tests/ directory, and which library items can that code call?

level: juniorimportance: must knowfreq 55%

answer

  1. outside the crate, looking in
  2. one executable per file
  3. use the library by its name
  4. pub items, nothing configured out

basics

~20 s

Cargo compiles each top-level .rs file in tests/ as its own crate and test executable, linked against the package's library. That code can call only the library's public API, exactly as a downstream crate would.

solid answer

~40 s

Each file such as `tests/api.rs` becomes a separate crate with its own test executable, built only by `cargo test`, so it needs no `#[cfg(test)]`. It brings the library in by its crate name — `use logfilter::{parse, Level};` — and sees only `pub` items reachable from the crate root: calling a private or `pub(crate)` function fails with E0603. The library is compiled for it as an ordinary build, so anything behind `#[cfg(test)]` in `src/` is configured out (E0425). Each file gets its own `Running tests/...` section, its `#[test]` functions run under the same libtest harness as unit tests, and it can use the package's `[dev-dependencies]`.

code

rust · 17 lines
rust
// tests/api.rs: its own crate, linked against the logfilter library
use logfilter::{keep, parse, Level};

#[test]
fn parse_ignores_case() {
    assert_eq!(parse("Info"), Ok(Level::Info));
}

#[test]
fn keep_drops_lines_below_min() {
    let lines = ["[DEBUG] tick", "[WARN] slow disk", "[ERROR] disk full"];
    let kept: Vec<&str> = keep(&lines, Level::Warn).collect();
    assert_eq!(kept, ["[WARN] slow disk", "[ERROR] disk full"]);
}

// Does not compile: normalize is private to the library (E0603).
// let tag = logfilter::normalize(" WARN ");

go deeper

for a junior

Recall that each file in tests/ is its own crate, imports the library by name, and can only use pub items.

for a middle

Explain the mechanics: a separate test executable per file, the library built without cfg(test), and the E0603 and E0425 errors that follow.

for a senior

Show that integration tests validate the published API, catch missing re-exports, and that many small test files cost link time you may want to consolidate.

for a principal

Frame the split as a design check: what is worth proving through the public API versus inside the module, and how test layout affects build time.

## What the tests/ directory is A Cargo package can hold a directory called `tests/` next to `src/`. Cargo treats the `.rs` files directly inside it as **integration tests**: code that exercises the package's **library crate** (`src/lib.rs`) from the outside, the way a user of the library would. The name contrasts with **unit tests**, which live inside `src/` in a `#[cfg(test)]` module and can reach private items; that side of testing is covered with in-module unit tests. ## Each file is its own crate The defining rule is that **every top-level file in `tests/` is compiled as a separate crate**, and each one becomes its own test executable linked against the library. - **Built only by `cargo test`.** Cargo compiles these files only when tests are built, so they need no `#[cfg(test)]` attribute anywhere. - **Separate scope.** `tests/api.rs` and `tests/cli.rs` cannot see each other's functions; each starts with an empty module tree of its own. - **The library is a dependency.** Because the test is another crate, it must name the library: `use logfilter::{keep, parse, Level};`. Nothing is in scope by default. - **Its own section in the output.** `cargo test` prints a `Running tests/api.rs (...)` block per file, followed by that file's results. - **Dev-dependencies are available.** Integration tests are linked with both `[dependencies]` and `[dev-dependencies]`; the manifest side of that belongs to Cargo's dependency material. Inside one executable, the libtest harness collects the `#[test]` functions and runs them on several threads, exactly as it does for unit tests. Cargo then runs the separate test executables one after another; the flags that change this are Cargo's. ## Only the public API Because an integration test is a different crate, Rust's visibility rules apply to it in full: 1. **Private items are rejected.** Calling a function the library did not mark `pub` fails with `error[E0603]: function `normalize` is private`. 2. **`pub(crate)` is still private here.** That visibility means "inside the library crate", and the test file is not inside it, so the same E0603 appears. 3. **`#[cfg(test)]` items do not exist.** The library is compiled for integration tests as a normal build, without `cfg(test)`, so a helper declared `#[cfg(test)] pub fn fixture()` in `src/` is configured out. rustc reports E0425 and adds the note `found an item that was configured out`. That restriction is the point. A test that compiles against the public API proves the API is usable as published: that the needed items are `pub`, re-exported where callers expect them, and composable without internal shortcuts. | | Unit test | Integration test | |---|---|---| | Location | a `#[cfg(test)] mod tests` inside `src/` | a `.rs` file directly in `tests/` | | Crate | part of the library or binary crate | a separate crate per file | | Reaches private items | yes, through `use super::*` | no, public API only | | Needs `#[cfg(test)]` | yes | no | | Sees `#[cfg(test)]` items in `src/` | yes | no | ## A worked example The `logfilter` package has a library with `pub fn parse`, `pub fn keep` and `pub enum Level`, plus a private `fn normalize`. The file `tests/api.rs` imports the public items and tests them together; un-commenting the last line breaks the build with E0603 rather than reaching into the library. ## Common mistakes - **Expecting `use super::*` to work.** A file in `tests/` has no parent module inside the library; it must import the library by name. - **Testing through internals.** If a behaviour can only be reached through a private function, either the public API is missing something or the check belongs in a unit test. - **Forgetting re-exports.** An item that is `pub` deep inside a private module is not reachable by path from outside; the integration test fails exactly as a user's code would, which is the signal to add a `pub use` at the crate root. - **Assuming a separate package.** Integration tests belong to the same package and share its `Cargo.toml`; they are separate crates, not separate packages, so they need no dependency entry for the library. ## What interviewers listen for - That **each file is a crate**, which explains both the explicit `use` line and why helpers need special handling. - That integration tests **see the crate as a user does**, so a missing `pub` or a missing re-export shows up here first. - That `#[cfg(test)]` code in the library is **invisible** to them, a common surprise when someone tries to share a fixture from `src/`. - That many small files cost a link step each; grouping related tests as modules of one test target is the usual fix when build time grows.

  • Can a Rust integration test call a library function marked pub(crate)?
    No. `pub(crate)` makes the item visible anywhere inside the library crate, and each file in `tests/` is a different crate, so the call fails with E0603 exactly like a private item. Test it from a unit test inside `src/`, or make it part of the public API if callers genuinely need it.
  • A helper in src/lib.rs is marked #[cfg(test)] pub fn fixture(); why can tests/api.rs not find it?
    For integration tests Cargo builds the library as an ordinary crate without `cfg(test)`, so the helper is configured out. rustc reports E0425 with a note that it found an item that was configured out. Shared integration helpers live under `tests/` instead, for example in `tests/common/mod.rs`.
  • Why do some Rust projects keep integration tests in one test target instead of many files?
    Every top-level file in `tests/` links its own executable, and Cargo runs those executables one after another. With dozens of files, linking dominates build time. Putting the tests in modules of a single target, such as `tests/integration/main.rs` with `mod` files beside it, links once and lets the harness run all of them in parallel.

An integration test is a customer at the counter: it can order only what is on the menu, the library's pub items. A unit test works in the kitchen and can reach the private shelves.

  • Files in tests/ need #[cfg(test)] around their code, just like unit test modules.
  • Integration tests can reach private functions with use super::*.
  • All files in tests/ are compiled together into one test crate.
  • A #[cfg(test)] helper in src/ is visible to integration tests because cargo test sets cfg(test).
  • pub(crate) items are callable from tests/ because the tests belong to the same package.