Rust Testing Tools

Code Coverage

Projects SHOULD measure code coverage. cargo-llvm-cov¹ SHOULD be the default; cargo-tarpaulin² MAY be used where its report formats are required.

Fuzzing: cargo-fuzz

Projects handling untrusted input SHOULD use fuzzing. cargo-fuzz³ SHOULD be the default choice.

Platform Requirements

cargo-fuzz drives libFuzzer⁴, which needs LLVM sanitizer support. Projects MUST confirm the environment before adopting it:

Requirement	Supported
Architecture	x86-64 and AArch64 only
Operating system	Unix-like only — not Windows
Toolchain	nightly, because the flags it passes are unstable
Host tooling	a C++ compiler with C++11 support

Why: these are libFuzzer’s constraints, not cargo-fuzz’s, and they are not detected until link time. A Windows CI job added to a fuzzing matrix fails after the whole dependency tree has been built. Fuzzing jobs MUST be restricted to Linux or macOS runners.³

Fuzzing in CI

The nightly toolchain MUST be pinned by date, the corpus MUST be persisted between runs, and crash artifacts MUST be uploaded.

Why: an unpinned +nightly makes the job fail on unrelated compiler changes with no diff to explain it. A corpus that is discarded each run restarts coverage exploration from zero, so a scheduled job repeatedly re-finds shallow inputs and never reaches the deep ones. A crash that is not uploaded cannot be reproduced.

jobs:
  fuzz:
    runs-on: ubuntu-latest   # libFuzzer does not support Windows
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8 # v1
        with:
          toolchain: nightly-2026-09-01
      - uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: fuzz/corpus
          key: fuzz-corpus-${{ github.sha }}
          restore-keys: fuzz-corpus-
      - run: cargo install cargo-fuzz --version 0.13.2 --locked
      - run: |
          cargo fuzz run my_target fuzz/corpus/my_target \
            -- -max_total_time=300 -rss_limit_mb=2048
      - if: failure()
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: fuzz-artifacts
          path: fuzz/artifacts

Property Testing

Projects SHOULD state invariants as property tests where a round trip, an ordering, or an algebraic law can be expressed. proptest⁶ SHOULD be used.

Why

An example test asserts one point; a property test asserts a rule over a generated domain and shrinks any counterexample to a minimal failing input, which is usually the whole diagnosis. Round trips, idempotence, and ordering laws are the highest-value candidates because they hold for every input by construction.

[dev-dependencies]
proptest = "1.11.0"  # proptest[^32]

// tests/props.rs
use proptest::prelude::*;

proptest! {
    #[test]
    fn render_then_parse_round_trips(values in prop::collection::vec(any::<u32>(), 0..32)) {
        let text = bench_props::render_list(&values);
        prop_assert_eq!(bench_props::parse_list(&text), Ok(values));
    }
}

Failing cases are written to proptest-regressions/ and MUST be committed, so the shrunk counterexample becomes a permanent regression test.

Mutation Testing

Projects SHOULD run cargo-mutants⁷ to measure whether the test suite actually detects changed behavior.

Why

Coverage says a line ran; it does not say an assertion would have failed had that line been wrong. cargo-mutants replaces function bodies with plausible alternatives and reports the ones the suite still passes with — a missed mutant is a concrete, addressable gap.

cargo install cargo-mutants --version 27.1.0 --locked

cargo mutants --in-diff git.diff   # pull-request scope: only changed code
cargo mutants --package my_crate   # full run, scheduled

A full run is slow because it rebuilds and retests per mutant. Pull requests SHOULD use --in-diff; whole-crate runs SHOULD be scheduled.

Public API Compatibility

Library crates MUST check public API compatibility before publishing. cargo-semver-checks⁸ MUST run in CI for every published library.

Benchmarking

Performance claims MUST be backed by a benchmark harness. Criterion⁹ SHOULD be used.

Test Performance

Test throughput and code performance are separate concerns and MUST NOT be measured with the same tool. --test-threads changes libtest concurrency; it does not measure anything.

Nextest

cargo install cargo-nextest --version 0.9.143 --locked
cargo nextest run --all-features

Nextest¹⁰ runs each test in its own process rather than its own thread, so one test cannot corrupt another’s global state, a panicking test cannot take the runner down with it, and per-test timeouts and retries become possible. Nextest does not run doc tests; cargo test --doc MUST still run separately.

Concurrency Testing with loom

Loom¹¹ MUST be declared as a cfg(loom) target dependency, the model MUST use Loom’s instrumented synchronization types, and the test MUST be run with --cfg loom set.

Why: Loom cannot observe std::sync::atomic or std::thread. It permutes executions only through its own replacements, so a model written against the standard types compiles, runs once, passes, and proves nothing. Declaring the dependency under [target.'cfg(loom)'.dependencies] keeps Loom and its tracing stack out of ordinary cargo test builds, and gating the test file on cfg(loom) means a normal run reports “0 tests” rather than a false pass. Nothing sets --cfg loom for you.¹¹

# Cargo.toml
[target.'cfg(loom)'.dependencies]
loom = "0.7.2"  # loom[^15]

[lints.rust]
unexpected_cfgs = { level = "warn", check-cfg = ['cfg(loom)'] }

Why check-cfg: loom is not a known cfg, so without this declaration every #[cfg(loom)] raises an unexpected_cfgs warning, and under -D warnings the ordinary build fails.

// tests/concurrent.rs
#![cfg(loom)]
#![allow(clippy::unwrap_used, reason = "loom model test")]

use loom::sync::Arc;
use loom::sync::atomic::AtomicUsize;
use loom::sync::atomic::Ordering::{Acquire, Relaxed, Release};
use loom::thread;

#[test]
fn increment_is_atomic() {
    loom::model(|| {
        let num = Arc::new(AtomicUsize::new(0));
        let threads: Vec<_> = (0..2)
            .map(|_| {
                let num = Arc::clone(&num);
                thread::spawn(move || {
                    num.fetch_add(1, Release);
                })
            })
            .collect();

        for t in threads {
            t.join().unwrap();
        }

        assert_eq!(2, num.load(Acquire));
        assert_eq!(2, num.load(Relaxed));
    });
}

# Loom runs nothing unless the cfg is set. --release keeps the permutation
# search tractable.
RUSTFLAGS="--cfg loom" cargo test --test concurrent --release

// BAD: std types, no cfg gate, plain `cargo test`. This runs the closure once,
// explores no interleavings, and passes whatever the code does.
#[test]
fn test_concurrent_safety() {
    loom::model(|| {
        let v1 = std::sync::Arc::new(std::sync::atomic::AtomicUsize::new(0));
        let v2 = v1.clone();
        std::thread::spawn(move || { v1.fetch_add(1, SeqCst); });
        v2.fetch_add(1, SeqCst);
    });
}

Loom does not implement the whole C11 model: SeqCst accesses are treated as AcqRel, which can produce false alarms, and some load-buffering executions are not explored, so a clean Loom run is not a proof.¹¹