Skip to content
Tutorials Center
My learning

Topics

Lesson 97 of 132 ยท Testing and Tooling

Test Patterns: Fixtures, Doc Tests and Property Tests

Learn practical Rust test patterns: doc tests, helper fixtures, table-driven tests, a hand-rolled property tester with shrinking, snapshot tests and mocking with traits.

Knowing #[test] and assert_eq! gets you started. Real test suites need patterns that keep tests short, readable and powerful as the code grows: shared setup, many cases without copy-paste, examples that cannot go stale, tests that explore inputs you would never think of, and ways to test code that talks to the clock, the network or the disk.

This lesson covers six patterns: helper functions and fixtures, table-driven tests, doc tests, property-based tests, snapshot tests and mocking with traits. As in the previous lesson, our editor does not run cargo test, so the real syntax is shown in read-only blocks and every idea has a runnable version. The runnable ones use a very small helper: a function that runs a closure, catches a panic and prints PASS or FAIL.

Rust The tiny harness used in this lesson

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

In a real project you would not write this; cargo test does it for you. Each snippet below shows what you would put inside a #[test] function.

Pattern 1: helper functions and fixtures

A fixture is the prepared world a test needs: a sample user, a populated list, a temporary folder. Repeating the setup in every test hides what each test is about. Extract it into a helper function with sensible defaults, then change only the field that matters.

Rust Test helpers and a Drop-based fixture

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

What makes this pattern work:

  • User { admin: true, ..sample_user() } (struct update syntax) states only the interesting difference. A reader sees at once that the test is about admin.
  • A fixture with a Drop implementation (the RAII idea from Drop and RAII) cleans up even when an assertion panics, because unwinding runs destructors. That is the Rust answer to the setUp/tearDown pairs of other frameworks. There is no special hook: the guard variable's lifetime is the fixture's lifetime.
  • In real projects the tempfile crate gives you directories and files that delete themselves when dropped. Never use one fixed path like /tmp/test.txt: tests run in parallel and would overwrite each other.
  • Shared helpers for integration tests go in tests/common/mod.rs, as described in the previous lesson. For helpers used by unit tests, a #[cfg(test)] mod helpers inside the crate is enough.

Pattern 2: table-driven tests

When one function has many input/output cases, avoid writing twenty near-identical test functions. Put the cases in an array of tuples and loop. This is the default style for parsers, validators and math helpers.

Rust A table of cases with useful failure messages

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

In a real #[test], put the context in the assertion message so a failure names the exact case:

Rust
// Read-only: the same table inside a real test.
#[test]
fn leap_years() {
    let cases = [(2024, true), (1900, false), (2000, true)];
    for (year, expected) in cases {
        assert_eq!(is_leap_year(year), expected, "year {year}");
    }
}

A plain loop stops at the first failing case. If you want every failure reported at once, collect the failures in a Vec and assert it is empty at the end, as the runnable demo does by counting. Crates such as rstest and test-case generate one separate named test per row if you prefer that.

Document why each row exists. A table of unexplained numbers is hard to maintain; a table where each row states its edge case doubles as documentation.

Pattern 3: doc tests

Rust compiles and runs the code examples inside your documentation comments as tests. Your docs can never silently go out of date: if an example stops compiling or its assertions fail, cargo test fails. Examples go inside triple-backtick blocks in /// comments (read-only; doc tests run only for library crates):

Rust
/// Splits a "key=value" pair at the first `=`.
///
/// # Examples
///
/// ```
/// use my_crate::split_pair;
///
/// assert_eq!(split_pair("color=red"), Some(("color", "red")));
/// assert_eq!(split_pair("no equals sign"), None);
/// ```
///
/// A value may itself contain `=`:
///
/// ```
/// # use my_crate::split_pair;
/// assert_eq!(split_pair("a=b=c"), Some(("a", "b=c")));
/// ```
pub fn split_pair(text: &str) -> Option<(&str, &str)> {
    text.split_once('=')
}

