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

By ● min read

<h2 id="overview">Overview</h2> <p>Testing is a critical part of Rust development, but as codebases grow, the built-in <code>cargo test</code> can become a bottleneck. <strong>cargo-nextest</strong> 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 <em>three times faster</em> than <code>cargo test</code> for many workloads.</p><figure style="margin:20px 0"><img src="https://blog.jetbrains.com/wp-content/uploads/2026/05/Untitled-design-1.png" alt="Mastering Rust Test Execution with cargo-nextest: A Practical Guide" style="width:100%;height:auto;border-radius:8px" loading="lazy"><figcaption style="font-size:12px;color:#666;margin-top:5px">Source: blog.jetbrains.com</figcaption></figure> <p>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.</p> <h2 id="prerequisites">Prerequisites</h2> <p>Before diving in, ensure you have the following:</p> <ul> <li><strong>Rust toolchain</strong> installed (rustc, cargo). If not, install via <a href="https://rustup.rs/">rustup</a>.</li> <li>A <strong>Rust project</strong> with existing tests (unit, integration, or both).</li> <li>Basic familiarity with <code>cargo test</code> and Cargo workspaces.</li> <li>For the RustRover section, you'll need <strong>RustRover 2026.1</strong> or later.</li> </ul> <h2 id="step-by-step">Step-by-Step Instructions</h2> <h3 id="install-nextest">1. Installing cargo-nextest</h3> <p>cargo-nextest is distributed as a Cargo subcommand. Install it using:</p> <pre><code>cargo install cargo-nextest</code></pre> <p>Alternatively, you can use a package manager like <code>brew</code> on macOS or download a pre-built binary from the <a href="https://github.com/nextest-rs/nextest/releases">releases page</a>. Verify the installation:</p> <pre><code>cargo nextest --version</code></pre> <h3 id="basic-usage">2. Running Your First Tests with nextest</h3> <p>Navigate to your project root and run all tests:</p> <pre><code>cargo nextest run</code></pre> <p>This compiles and executes your tests, displaying a structured summary. Compared to <code>cargo test</code>, you'll notice faster execution and clearer output. To see what tests exist without running them:</p> <pre><code>cargo nextest list</code></pre> <p>You can pass familiar test filters:</p> <pre><code>cargo nextest run my_test_name</code></pre> <h3 id="configuring-nextest">3. Configuring Test Execution</h3> <p>Create a <code>.nextest.toml</code> file in your project root to customize behavior. Key options include:</p> <ul> <li><strong>test-threads</strong>: Control parallelism (default: number of CPUs). Set to 1 for sequential execution.</li> <li><strong>retries</strong>: Automatically retry flaky tests a specified number of times.</li> <li><strong>slow-timeout</strong>: Mark tests as slow after a threshold (e.g., <code>60s</code>).</li> </ul> <p>Example configuration:</p> <pre><code>[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"</code></pre> <p>Apply these settings by running nextest again—it automatically reads the config.</p> <h3 id="ci-integration">4. Integrating with CI (Continuous Integration)</h3> <p>cargo-nextest excels in CI environments. Use the <code>--ci</code> flag for a more machine-friendly output:</p> <pre><code>cargo nextest run --ci</code></pre> <p>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:</p> <pre><code>cargo nextest run --message-format junit > test_results.xml</code></pre> <p>For GitHub Actions, consider the official <a href="https://github.com/nextest-rs/nextest-action">nextest-action</a>:</p> <pre><code># .github/workflows/test.yml - name: Run tests with nextest uses: nextest-rs/nextest-action@v1 with: arguments: --ci</code></pre> <h3 id="rustrover-integration">5. Using cargo-nextest in RustRover</h3> <p>RustRover 2026.1 introduced native support for cargo-nextest. Once installed, you can select <strong>nextest</strong> as your test runner in <em>Settings &gt; Build, Execution, Deployment &gt; Rust &gt; Test Runner</em>. Then, run tests via the gutter icons or the context menu—results appear in the <strong>Test</strong> tool window with progress and structured details. This gives you IDE-level control over test execution without leaving your editor.</p><figure style="margin:20px 0"><img src="https://blog.jetbrains.com/wp-content/uploads/2025/12/Screenshot-2025-10-23-at-06.34.51.png" alt="Mastering Rust Test Execution with cargo-nextest: A Practical Guide" style="width:100%;height:auto;border-radius:8px" loading="lazy"><figcaption style="font-size:12px;color:#666;margin-top:5px">Source: blog.jetbrains.com</figcaption></figure> <h3 id="advanced-features">6. Advanced Features</h3> <h4>Test Partitioning</h4> <p>For large suites, split tests across multiple CI jobs. Use the <code>--partition</code> flag:</p> <pre><code># In CI job 1 cargo nextest run --partition hash:1/2 --ci # In CI job 2 cargo nextest run --partition hash:2/2 --ci</code></pre> <p>This distributes tests by hash, ensuring balanced runs.</p> <h4>Per-Test Timeouts</h4> <p>Set timeouts for specific tests using <code>#[nextest(timeout = "5s")]</code> attribute (requires <code>nextest-attr</code> crate).</p> <h4>Output Format Customization</h4> <p>Control verbosity with <code>--verbose</code>, or output machine-readable JSON with <code>--message-format json</code>.</p> <h2 id="common-mistakes">Common Mistakes</h2> <ul> <li><strong>Forgetting to install nextest:</strong> Ensure <code>cargo nextest</code> is available in your PATH, especially in CI.</li> <li><strong>Not creating a <code>.nextest.toml</code>:</strong> Without it, nextest uses sensible defaults, but you miss out on tuning for your project.</li> <li><strong>Misunderstanding test isolation:</strong> nextest runs each test in its own process for better isolation, but this can increase overhead for very small tests. Adjust <code>test-threads</code> accordingly.</li> <li><strong>Ignoring flaky test retries:</strong> If your tests are flaky, enable retries to avoid false CI failures. But investigate the root cause.</li> <li><strong>Using <code>--no-run</code> incorrectly:</strong> When compiling separately, remember to run <code>cargo nextest run --no-run --compile</code> first, then use the generated binary.</li> </ul> <h2 id="summary">Summary</h2> <p>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 <code>cargo-nextest</code> and running it on your existing tests. Customize with <code>.nextest.toml</code> and integrate it into your CI pipeline for maximum benefit.</p>