Mastering Rust Test Execution with cargo-nextest: A Practical Guide

Overview

Testing is a critical part of Rust development, but as codebases grow, the built-in cargo test can become a bottleneck. cargo-nextest emerges as a next-generation test runner designed to make test execution faster, more observable, and more reliable—especially for large projects and CI pipelines. Developed by Rain (a seasoned Rust engineer from Meta, Mozilla, and Oxide Computer Company), cargo-nextest is now widely adopted in the Rust ecosystem. Benchmarks show it can be up to three times faster than cargo test for many workloads.

This guide walks you through everything you need to integrate cargo-nextest into your Rust workflow. We'll cover installation, basic usage, advanced configuration, CI integration, and how to leverage its support in RustRover 2026.1. By the end, you'll be able to run your tests more efficiently and gain deeper insight into test results.

Prerequisites

Before diving in, ensure you have the following:

• Rust toolchain installed (rustc, cargo). If not, install via rustup.
• A Rust project with existing tests (unit, integration, or both).
• Basic familiarity with cargo test and Cargo workspaces.
• For the RustRover section, you'll need RustRover 2026.1 or later.

Step-by-Step Instructions

1. Installing cargo-nextest

cargo-nextest is distributed as a Cargo subcommand. Install it using:

cargo install cargo-nextest

Alternatively, you can use a package manager like brew on macOS or download a pre-built binary from the releases page. Verify the installation:

cargo nextest --version

2. Running Your First Tests with nextest

Navigate to your project root and run all tests:

cargo nextest run

This compiles and executes your tests, displaying a structured summary. Compared to cargo test, you'll notice faster execution and clearer output. To see what tests exist without running them:

cargo nextest list

You can pass familiar test filters:

cargo nextest run my_test_name

3. Configuring Test Execution

Create a .nextest.toml file in your project root to customize behavior. Key options include:

• test-threads: Control parallelism (default: number of CPUs). Set to 1 for sequential execution.
• retries: Automatically retry flaky tests a specified number of times.
• slow-timeout: Mark tests as slow after a threshold (e.g., 60s).

Example configuration:

[test-threads]
# Limit to 4 parallel tests
count = 4

[retries]
# Retry failed tests up to 2 times
count = 2

[slow-timeout]
# Warn if a test takes more than 30 seconds
period = "30s"

Apply these settings by running nextest again—it automatically reads the config.

4. Integrating with CI (Continuous Integration)

cargo-nextest excels in CI environments. Use the --ci flag for a more machine-friendly output:

cargo nextest run --ci

This suppresses progress bars and produces structured JSON logs. You can also generate JUnit XML reports for integration with popular CI tools like Jenkins, GitLab CI, or GitHub Actions:

cargo nextest run --message-format junit > test_results.xml

For GitHub Actions, consider the official nextest-action:

# .github/workflows/test.yml
- name: Run tests with nextest
  uses: nextest-rs/nextest-action@v1
  with:
    arguments: --ci

5. Using cargo-nextest in RustRover

RustRover 2026.1 introduced native support for cargo-nextest. Once installed, you can select nextest as your test runner in Settings > Build, Execution, Deployment > Rust > Test Runner. Then, run tests via the gutter icons or the context menu—results appear in the Test tool window with progress and structured details. This gives you IDE-level control over test execution without leaving your editor.

6. Advanced Features

Test Partitioning

For large suites, split tests across multiple CI jobs. Use the --partition flag:

# In CI job 1
cargo nextest run --partition hash:1/2 --ci
# In CI job 2
cargo nextest run --partition hash:2/2 --ci

This distributes tests by hash, ensuring balanced runs.

Per-Test Timeouts

Set timeouts for specific tests using #[nextest(timeout = "5s")] attribute (requires nextest-attr crate).

Output Format Customization

Control verbosity with --verbose, or output machine-readable JSON with --message-format json.

Common Mistakes

• Forgetting to install nextest: Ensure cargo nextest is available in your PATH, especially in CI.
• Not creating a .nextest.toml: Without it, nextest uses sensible defaults, but you miss out on tuning for your project.
• Misunderstanding test isolation: nextest runs each test in its own process for better isolation, but this can increase overhead for very small tests. Adjust test-threads accordingly.
• Ignoring flaky test retries: If your tests are flaky, enable retries to avoid false CI failures. But investigate the root cause.
• Using --no-run incorrectly: When compiling separately, remember to run cargo nextest run --no-run --compile first, then use the generated binary.

Summary

cargo-nextest is a powerful addition to any Rust developer's toolkit, offering faster test execution, better observability, and CI-friendly features. This guide covered installation, basic and advanced usage, CI integration, and RustRover support. By adopting nextest, you can significantly reduce test turnaround times and gain deeper insights into your test suite—especially as your project scales. Start by installing cargo-nextest and running it on your existing tests. Customize with .nextest.toml and integrate it into your CI pipeline for maximum benefit.