writing-rust-tests

Writing Rust Tests

Overview

This is a Cargo workspace (edition 2024). Tests here follow three non-negotiable defaults:

1. #[rstest], not bare #[test]. Every test function is annotated #[rstest], even when it takes no cases yet. This keeps the whole suite uniform and lets any test grow cases without a rewrite.
2. Parametrize with #[case], never duplicate. Two or more test functions that differ only in input/expected values ARE ONE parametrized test. A hand-rolled for loop over inputs IS a parametrized test written wrong.
3. Reach for proptest when the property holds over a whole domain, not just the few points you picked.

Violating the letter of these rules is violating the spirit. "It's only two cases" and "a loop is basically the same" are how the suite rots into scattered, unreadable #[test] functions.

When to Use

• Adding a new function/type and covering it with tests.
• Adding cases to existing tests, or a new crates/<crate>/tests/*.rs integration test.
• The user says "write tests", "add coverage", "test this", or "run the tests".
• You are about to write #[test], a for loop inside a test, or the second near-identical test function.

The Decision

digraph t {
    "What am I testing?" [shape=diamond];
    "Same logic, different inputs?" [shape=diamond];
    "Property true over a whole domain?" [shape=diamond];
    "rstest + #[case] per input" [shape=box];
    "proptest! block" [shape=box];
    "single #[rstest] fn" [shape=box];

    "What am I testing?" -> "Same logic, different inputs?";
    "Same logic, different inputs?" -> "rstest + #[case] per input" [label="yes"];
    "Same logic, different inputs?" -> "Property true over a whole domain?" [label="no"];
    "Property true over a whole domain?" -> "proptest! block" [label="yes"];
    "Property true over a whole domain?" -> "single #[rstest] fn" [label="no"];
}

rstest and proptest are already workspace dev-deps (see crates/hm-common). If a crate needs them, add to its [dev-dependencies].