It also covers the nextest doctest pitfall: cargo nextest run never runs doc-tests, so
cargo test --doc must always be paired alongside it — a green nextest run alone is not
full coverage.
Out of scope: CI pipeline wiring and gate ordering belong to rust-tooling-cicd; non-Rust
test suites are not covered.
Rust Testing & Quality
Agent Workflow (MANDATORY)
Before ANY test work, use TeamCreate to spawn 3 agents:
- explore-codebase - Map existing
tests/, #[cfg(test)], benches/
- research-expert - Verify current nextest/proptest/criterion docs via Context7/Exa
- mcp__context7__query-docs - Check crate-specific API (proptest strategies, criterion groups)
After implementation, run sniper for validation.
Overview
| Test kind |
Location |
Runs the code as |
| Unit |
#[cfg(test)] mod tests inside the source file |
Same crate, sees private items |
| Integration |
tests/*.rs (each file = own crate) |
External consumer, public API only |
| Doc-test |
```rust blocks in /// docs |
Compiled + run as examples |
| Property |
proptest, inside unit or integration |
Generated random inputs + shrinking |
| Benchmark |
benches/*.rs with criterion |
Statistical timing, not correctness |
Critical Rules
- nextest does NOT run doc-tests -
cargo nextest run skips them by design. ALWAYS pair with cargo test --doc. Never treat a green nextest run as full coverage.
- Integration tests see only the public API - if a test needs private items, it belongs in
#[cfg(test)], not tests/.
- Commit
proptest-regressions/ - persisted failing seeds must be under version control so failures are reproducible.
harness = false for criterion benches - required in Cargo.toml, or the built-in bench harness collides.- Mutation testing is a gate, not a smoke test -
cargo mutants is slow; run it in scheduled CI, not on every push.
Architecture
my_crate/
├── src/
│ └── lib.rs # unit tests in #[cfg(test)] + doc-tests in ///
├── tests/
│ └── api.rs # integration tests (public API)
├── benches/
│ └── throughput.rs # criterion, harness = false
└── proptest-regressions/ # committed failing seeds
→ See test-suite.md for the complete example
Reference Guide
Concepts
| Topic |
Reference |
When to Consult |
| Test organization |
test-organization.md |
Deciding unit vs integration vs doc, running with nextest |
| Property & mutation |
property-and-mutation.md |
Adding proptest strategies or cargo-mutants |
Templates
| Template |
When to Use |
| test-suite.md |
Scaffolding unit + integration + doc + proptest |
| criterion-bench.md |
Adding a criterion benchmark |
Quick Reference
Run everything (the correct pair)
cargo nextest run --all-features # unit + integration, fast, parallel
cargo test --doc # doc-tests — NOT covered by nextest
Property test skeleton
use proptest::prelude::*;
proptest! {
#[test]
fn round_trips(n in 0u32..10_000) {
prop_assert_eq!(decode(&encode(n)), n);
}
}
→ See test-suite.md for the full file
Best Practices
DO
- Run
cargo nextest run + cargo test --doc together in every CI gate
- Keep integration tests black-box against the public API
- Start proptest with the cheapest property: "does not panic"
- Name benches by the operation measured, not the function name
DON'T
- Assume nextest covered doc-tests — it never does
- Put timing benchmarks in
#[test] (use criterion in benches/)
- Gitignore
proptest-regressions/ — commit it
- Run
cargo mutants on every push (schedule it instead)
1---2name: rust-testing-quality-23description: Use when writing, organizing, or running Rust tests — unit, integration, doc-tests, proptest, criterion benchmarks, or cargo-mutants. Not for CI pipeline wiring (rust-tooling-cicd).4---56<objective>7This skill covers organizing and running the full Rust test spectrum: unit tests in8#[cfg(test)] modules, integration tests in tests/*.rs against the public API only,9doc-tests compiled from /// examples, property-based testing with proptest (including10committing proptest-regressions/), criterion benchmarks (harness = false), and mutation11testing with cargo-mutants as a scheduled quality gate rather than a per-push check.1213It also covers the nextest doctest pitfall: `cargo nextest run` never runs doc-tests, so14`cargo test --doc` must always be paired alongside it — a green nextest run alone is not15full coverage.1617Out of scope: CI pipeline wiring and gate ordering belong to rust-tooling-cicd; non-Rust18test suites are not covered.19</objective>2021# Rust Testing & Quality2223## Agent Workflow (MANDATORY)2425Before ANY test work, use `TeamCreate` to spawn 3 agents:26271. **explore-codebase** - Map existing `tests/`, `#[cfg(test)]`, `benches/`282. **research-expert** - Verify current nextest/proptest/criterion docs via Context7/Exa293. **mcp__context7__query-docs** - Check crate-specific API (proptest strategies, criterion groups)3031After implementation, run **sniper** for validation.3233---3435## Overview3637| Test kind | Location | Runs the code as |38|-----------|----------|------------------|39| **Unit** | `#[cfg(test)] mod tests` inside the source file | Same crate, sees private items |40| **Integration** | `tests/*.rs` (each file = own crate) | External consumer, public API only |41| **Doc-test** | ` ```rust ` blocks in `///` docs | Compiled + run as examples |42| **Property** | proptest, inside unit or integration | Generated random inputs + shrinking |43| **Benchmark** | `benches/*.rs` with criterion | Statistical timing, not correctness |4445---4647## Critical Rules48491. **nextest does NOT run doc-tests** - `cargo nextest run` skips them by design. ALWAYS pair with `cargo test --doc`. Never treat a green nextest run as full coverage.502. **Integration tests see only the public API** - if a test needs private items, it belongs in `#[cfg(test)]`, not `tests/`.513. **Commit `proptest-regressions/`** - persisted failing seeds must be under version control so failures are reproducible.524. **`harness = false` for criterion benches** - required in `Cargo.toml`, or the built-in bench harness collides.535. **Mutation testing is a gate, not a smoke test** - `cargo mutants` is slow; run it in scheduled CI, not on every push.5455---5657## Architecture5859```60my_crate/61├── src/62│ └── lib.rs # unit tests in #[cfg(test)] + doc-tests in ///63├── tests/64│ └── api.rs # integration tests (public API)65├── benches/66│ └── throughput.rs # criterion, harness = false67└── proptest-regressions/ # committed failing seeds68```6970→ See [test-suite.md](references/templates/test-suite.md) for the complete example7172---7374## Reference Guide7576### Concepts7778| Topic | Reference | When to Consult |79|-------|-----------|-----------------|80| **Test organization** | [test-organization.md](references/test-organization.md) | Deciding unit vs integration vs doc, running with nextest |81| **Property & mutation** | [property-and-mutation.md](references/property-and-mutation.md) | Adding proptest strategies or cargo-mutants |8283### Templates8485| Template | When to Use |86|----------|-------------|87| [test-suite.md](references/templates/test-suite.md) | Scaffolding unit + integration + doc + proptest |88| [criterion-bench.md](references/templates/criterion-bench.md) | Adding a criterion benchmark |8990---9192## Quick Reference9394### Run everything (the correct pair)9596```bash97cargo nextest run --all-features # unit + integration, fast, parallel98cargo test --doc # doc-tests — NOT covered by nextest99```100101### Property test skeleton102103```rust104use proptest::prelude::*;105106proptest! {107 #[test]108 fn round_trips(n in 0u32..10_000) {109 prop_assert_eq!(decode(&encode(n)), n);110 }111}112```113114→ See [test-suite.md](references/templates/test-suite.md) for the full file115116---117118## Best Practices119120### DO121- Run `cargo nextest run` + `cargo test --doc` together in every CI gate122- Keep integration tests black-box against the public API123- Start proptest with the cheapest property: "does not panic"124- Name benches by the operation measured, not the function name125126### DON'T127- Assume nextest covered doc-tests — it never does128- Put timing benchmarks in `#[test]` (use criterion in `benches/`)129- Gitignore `proptest-regressions/` — commit it130- Run `cargo mutants` on every push (schedule it instead)
fusengine