rgoussu.dev
rgoussu@goussu: ~/library/rust/toolchain
❯ ~/library/rust/toolchain cat cargo-nextest.md

cargo-nextest — the test runner

# The community-standard test runner — process-per-test isolation, cleaner output, flaky-test retries, CI partitioning and JUnit reports — and what it doesn't run (doctests).

Conceptsaved 2026-08-09 #rust#tooling#testing#ci

Overview

cargo nextest run is a drop-in replacement for cargo test that has become the professional default. It executes each test in its own process with a smarter scheduler, which buys isolation (one segfault or env-var mutation can't poison siblings), better parallelism on mixed-duration suites, per-test timeouts, automatic retries for flaky tests, and CI-grade features — partitioning across machines, JUnit XML — that the built-in libtest runner never grew.

Key points

  • Process-per-test: the defining design choice. Slower per-test floor, but true isolation — leaked state, aborts and segfaults are contained and reported per test.
  • The output is the daily win: a live status line, slowest-tests list, and failures re-printed together at the end — against libtest's interleaved wall of text.
  • Retries & flakiness policy: --retries 2 marks pass-on-retry as flaky rather than silently green — surfacing the flake list instead of burying it.
  • Per-test timeouts (slow-timeout, terminate-after): hung tests fail with a stack of what was running, instead of hanging the CI job.
  • CI partitioning: --partition count:1/4 shards a suite across runners with balanced durations; --profile ci in .config/nextest.toml holds the CI-specific settings (JUnit output path, retries, fail-fast off).
  • Doctests stay behind: libtest still owns them — CI runs cargo nextest run && cargo test --doc. The one wart to remember.
  • Filtersets: -E 'test(parse) & package(core)' — a small expression language for selecting tests by name/package/kind, beyond substring matching.

Examples

cargo install cargo-nextest --locked
cargo nextest run                          # the new default
cargo nextest run --retries 2 -E 'package(api)'
cargo nextest run --partition hash:1/4     # CI shard
cargo test --doc                           # doctests still need libtest

Related