Things to know:

  • Each block is compiled as a separate tiny program, with the body wrapped in fn main() { ... } and your crate available by name. It checks the public API exactly as a user would call it.
  • A line starting with # (hash and space) is hidden in the rendered documentation but still compiled. Use it for use lines and setup that would distract the reader, as in the second example.
  • To use ?, end the block with # Ok::<(), Box<dyn std::error::Error>>(()) or write fn main() -> Result<...> explicitly.
  • Fences can carry attributes: ```no_run compiles but does not run (for example network code), ```ignore skips it, ```should_panic expects a panic, ```compile_fail asserts that the code does not compile. The last one is wonderful for documenting that the type system rejects misuse.
  • cargo test --doc runs only doc tests.

Because doc tests are slower (every block is its own compilation), use them for examples that teach the reader, and keep edge cases in ordinary unit tests.

Pattern 4: property-based tests

An example-based test says "for this input, expect that output". A property test says "for any input, this statement is always true", and the framework generates hundreds of random inputs to try to break it. Typical properties:

  • Round trip: decode(encode(x)) == x
  • Idempotence: sorting an already sorted list changes nothing
  • Invariants: the result of sort has the same length and is ordered
  • Oracle: a fast implementation agrees with a slow, obviously correct one

When a property fails, good tools shrink the failing input to the smallest one that still fails, so you debug a 3-element list instead of a 300-element one.

The proptest and quickcheck crates do this for you (read-only here; they come from crates.io):

Rust
// Read-only: requires the proptest crate in [dev-dependencies].
use proptest::prelude::*;

proptest! {
    #[test]
    fn reversing_twice_is_identity(v in proptest::collection::vec(any::<i32>(), 0..100)) {
        let mut copy = v.clone();
        copy.reverse();
        copy.reverse();
        prop_assert_eq!(copy, v);
    }

    #[test]
    fn sort_keeps_length_and_orders(mut v in proptest::collection::vec(any::<i32>(), 0..100)) {
        let len = v.len();
        v.sort();
        prop_assert_eq!(v.len(), len);
        prop_assert!(v.windows(2).all(|w| w[0] <= w[1]));
    }
}

Now we build the idea ourselves, small enough to read in one sitting. It has a seeded random generator (the same trick from Randomness, Hashing and Math, so failures are reproducible), a check function that tries many random inputs, and a simple shrinker. The code under test is a run-length encoder with a deliberate bug: its decoder reads only one digit for the run length, so runs of 10 or more break. Hand-written examples rarely contain a run of ten; a property test finds it quickly.

Rust A property tester with shrinking

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Read the output carefully. The first property passes. The round-trip property fails on run 12 with a string of 15 identical characters, and the shrinker reduces it to the smallest failing case: ten identical characters, encoded as "10a" and decoded as "0". Ten is exactly the boundary where the count needs two digits. A bug report that says "runs of 10 or more break" is far more useful than a random 28-character string.

Techniques worth stealing:

  • Seed and print. A failure you cannot reproduce is worthless. Print the seed, or fix it as here. Real tools save failing seeds in a file and replay them.
  • Generate interesting data. We used an alphabet of two letters on purpose, so long runs happen often. Uniformly random bytes would almost never produce a run of ten.
  • Shrink. Without shrinking, property tests produce noisy counterexamples.
  • To fix the bug, make the decoder read all the digits before the character, then run the property again. Properties also protect the fix later.

Pattern 5: snapshot tests

A snapshot test compares a complex output (a report, a rendered page, a pretty-printed syntax tree) with a stored expected text. Writing the expected string by hand for 30 lines of output is tedious and error-prone; snapshot tools write it for you the first time and flag any later difference for review.

The idea in its simplest form needs only a multi-line string literal and a helpful comparison:

Rust A snapshot comparison with a line diff

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

