Rust Testing Best Practices

Comprehensive testing guide for Rust applications, covering CLI testing, library testing, async patterns, and CI integration. Contains 42 rules across 8 categories, prioritized by impact to guide test design, mocking strategies, and CI optimization.

When to Apply

Reference these guidelines when:

• Writing unit tests for Rust libraries or modules
• Creating integration tests for CLI applications
• Setting up mocking with mockall or trait-based design
• Testing async code with Tokio
• Configuring CI pipelines for Rust projects

Rule Categories by Priority

Quick Reference

1. Test Organization (CRITICAL)

• org-unit-test-modules – Use cfg(test) modules for unit tests
• org-integration-tests-directory – Place integration tests in tests directory
• org-shared-test-utilities – Use tests/common/mod.rs for shared utilities
• org-binary-crate-pattern – Extract logic from main.rs into lib.rs
• org-test-naming – Name tests after behavior not implementation
• org-test-cli-with-assert-cmd – Use assert_cmd for CLI testing

2. Mocking and Test Doubles (CRITICAL)

• mock-trait-based-design – Design for testability with traits
• mock-automock-attribute – Use mockall automock for complex mocking
• mock-avoid-mocking-owned-types – Avoid mocking types you own
• mock-expect-call-counts – Verify mock call counts explicitly
• mock-predicate-arguments – Use predicates to verify mock arguments
• mock-returning-sequences – Use sequences for multiple return values
• mock-static-methods – Use mock! macro for static methods

3. Async Testing (HIGH)

• async-tokio-test-macro – Use tokio::test for async test functions
• async-time-control – Use paused time for timeout testing
• async-mock-io – Use tokio_test for mocking async IO
• async-spawn-blocking – Test spawn_blocking with multi-threaded runtime
• async-test-channels – Use channels for testing async communication

4. Property-Based Testing (HIGH)

• prop-proptest-basics – Use proptest for property-based testing
• prop-custom-strategies – Create custom strategies for domain types
• prop-shrinking – Use shrinking to find minimal failing cases
• prop-invariant-testing – Test invariants instead of specific values

5. Test Fixtures and Setup (MEDIUM)

• fix-rstest-fixtures – Use rstest fixtures for test setup
• fix-rstest-parametrized – Use rstest case for parameterized tests
• fix-temp-directories – Use TempDir for file system tests
• fix-test-context – Use test-context for setup and teardown
• fix-once-cell-shared-state – Use OnceCell for expensive shared setup

6. Assertions and Error Testing (MEDIUM)

• assert-specific-errors – Assert specific error types not just is_err
• assert-should-panic – Use should_panic for panic testing
• assert-debug-display – Implement Debug for clear failure messages
• assert-custom-messages – Add context to assertions with custom messages
• assert-floating-point – Use approximate comparison for floating point
• assert-collection-contents – Assert collection contents not just length

7. CI Integration (MEDIUM)

• ci-cargo-nextest – Use cargo-nextest for faster CI
• ci-caching – Cache Cargo dependencies in CI
• ci-test-isolation – Ensure test isolation in parallel CI
• ci-coverage – Generate coverage reports in CI

8. Test Performance (LOW-MEDIUM)

• perf-compile-time – Reduce test compilation time
• perf-test-filtering – Filter tests for faster feedback loops
• perf-avoid-io-in-unit-tests – Avoid real IO in unit tests
• perf-parallel-test-execution – Configure parallel test threads
• perf-benchmark-critical-paths – Benchmark critical paths with Criterion

How to Use

Read individual reference files for detailed explanations and code examples:

• Section definitions – Category structure and impact levels
• Rule template – Template for adding new rules

Reference Files