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, spawn 3 agents in parallel, one Agent call each with a name:
- fuse-ai-pilot:explore-codebase - Map existing
tests/, #[cfg(test)], benches/
- fuse-ai-pilot: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 fuse-ai-pilot: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-quality3description: 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).4versions:5 cargo-nextest: "0.9"6 proptest: "1"7 criterion: "0.5"8user-invocable: false9references: references/test-organization.md, references/property-and-mutation.md, references/templates/test-suite.md, references/templates/criterion-bench.md10related-skills: solid-rust, rust-tooling-cicd11metadata:12 source: https://skillmd.com/skills/fusengine/rust-testing-quality13---1415<objective>16This skill covers organizing and running the full Rust test spectrum: unit tests in17#[cfg(test)] modules, integration tests in tests/*.rs against the public API only,18doc-tests compiled from /// examples, property-based testing with proptest (including19committing proptest-regressions/), criterion benchmarks (harness = false), and mutation20testing with cargo-mutants as a scheduled quality gate rather than a per-push check.2122It also covers the nextest doctest pitfall: `cargo nextest run` never runs doc-tests, so23`cargo test --doc` must always be paired alongside it — a green nextest run alone is not24full coverage.2526Out of scope: CI pipeline wiring and gate ordering belong to rust-tooling-cicd; non-Rust27test suites are not covered.28</objective>2930# Rust Testing & Quality3132## Agent Workflow (MANDATORY)3334Before ANY test work, spawn 3 agents in parallel, one `Agent` call each with a `name`:35361. **fuse-ai-pilot:explore-codebase** - Map existing `tests/`, `#[cfg(test)]`, `benches/`372. **fuse-ai-pilot:research-expert** - Verify current nextest/proptest/criterion docs via Context7/Exa383. **mcp__context7__query-docs** - Check crate-specific API (proptest strategies, criterion groups)3940After implementation, run **fuse-ai-pilot:sniper** for validation.4142---4344## Overview4546| Test kind | Location | Runs the code as |47|-----------|----------|------------------|48| **Unit** | `#[cfg(test)] mod tests` inside the source file | Same crate, sees private items |49| **Integration** | `tests/*.rs` (each file = own crate) | External consumer, public API only |50| **Doc-test** | ` ```rust ` blocks in `///` docs | Compiled + run as examples |51| **Property** | proptest, inside unit or integration | Generated random inputs + shrinking |52| **Benchmark** | `benches/*.rs` with criterion | Statistical timing, not correctness |5354---5556## Critical Rules57581. **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.592. **Integration tests see only the public API** - if a test needs private items, it belongs in `#[cfg(test)]`, not `tests/`.603. **Commit `proptest-regressions/`** - persisted failing seeds must be under version control so failures are reproducible.614. **`harness = false` for criterion benches** - required in `Cargo.toml`, or the built-in bench harness collides.625. **Mutation testing is a gate, not a smoke test** - `cargo mutants` is slow; run it in scheduled CI, not on every push.6364---6566## Architecture6768```69my_crate/70├── src/71│ └── lib.rs # unit tests in #[cfg(test)] + doc-tests in ///72├── tests/73│ └── api.rs # integration tests (public API)74├── benches/75│ └── throughput.rs # criterion, harness = false76└── proptest-regressions/ # committed failing seeds77```7879→ See [test-suite.md](references/templates/test-suite.md) for the complete example8081---8283## Reference Guide8485### Concepts8687| Topic | Reference | When to Consult |88|-------|-----------|-----------------|89| **Test organization** | [test-organization.md](references/test-organization.md) | Deciding unit vs integration vs doc, running with nextest |90| **Property & mutation** | [property-and-mutation.md](references/property-and-mutation.md) | Adding proptest strategies or cargo-mutants |9192### Templates9394| Template | When to Use |95|----------|-------------|96| [test-suite.md](references/templates/test-suite.md) | Scaffolding unit + integration + doc + proptest |97| [criterion-bench.md](references/templates/criterion-bench.md) | Adding a criterion benchmark |9899---100101## Quick Reference102103### Run everything (the correct pair)104105```bash106cargo nextest run --all-features # unit + integration, fast, parallel107cargo test --doc # doc-tests — NOT covered by nextest108```109110### Property test skeleton111112```rust113use proptest::prelude::*;114115proptest! {116 #[test]117 fn round_trips(n in 0u32..10_000) {118 prop_assert_eq!(decode(&encode(n)), n);119 }120}121```122123→ See [test-suite.md](references/templates/test-suite.md) for the full file124125---126127## Best Practices128129### DO130- Run `cargo nextest run` + `cargo test --doc` together in every CI gate131- Keep integration tests black-box against the public API132- Start proptest with the cheapest property: "does not panic"133- Name benches by the operation measured, not the function name134135### DON'T136- Assume nextest covered doc-tests — it never does137- Put timing benchmarks in `#[test]` (use criterion in `benches/`)138- Gitignore `proptest-regressions/` — commit it139- Run `cargo mutants` on every push (schedule it instead)