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

<h2>Introduction</h2> <p>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. <strong>cargo-nextest</strong>—created by Rain—is a next-generation test runner designed to solve exactly these problems. It runs tests up to three times faster than <code>cargo test</code>, provides detailed observability into test behavior, and works seamlessly in both local development and continuous integration environments. With the recent <strong>RustRover 2026.1</strong> 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.</p><figure style="margin:20px 0"><img src="https://blog.jetbrains.com/wp-content/uploads/2026/05/Untitled-design-1.png" alt="Mastering Rust Testing with cargo-nextest: A Step-by-Step 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> <h2>What You Need</h2> <ul> <li><strong>Rust toolchain</strong> (stable or nightly) installed via <code>rustup</code></li> <li>A Rust project with tests (unit, integration, or doctests)</li> <li><strong>cargo-nextest</strong> binary (installation covered in Step 1)</li> <li>(Optional) <strong>RustRover 2026.1</strong> or later for IDE integration</li> <li>Basic familiarity with command-line and <code>Cargo.toml</code> configuration</li> </ul> <h2>Step-by-Step Guide</h2> <h3 id="step1">Step 1: Install cargo-nextest</h3> <p>To install cargo-nextest, run the following command in your terminal:</p> <pre><code>cargo install cargo-nextest</code></pre> <p>This will download and compile the binary. If you're on macOS or Linux, you can also use the prebuilt binaries from the <a href="https://github.com/nextest-rs/nextest/releases" target="_blank">GitHub releases page</a> for faster installation. Verify the installation with:</p> <pre><code>cargo nextest --version</code></pre> <p>You should see the version number like <code>0.9.78</code>.</p> <h3 id="step2">Step 2: Configure Your Test Runner</h3> <p>cargo-nextest works with your existing Rust tests without any code changes. However, you can customize its behavior through a <code>.config/nextest.toml</code> file in your project root. Create it and add settings such as:</p> <ul> <li><strong>Test timeouts</strong> – Prevent hung tests from blocking the whole suite.</li> <li><strong>Retry policies</strong> – Automatically retry flaky tests a set number of times.</li> <li><strong>Display options</strong> – Control how test output is shown (e.g., per-test output, pass/fail counts).</li> </ul> <p>For example:</p> <pre><code># .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 </code></pre> <p>This configuration makes nextest particularly useful on CI where you want to fail fast and avoid resource exhaustion.</p> <h3 id="step3">Step 3: Run Tests with cargo-nextest</h3> <p>Instead of <code>cargo test</code>, use:</p> <pre><code>cargo nextest run</code></pre> <p>By default, this runs all tests in your workspace. You can filter by test name:</p> <pre><code>cargo nextest run --test integration_tests -- test_name_pattern</code></pre> <p>Key flags to know:</p> <ul> <li><code>--workspace</code> – Run all workspace members (default).</li> <li><code>--release</code> – Compile with release optimizations.</li> <li><code>--all-features</code> – Enable all Cargo features.</li> <li><code>--no-tests=warn</code> – Warn instead of error if no tests are found.</li> </ul> <p>During the run, you'll see a live progress bar and per-test timing. This is far more informative than <code>cargo test</code>'s simple dot output.</p> <h3 id="step4">Step 4: Interpret the Results</h3> <p>After the run, nextest produces a structured report. Look for:</p> <ul> <li><strong>Test suite summary</strong> – Shows total passed, failed, skipped, and ignored.</li> <li><strong>Slowest tests</strong> – Identifies bottlenecks in your test suite.</li> <li><strong>Output per test</strong> – Expandable to see exactly what each test printed.</li> </ul> <p>Use the <code>--message-format json</code> flag to get machine-readable output for custom analysis. For local debugging, run with:</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 Testing with cargo-nextest: A Step-by-Step 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> <pre><code>cargo nextest run --failure-output immediate</code></pre> <p>This prints output as soon as a test fails, helping you iterate faster.</p> <h3 id="step5">Step 5: Integrate cargo-nextest with CI</h3> <p>cargo-nextest is built for continuous integration. Add this to your CI script (e.g., GitHub Actions):</p> <pre><code># .github/workflows/ci.yml - name: Run tests with nextest run: | cargo nextest run --profile ci </code></pre> <p>You can create a CI-specific profile in <code>.config/nextest.toml</code>:</p> <pre><code>[profile.ci] fail-fast = true retries = 1 test-threads = 6 </code></pre> <p>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 <code>--junit</code> flag).</p> <h3 id="step6">Step 6: Use RustRover IDE Integration (Optional)</h3> <p>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 <strong>cargo-nextest</strong> 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.</p> <h2>Tips for Success</h2> <ul> <li><strong>Start small</strong> – Try nextest on a single crate before rolling out across your whole workspace.</li> <li><strong>Leverage test partitioning</strong> – For massive test suites, use <code>--partition</code> to split runs across multiple CI jobs (e.g., <code>--partition hash:1/4</code>).</li> <li><strong>Combine with cargo-tarpaulin</strong> – For code coverage, run nextest first to check passes, then use tarpaulin for coverage metrics.</li> <li><strong>Watch for known limitations</strong> – cargo-nextest does not yet support doctests with capture; use <code>cargo test --doc</code> for those.</li> <li><strong>Stay updated</strong> – The tool evolves quickly; follow the <a href="https://github.com/nextest-rs/nextest" target="_blank">GitHub repository</a> for new features like test retries based on history.</li> </ul> <p>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.</p>