Testing Strategy
Core Question
What is the right test boundary for this behavior, and how
should the test be structured for maintainability?
Unit tests verify internal logic in isolation. Integration
tests verify that public API contracts hold when components
work together. Choosing wrong leads to either brittle tests
that break on refactoring (too-low boundary) or slow, opaque
tests that don't pinpoint failures (too-high boundary).
Quick Decisions
| Situation |
Reach For |
Why |
| Pure function with clear inputs/outputs |
Unit test |
Fast, precise, no setup needed |
| Private helper with tricky logic |
Unit test via use super::* |
Test the logic directly, not through layers of indirection |
| Public API contract |
Integration test in tests/ |
Proves the API works as consumers will use it |
| Error path or edge case |
Unit test per error variant |
Exhaustive, fast, catches regressions early |
| Complex setup shared across tests |
Test builder or helper function |
DRY without sacrificing clarity |
| Multiple inputs, same logic |
Macro-generated parameterized tests |
Covers variants without copy-paste |
| Binary crate behavior |
Integration test with Command |
Tests the actual CLI interface end-to-end |
| Database or file system interaction |
Integration test with isolation |
Real dependencies need real cleanup strategies |
| Documenting usage for library consumers |
Doctest |
Tested documentation stays accurate |
| Roundtrip or invariant properties |
Property test (see rust-quality) |
Finds edge cases humans miss |
| Mock-heavy test getting complex |
Reconsider the design |
Too many mocks signals a wrong abstraction boundary |
Key Principles
Test behavior, not implementation. Tests that mirror
internal structure break on every refactor. Test what the
function promises, not how it delivers.
Unit tests are fast and precise. If a unit test needs
a database, a network, or five seconds to run, it is an
integration test in disguise. Move it.
Integration tests prove contracts. They exercise the
public API as a consumer would. Failures here mean you
shipped a breaking change.
Error paths need tests too. Every Result::Err variant
and every None return should have at least one test.
Error paths are where bugs hide because they are where
developers look last.
Test names are documentation. parse_rejects_empty_input
tells you what broke. test_parse_3 does not. Pattern:
function_condition_expected.
Shared setup belongs in helpers, not copy-pasted. Extract
builders and factory functions into the test module. Repeated
arrange blocks drift apart and obscure the actual test logic.
One assertion per concept. A test can have multiple
assert! calls if they verify one logical thing. Unrelated
assertions belong in separate tests so failures are specific.
Tests own their data. Never depend on test execution
order. Never share mutable state between tests without
explicit isolation. Cargo runs tests in parallel by default.
Usage Scenarios
Scenario 1: "I'm adding tests to existing code with no
coverage"
-> Start with integration tests for the public API to establish
a safety net. Then add unit tests for complex internal logic.
Integration tests catch the most breakage with the least
knowledge of internals. Unit tests follow once you understand
the code well enough to identify tricky logic worth testing
directly.
Scenario 2: "My test suite is slow and I don't know why"
-> Profile with cargo test --lib (unit only) vs
cargo test --test '*' (integration only). If unit tests are
slow, they are likely touching the filesystem or network — move
those to integration tests. If integration tests are slow,
look for missing isolation (shared databases, serial locks).
Scenario 3: "I have 50 test functions in one module and
it's hard to navigate"
-> Nest submodules inside mod tests: group by behavior
(mod validation, mod parsing, mod error_cases). Each
submodule gets use super::* from the parent test module.
Tests become module::tests::validation::rejects_empty_input.
Scenario 4: "I need to test a CLI binary that reads stdin
and writes files"
-> Use std::process::Command or assert_cmd in integration
tests. Create TempDir for file output. Assert on exit code,
stdout, and stderr. Never test CLI behavior through library
unit tests — test the actual binary.
Reference Index
| Reference |
Read When |
| references/unit-tests.md |
Writing unit tests: module organization, private function testing, error paths, test builders, parameterized tests, feature flags, test filtering |
| references/integration-tests.md |
Writing integration tests: tests/ directory structure, shared utilities, binary testing, real dependencies, isolation, snapshots, workspaces |
Cross-References
| When |
Check |
| Property-based testing with proptest |
rust-quality → Quick Decisions |
| Mocking with mockall, trait extraction |
rust-quality → Quick Decisions |
| Benchmarking with criterion |
rust-quality → Quick Decisions |
Async test patterns (#[tokio::test]) |
rust-async → Quick Decisions |
| Error type design affecting test assertions |
rust-errors → Quick Decisions |
| Project structure and test file placement |
rust-architecture → Quick Decisions |
1---2name: rust-tests3description: Rust unit and integration test strategy — when to write which kind of test, how to structure test modules, test helpers and builders, error path testing, parameterized tests, integration test organization, binary crate testing, and test isolation. Use when deciding between unit and integration tests, organizing a growing test suite, testing error paths, setting up shared test utilities, or structuring the tests/ directory for a workspace. Also use when tests are slow, brittle, or hard to navigate.4---56# Testing Strategy78## Core Question910**What is the right test boundary for this behavior, and how11should the test be structured for maintainability?**1213Unit tests verify internal logic in isolation. Integration14tests verify that public API contracts hold when components15work together. Choosing wrong leads to either brittle tests16that break on refactoring (too-low boundary) or slow, opaque17tests that don't pinpoint failures (too-high boundary).1819---2021## Quick Decisions2223| Situation | Reach For | Why |24| --------------------------------------- | ----------------------------------- | ---------------------------------------------------------- |25| Pure function with clear inputs/outputs | Unit test | Fast, precise, no setup needed |26| Private helper with tricky logic | Unit test via `use super::*` | Test the logic directly, not through layers of indirection |27| Public API contract | Integration test in `tests/` | Proves the API works as consumers will use it |28| Error path or edge case | Unit test per error variant | Exhaustive, fast, catches regressions early |29| Complex setup shared across tests | Test builder or helper function | DRY without sacrificing clarity |30| Multiple inputs, same logic | Macro-generated parameterized tests | Covers variants without copy-paste |31| Binary crate behavior | Integration test with `Command` | Tests the actual CLI interface end-to-end |32| Database or file system interaction | Integration test with isolation | Real dependencies need real cleanup strategies |33| Documenting usage for library consumers | Doctest | Tested documentation stays accurate |34| Roundtrip or invariant properties | Property test (see rust-quality) | Finds edge cases humans miss |35| Mock-heavy test getting complex | Reconsider the design | Too many mocks signals a wrong abstraction boundary |3637---3839## Key Principles40411. **Test behavior, not implementation.** Tests that mirror42 internal structure break on every refactor. Test what the43 function promises, not how it delivers.44452. **Unit tests are fast and precise.** If a unit test needs46 a database, a network, or five seconds to run, it is an47 integration test in disguise. Move it.48493. **Integration tests prove contracts.** They exercise the50 public API as a consumer would. Failures here mean you51 shipped a breaking change.52534. **Error paths need tests too.** Every `Result::Err` variant54 and every `None` return should have at least one test.55 Error paths are where bugs hide because they are where56 developers look last.57585. **Test names are documentation.** `parse_rejects_empty_input`59 tells you what broke. `test_parse_3` does not. Pattern:60 `function_condition_expected`.61626. **Shared setup belongs in helpers, not copy-pasted.** Extract63 builders and factory functions into the test module. Repeated64 arrange blocks drift apart and obscure the actual test logic.65667. **One assertion per concept.** A test can have multiple67 `assert!` calls if they verify one logical thing. Unrelated68 assertions belong in separate tests so failures are specific.69708. **Tests own their data.** Never depend on test execution71 order. Never share mutable state between tests without72 explicit isolation. Cargo runs tests in parallel by default.7374---7576## Usage Scenarios7778**Scenario 1:** "I'm adding tests to existing code with no79coverage"80-> Start with integration tests for the public API to establish81a safety net. Then add unit tests for complex internal logic.82Integration tests catch the most breakage with the least83knowledge of internals. Unit tests follow once you understand84the code well enough to identify tricky logic worth testing85directly.8687**Scenario 2:** "My test suite is slow and I don't know why"88-> Profile with `cargo test --lib` (unit only) vs89`cargo test --test '*'` (integration only). If unit tests are90slow, they are likely touching the filesystem or network — move91those to integration tests. If integration tests are slow,92look for missing isolation (shared databases, serial locks).9394**Scenario 3:** "I have 50 test functions in one module and95it's hard to navigate"96-> Nest submodules inside `mod tests`: group by behavior97(`mod validation`, `mod parsing`, `mod error_cases`). Each98submodule gets `use super::*` from the parent test module.99Tests become `module::tests::validation::rejects_empty_input`.100101**Scenario 4:** "I need to test a CLI binary that reads stdin102and writes files"103-> Use `std::process::Command` or `assert_cmd` in integration104tests. Create `TempDir` for file output. Assert on exit code,105stdout, and stderr. Never test CLI behavior through library106unit tests — test the actual binary.107108---109110## Reference Index111112| Reference | Read When |113| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |114| [references/unit-tests.md][unit] | Writing unit tests: module organization, private function testing, error paths, test builders, parameterized tests, feature flags, test filtering |115| [references/integration-tests.md][integ] | Writing integration tests: tests/ directory structure, shared utilities, binary testing, real dependencies, isolation, snapshots, workspaces |116117[unit]: references/unit-tests.md118[integ]: references/integration-tests.md119120---121122## Cross-References123124| When | Check |125| ------------------------------------------- | ----------------------------------- |126| Property-based testing with proptest | rust-quality → Quick Decisions |127| Mocking with mockall, trait extraction | rust-quality → Quick Decisions |128| Benchmarking with criterion | rust-quality → Quick Decisions |129| Async test patterns (`#[tokio::test]`) | rust-async → Quick Decisions |130| Error type design affecting test assertions | rust-errors → Quick Decisions |131| Project structure and test file placement | rust-architecture → Quick Decisions |
dawidpereira