clawmates/skills/rust/cargo-test-driven-development.md

name, description, when_to_use, tags

name	description	when_to_use	tags
cargo-test-driven-development	The `cargo nextest run` workflow for Rust TDD — fast, parallel, isolates flakes. Falls back to `cargo test` when nextest isn't installed.	You're the tester role, or coder role in the RED phase of TDD, on a Rust codebase.	rust testing tdd versioned

Cargo TDD workflow

Runner

Primary: cargo nextest run (0.9.140 as of 2026-07). Why over cargo test:

• Parallel process isolation — one panicking test doesn't taint others.
• Structured, greppable output.
• --retries N policy for flake-tolerance without hiding real failures.
• Per-test timeouts.

Install: cargo install cargo-nextest --locked in the runtime image; CI runs cargo nextest run --profile ci.

The RED-GREEN loop (Rust flavor)

1. RED — write the failing test.

   #[tokio::test]
   async fn workspace_scoped_get_rejects_cross_workspace() {
       let pool = testkit::pool().await;
       let mine = seed_workspace(&pool).await;
       let theirs = seed_workspace(&pool).await;
       let row = insert_row(&pool, theirs).await;
       assert!(get(&pool, row.id, mine).await.unwrap().is_none());
   }
   

   Run: cargo nextest run workspace_scoped_get_rejects_cross_workspace. Confirm the test fails because the fn doesn't exist yet or because behavior is missing.

2. GREEN — minimal implementation. Hardcode if that's what the ONE test asks for. Trust that the NEXT test will force you to generalize.

3. REFACTOR under green. Extract, rename, tighten. Re-run after each keystroke that could break something. cargo nextest run <fn_name> on the specific test is faster than the whole suite.

Speed tricks

• cargo nextest run -j 8 — parallelize across cores.
• cargo nextest run --no-fail-fast — see all failures in one pass, not just the first.
• cargo nextest run -E 'test(foo)' — filter expression language, more powerful than a substring.
• cargo check --tests before running — catches type errors ~10× faster than compiling test binaries.

Coverage

• cargo llvm-cov nextest — nextest under llvm-cov instrumentation. Reports per-file line coverage.
• CI enforces ≥90% on changed lines. Locally: cargo llvm-cov nextest --html && open target/llvm-cov/html/index.html.

Integration tests that hit real infra

• Postgres via testcontainers — spins a fresh container per test suite. NEVER mock the DB when the test's job is to prove a query.
• HTTP via axum::Router + tower::ServiceExt::oneshot — driver is in-process, no port needed.
• Docker via bollard mock or a #[ignore] guarded live test.

Anti-patterns

• Snapshot-only test files. A snapshot proves nothing structural. Pair with real assertions.
• #[ignore]d tests that stay ignored. Ignore is a debt marker — file the ticket to fix and put the ticket ID in the ignore reason.
• Testing panics with should_panic when a Result::Err would do. Panics on the happy path of a test framework are user-hostile output.