skip to content

Why does a Rust helper file tests/common.rs run as its own integration-test target, and how does tests/common/mod.rs avoid that?

level: middleimportance: should knowfreq 40%

answer

  1. what Cargo auto-discovers
  2. running 0 tests
  3. subdirectories are not targets
  4. mod common; in every file

basics

~20 s

Cargo builds every top-level .rs file in tests/ as an integration-test crate, so common.rs runs alone and reports 0 tests. tests/common/mod.rs sits in a subdirectory, so it is only a module that test files include with mod common;.

solid answer

~40 s

Cargo auto-discovers `tests/*.rs` and `tests/*/main.rs` as test targets. A helper file at `tests/common.rs` is therefore compiled as its own crate and shows up as `Running tests/common.rs` with `running 0 tests`. Moving it to `tests/common/mod.rs` takes it out of discovery; each test file that wants it writes `mod common;` and calls `common::sample_lines()`. Every test crate compiles its own copy of that module, so a helper one file never calls triggers a `dead_code` warning attributed to that test target. Silence it with `#[allow(dead_code)]` on the `mod common;` line, or split helpers by use. For one large test, `tests/scenarios/main.rs` plus sibling module files makes a single multi-file target.

code

plaintext · 11 lines
plaintext
logfilter/
├── Cargo.toml
├── src/
│   ├── lib.rs
│   └── main.rs
└── tests/
    ├── api.rs
    ├── cli.rs
    ├── report.rs
    └── common/
        └── mod.rs

go deeper

for a junior

Remember that each file directly in tests/ becomes a test target, so shared helpers go in tests/common/mod.rs and are pulled in with mod common;.

for a middle

Explain Cargo's discovery rule, tests/.rs and tests//main.rs, and why each test crate compiles its own copy of the helper module.

for a senior

Diagnose the per-crate dead_code warning, and pick between a helper module, a multi-file test target and a dev-dependency support crate as the suite grows.

for a principal

Weigh how test layout shapes build time and ownership of fixtures, and when shared helpers deserve their own crate.

## How Cargo finds integration tests Cargo builds targets it **discovers** from the file layout. For integration tests the discovery rule covers two shapes: - **`tests/<name>.rs`** — a single-file integration test, compiled as its own crate. - **`tests/<name>/main.rs`** — a multi-file integration test whose other files are modules of that one crate. Nothing else under `tests/` is discovered as a target. Each discovered target is a separate crate linked against the package's library, with its own section in the `cargo test` output. ## Why tests/common.rs misbehaves A team writing a log-filtering tool wants a fixture shared by `tests/api.rs`, `tests/report.rs` and `tests/cli.rs`. The obvious move is a file `tests/common.rs` with `pub fn sample_lines()`. Because it sits directly in `tests/`, Cargo discovers it as one more integration test: - it is compiled as **its own crate**, though nothing in it is a test; - `cargo test` prints `Running tests/common.rs` followed by `running 0 tests`; - it still does not make `common` available to the other files, because each file is a separate crate with its own module tree. The extra target is noise in the output and one more executable to link. ## The tests/common/mod.rs layout Moving the helpers into a subdirectory changes their role: 1. Create `tests/common/mod.rs` and put the shared items in it, marked `pub`. 2. In each test file that needs them, declare `mod common;` near the top. 3. Call them as `common::sample_lines()` or `common::SAMPLE`. Because `tests/common/` has no `main.rs`, Cargo does not discover it, and the `Running tests/common.rs` section disappears. The file is found the way any `mod` declaration finds a file: the path rules belong to the material on modules. Here the `mod.rs` spelling is what keeps the file out of discovery while still letting `mod common;` find it. | Layout | Discovered as a test target? | How other files use it | |---|---|---| | `tests/common.rs` | yes, runs with 0 tests | still needs `mod common;` | | `tests/common/mod.rs` | no | `mod common;` | | `tests/scenarios/main.rs` | yes, one multi-file target | its own modules only | ## One copy per test crate, and the dead_code warning `mod common;` does not share compiled code. Each test crate that declares it **compiles its own copy** of the module, and lints run per crate. If `tests/report.rs` calls `common::sample_lines()` but `tests/cli.rs` only uses `common::SAMPLE`, the `cli` crate sees an unused function: - rustc prints ``warning: function `sample_lines` is never used`` pointing into `tests/common/mod.rs`; - Cargo attributes it to the target that compiled it: `` `logfilter` (test "cli") generated 1 warning ``; - the `report` crate, which does call it, produces no warning. Common fixes are `#[allow(dead_code)]` on the `mod common;` line in files that use only part of the module, or splitting helpers into smaller modules so each file pulls in what it calls. ## What the output shows With `tests/common.rs` in place, `cargo test` prints a section for it between the other integration tests, along these lines: `Running tests/common.rs (target/debug/deps/common-...)`, then `running 0 tests` and a passing `test result` line. Nothing failed, but a reader skimming the output sees a target that tests nothing, and anyone grepping for failures has one more section to step over. After the move to `tests/common/mod.rs` that section disappears, and the helper code is compiled only inside the test crates that declare `mod common;`. The total number of test executables drops by one, and each remaining one contains exactly the helpers it asked for. ## Choosing a shape for shared test code - **A few helpers, many test files:** `tests/common/mod.rs` with `mod common;` in each file. - **One big suite:** `tests/scenarios/main.rs` with `mod helpers;` beside it gives one target, one link step and parallel execution of every test in it. - **Helpers in `src/` under `#[cfg(test)]`:** these do not reach integration tests, because the library they link is built without `cfg(test)`. - **Helpers shared across several packages:** a separate support crate used as a dev-dependency; that arrangement is Cargo's workspace material.

  • Why does the dead_code warning name the cli test target and not report?
    Each test file that declares `mod common;` compiles its own copy of the module, and lints run per crate. `tests/report.rs` calls `sample_lines()`, so its copy is used; `tests/cli.rs` only reads `SAMPLE`, so its copy of `sample_lines` is dead and Cargo attributes the warning to the `cli` test target.
  • How do you split one large Rust integration test across several files without creating more targets?
    Use the multi-file shape: `tests/scenarios/main.rs` is the crate root and declares `mod helpers;`, which loads `tests/scenarios/helpers.rs`. Cargo discovers only `main.rs` in that directory, so the whole suite is one target with one link step, and the harness runs all its tests in parallel.

  • tests/common.rs is skipped by cargo test because it contains no #[test] functions.
  • Declaring mod common; in one test file makes common available to every other test file.
  • tests/common/mod.rs is compiled once and shared by all the integration-test executables.
  • Helpers under #[cfg(test)] in src/ can be shared with the files in tests/.
  • A dead_code warning from tests/common means the helper is unused by every test file.