rust-testing

Rust Testing

Prefer real implementations and hand-written fakes over heavy mocking — a test wired to a mock asserts how the code calls its collaborators, not what the code does. Tests are documentation that runs: a reader should learn the intended behavior from the test name, the arrange/act/assert shape, and the doctest examples on public items. Test the public contract, not the private call graph.

Route to Reference

• Test layout depth — ${CLAUDE_SKILL_DIR}/references/layout.md Unit vs integration vs doctest mechanics, tests/ crate-per-file model, tests/common/mod.rs shared-helper pattern, binary-crate lib.rs split, doctest attributes (no_run, should_panic, ignore, hidden # lines), assert_matches! and pretty_assertions usage
• Property and snapshot testing, benchmarks — ${CLAUDE_SKILL_DIR}/references/property-and-snapshot.md proptest vs quickcheck strategy authoring and shrinking, insta inline/file snapshots and cargo insta review, criterion harness setup and std::hint::black_box
• Mocking and fixtures — ${CLAUDE_SKILL_DIR}/references/mocking-and-fixtures.md mockall #[automock] vs mock!, predicates and call counts, the trait-seam pattern for in-memory fakes, rstest #[case]/#[fixture] params, serial_test, assert_cmd + predicates for CLI integration
• Async tests — ${CLAUDE_SKILL_DIR}/references/async-tests.md #[tokio::test] flavors, tokio::time::pause/ advance for deterministic timers, tokio-test macros; cross-references the rust skill async reference for runtime semantics
• Pinned crate versions — ${CLAUDE_SKILL_DIR}/references/versions.md date-stamped dev-dependency versions for the testing ecosystem crates ("as of 2026-06")

Read the relevant reference before writing non-trivial tests in that area.

Test Layout

• Place unit tests in a #[cfg(test)] mod tests block in the same file as the code under test; bring the parent into scope with use super::*. #[cfg(test)] keeps test code (and its helpers) out of the build artifact.
• Use unit tests to exercise private items — Rust's privacy rules let a child tests module reach its ancestors, so testing internals is possible. Reserve this for genuinely tricky private logic; prefer driving private code through the public API.
• Place integration tests in the top-level tests/ directory, next to src/. Cargo compiles each file as its own crate, so they reach only the public API via use my_crate::... — exactly as an external consumer would.
• Share integration-test helpers from tests/common/mod.rs, not tests/common.rs. The mod.rs form is not compiled as a separate test crate, so it produces no spurious empty "running 0 tests" section. Import it with mod common;.
• For a binary crate, keep main.rs a thin shell that calls into lib.rs; integration tests then exercise the library crate, since only library crates expose items to external use.
• Write doctests as /// examples on public items. They double as compiled documentation and run under cargo test --doc. Hide setup lines with a leading # and use ```no_run for examples that must compile but not run.