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