# cargo-nextest — Next-Generation Test Runner for Rust

> cargo-nextest is a drop-in replacement for cargo test that runs each test in its own process, providing better isolation, up to 3x faster execution through parallelism, and rich structured output with per-test timing and retry support.

## Install

Save in your project root:

# cargo-nextest — Next-Generation Test Runner for Rust

## Quick Use
```bash
# Install nextest
cargo install cargo-nextest --locked

# Or install via pre-built binary
curl -LsSf https://get.nexte.st/latest/linux | tar zxf - -C ~/.cargo/bin

# Run tests (drop-in replacement for cargo test)
cargo nextest run

# Run a specific test
cargo nextest run test_name

# Run with retries for flaky tests
cargo nextest run --retries 2

# List tests without running
cargo nextest list
```

## Introduction
cargo-nextest reimagines Rust test execution by running each test as an individual process rather than grouping tests within a single binary process. This per-test isolation eliminates shared state issues, enables fine-grained parallelism, and produces structured output showing exactly which tests passed, failed, or were slow.

## What cargo-nextest Does
- Runs each Rust test in its own process for complete isolation
- Parallelizes test execution across CPU cores for up to 3x faster CI runs
- Provides structured JUnit XML and machine-readable output for CI systems
- Supports automatic retries for flaky tests with configurable retry policies
- Shows per-test timing, making slow test detection trivial

## Architecture Overview
Nextest operates in two phases. The list phase compiles test binaries and discovers all test functions by parsing binary output. The run phase executes each test as a separate child process, managing a pool of concurrent processes up to the configured parallelism limit. Results are collected in real time and streamed to formatters (human-readable, JUnit XML, or JSON). This architecture means a panicking test only affects its own process, not the entire suite.

## Self-Hosting & Configuration
- Install via `cargo install` or download pre-built binaries for faster setup
- Configure via `.config/nextest.toml` in your project root
- Set default parallelism, timeout, and retry policies per profile
- Define custom test groups with dedicated thread limits for resource-heavy tests
- Use profiles (default, ci) to switch settings between local dev and CI

## Key Features
- Per-test process isolation prevents panics and global state from affecting other tests
- Up to 3x faster execution in CI through aggressive parallelism
- Automatic flaky test retries with configurable count and delay
- JUnit XML output for native integration with GitHub Actions, Jenkins, and GitLab CI
- Test archives: bundle test binaries for execution on a different machine

## Comparison with Similar Tools
- **cargo test** — Runs tests in-process within each binary; nextest isolates each test in its own process
- **cargo test --jobs N** — Controls binary compilation parallelism; nextest parallelizes test execution
- **libtest** — Rust's built-in test harness; nextest wraps it with better output and isolation
- **cargo-tarpaulin** — Coverage tool; nextest focuses on execution speed and reliability
- **pytest (Python)** — Similar per-test isolation model; nextest brings this to the Rust ecosystem

## FAQ
**Q: Is nextest a drop-in replacement for cargo test?**
A: For running tests, yes. `cargo nextest run` replaces `cargo test` with the same filtering options. Doc-tests still require `cargo test --doc` as a separate step.

**Q: Does it support doc-tests?**
A: Not directly. Doc-tests use a different compilation model. Run `cargo test --doc` alongside `cargo nextest run` in CI.

**Q: How does it handle tests that rely on shared state?**
A: Each test runs in its own process, so shared mutable statics are isolated. Tests that intentionally share state via the filesystem still work, but global in-process state is not shared.

**Q: Does it work with workspaces?**
A: Yes. Nextest supports Cargo workspaces and can run tests across all workspace members in parallel.

## Sources
- https://github.com/nextest-rs/nextest
- https://nexte.st

---
Source: https://tokrepo.com/en/workflows/asset-f5093051
Author: AI Open Source