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

Priority Category Impact Prefix

1 Test Organization CRITICAL org-

2 Mocking and Test Doubles CRITICAL mock-

3 Async Testing HIGH async-

4 Property-Based Testing HIGH prop-

5 Test Fixtures and Setup MEDIUM fix-

6 Assertions and Error Testing MEDIUM assert-

7 CI Integration MEDIUM ci-

8 Test Performance LOW-MEDIUM perf-

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

File Description

references/_sections.md Category definitions and ordering

assets/templates/_template.md Template for new rules

metadata.json Version and reference information