/rust-testing-quality

name: rust-testing-quality
description: 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).
versions:
  cargo-nextest: "0.9"
  proptest: "1"
  criterion: "0.5"
user-invocable: false
references: references/test-organization.md, references/property-and-mutation.md, references/templates/test-suite.md, references/templates/criterion-bench.md
related-skills: solid-rust, rust-tooling-cicd

<objective> This skill covers organizing and running the full Rust test spectrum: unit tests in #[cfg(test)] modules, integration tests in tests/*.rs against the public API only, doc-tests compiled from /// examples, property-based testing with proptest (including committing proptest-regressions/), criterion benchmarks (harness = false), and mutation testing with cargo-mutants as a scheduled quality gate rather than a per-push check.

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. </objective>

Rust Testing & Quality

Agent Workflow (MANDATORY)

Before ANY test work, spawn 3 agents in parallel, one `Agent` call each with a `name`:

1. **fuse-ai-pilot:explore-codebase** - Map existing `tests/`, `#[cfg(test)]`, `benches/` 2. **fuse-ai-pilot:research-expert** - Verify current nextest/proptest/criterion docs via Context7/Exa 3. **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

1. **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. 2. **Integration tests see only the public API** - if a test needs private items, it belongs in `#[cfg(test)]`, not `tests/`. 3. **Commit `proptest-regressions/`** - persisted failing seeds must be under version control so failures are reproducible. 4. **`harness = false` for criterion benches** - required in `Cargo.toml`, or the built-in bench harness collides. 5. **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](references/templates/test-suite.md) for the complete example

---

Reference Guide

Concepts

| Topic | Reference | When to Consult | |-------|-----------|-----------------| | **Test organization** | [test-organization.md](references/test-organization.md) | Deciding unit vs integration vs doc, running with nextest | | **Property & mutation** | [property-and-mutation.md](references/property-and-mutation.md) | Adding proptest strategies or cargo-mutants |

Templates

| Template | When to Use | |----------|-------------| | [test-suite.md](references/templates/test-suite.md) | Scaffolding unit + integration + doc + proptest | | [criterion-bench.md](references/templates/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](references/templates/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)