Mastering Rust Testing with cargo-nextest: A Step-by-Step Guide

Introduction

If you're working with Rust projects that have grown beyond a few dozen tests, you've likely felt the frustration of slow test runs, opaque results, and CI pipelines that take forever. cargo-nextest—created by Rain—is a next-generation test runner designed to solve exactly these problems. It runs tests up to three times faster than cargo test, provides detailed observability into test behavior, and works seamlessly in both local development and continuous integration environments. With the recent RustRover 2026.1 adding native support, there's never been a better time to adopt it. This guide walks you through everything you need to get started, from installation to advanced usage.

What You Need

• Rust toolchain (stable or nightly) installed via rustup
• A Rust project with tests (unit, integration, or doctests)
• cargo-nextest binary (installation covered in Step 1)
• (Optional) RustRover 2026.1 or later for IDE integration
• Basic familiarity with command-line and Cargo.toml configuration

Step-by-Step Guide

Step 1: Install cargo-nextest

To install cargo-nextest, run the following command in your terminal:

cargo install cargo-nextest

This will download and compile the binary. If you're on macOS or Linux, you can also use the prebuilt binaries from the GitHub releases page for faster installation. Verify the installation with:

cargo nextest --version

You should see the version number like 0.9.78.

Step 2: Configure Your Test Runner

cargo-nextest works with your existing Rust tests without any code changes. However, you can customize its behavior through a .config/nextest.toml file in your project root. Create it and add settings such as:

• Test timeouts – Prevent hung tests from blocking the whole suite.
• Retry policies – Automatically retry flaky tests a set number of times.
• Display options – Control how test output is shown (e.g., per-test output, pass/fail counts).

For example:

# .config/nextest.toml
[test-runner]
test-threads = 4                  # limit parallel threads
max-failures = 10                 # stop after 10 failures

[test-output]
show-output = "failed"            # only show stdout for failed tests

This configuration makes nextest particularly useful on CI where you want to fail fast and avoid resource exhaustion.

Step 3: Run Tests with cargo-nextest

Instead of cargo test, use:

cargo nextest run

By default, this runs all tests in your workspace. You can filter by test name:

cargo nextest run --test integration_tests -- test_name_pattern

Key flags to know:

• --workspace – Run all workspace members (default).
• --release – Compile with release optimizations.
• --all-features – Enable all Cargo features.
• --no-tests=warn – Warn instead of error if no tests are found.

During the run, you'll see a live progress bar and per-test timing. This is far more informative than cargo test's simple dot output.

Step 4: Interpret the Results

After the run, nextest produces a structured report. Look for:

• Test suite summary – Shows total passed, failed, skipped, and ignored.
• Slowest tests – Identifies bottlenecks in your test suite.
• Output per test – Expandable to see exactly what each test printed.

Use the --message-format json flag to get machine-readable output for custom analysis. For local debugging, run with:

cargo nextest run --failure-output immediate

This prints output as soon as a test fails, helping you iterate faster.

Step 5: Integrate cargo-nextest with CI

cargo-nextest is built for continuous integration. Add this to your CI script (e.g., GitHub Actions):

# .github/workflows/ci.yml
- name: Run tests with nextest
  run: |
    cargo nextest run --profile ci

You can create a CI-specific profile in .config/nextest.toml:

[profile.ci]
fail-fast = true
retries = 1
test-threads = 6

This ensures that on CI you get fast feedback (fail-fast) and a single retry for flaky tests. The structured JSON output can be fed into test reporting tools like JUnit reports (via --junit flag).

Step 6: Use RustRover IDE Integration (Optional)

If you use RustRover 2026.1 or later, you can run nextest directly from the IDE. Open the Test tool window, select your test runner as cargo-nextest from the run configuration dropdown. You'll see real-time progress, pass/fail status, and clickable test results. This brings the speed of nextest into a visual environment—great for debugging failing tests without leaving the editor.

Tips for Success

• Start small – Try nextest on a single crate before rolling out across your whole workspace.
• Leverage test partitioning – For massive test suites, use --partition to split runs across multiple CI jobs (e.g., --partition hash:1/4).
• Combine with cargo-tarpaulin – For code coverage, run nextest first to check passes, then use tarpaulin for coverage metrics.
• Watch for known limitations – cargo-nextest does not yet support doctests with capture; use cargo test --doc for those.
• Stay updated – The tool evolves quickly; follow the GitHub repository for new features like test retries based on history.

By following these steps, you'll transform your Rust testing experience. cargo-nextest not only saves time but also gives you deeper insight into test behavior—making it an essential tool for any serious Rust project.