With the insta crate (read-only) the stored text lives in a snapshot file or inline, and a review command shows a diff and lets you accept intended changes:

Rust
// Read-only: requires the insta crate.
#[test]
fn invoice_looks_right() {
    let report = render_invoice(&sample_items());
    insta::assert_snapshot!(report);
}
Terminal
# Read-only: shell commands from a real project
cargo insta test      # run tests and collect changed snapshots
cargo insta review    # step through the diffs; accept or reject each

Snapshots are excellent for large structured output and weak when blindly accepted: if people press "accept all" without reading, a snapshot test asserts nothing. Keep snapshots small and free of volatile data (timestamps, random IDs, absolute paths), and review each diff like code.

Pattern 6: mocking with traits

Code that calls the real clock, network or database is hard to test: the results change, it is slow, and it may have side effects. The Rust answer is dependency injection with traits. The code under test depends on a trait; production passes the real implementation, and tests pass a fake that you control and inspect. No mocking framework is needed for most cases.

We test a reminder service that must not send mail outside working hours. It needs the time (a Clock) and a way to send (a Mailer):

Rust Fake clock and recording mailer

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Choices explained:

  • The service takes &dyn Clock and &dyn Mailer (trait objects); generic parameters (struct ReminderService<C: Clock, M: Mailer>) work equally well and avoid dynamic dispatch. Use generics when performance matters and trait objects when you want simpler types.
  • The mailer is a recording fake: it stores calls in a RefCell so a &self method can still record. That lets the test assert on what was sent, not just on the return value. See RefCell and Cell.
  • A fixed clock makes "9 to 6" logic testable at any hour. Never call SystemTime::now() deep inside logic you want to test.
  • The failing mailer tests the error path, which real servers rarely let you trigger on demand.

For very large traits the mockall crate (read-only) generates mock structs with expectations such as "send was called once with these arguments", at the cost of more macro magic. Prefer hand-written fakes while they stay short; they are plain Rust and easy to debug.

Mock at the boundaries of your program (time, network, filesystem, database) and keep the logic between them pure. If you find yourself mocking five internal collaborators to test one function, the design is the problem, not the test.

Choosing a pattern

Situation Pattern
Many similar setups Helper functions, struct update syntax
Resources that need cleanup RAII guard with Drop, tempfile
One function, many inputs Table-driven test
Public API examples Doc test
"For all inputs, X holds" Property test
Large formatted output Snapshot test
Time, network, disk, randomness Trait + fake

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What is the main advantage of a doc test?

    cargo test compiles the code blocks in /// comments, so a stale or broken example fails the test run.
  2. 2. In a doc test, what does a line that starts with # do?

    Hidden lines keep boilerplate such as use statements out of the docs while still compiling them.
  3. 3. What does shrinking do in a property-based test?

    After finding a failing input the framework simplifies it, so you debug a minimal counterexample instead of a large random one.
  4. 4. How do you make code that depends on the current time easy to test?

    Dependency injection through a trait lets production use the real clock and tests use a deterministic one.
  5. 5. Why does a Drop-based fixture clean up even when an assertion fails?

    A panic unwinds the stack, dropping local variables in order. A guard value's Drop implementation therefore runs on both success and failure.

Summary

  • Extract setup into helper functions and use struct update syntax so each test shows only what is special about it.
  • Use RAII guards with Drop (or the tempfile crate) for fixtures that need cleanup; panics still run destructors.
  • Table-driven tests loop over a list of cases; put the reason and the input in assertion messages.
  • Doc tests compile and run examples in /// comments; # hides boilerplate, and fence attributes such as no_run and compile_fail control behavior.
  • Property tests check "for all inputs" statements with random data; seeds and shrinking make failures reproducible and small. proptest and quickcheck are the real tools.
  • Snapshot tests compare big outputs with stored text; review every diff.
  • Mock boundaries by depending on traits and passing fakes; hand-written recording fakes are often enough.

Next: Debugging, Logging and Diagnostics