cargo-nextest - Next-Generation Test Runner

cargo-nextest is a faster, more reliable test runner for Rust that executes each test in its own process for better isolation and parallel performance.

Installation

bash

# Install cargo-nextest
cargo install cargo-nextest --locked

# Verify installation
cargo nextest --version

Basic Usage

bash

# Run all tests with nextest
cargo nextest run

# Run specific test
cargo nextest run test_name

# Run tests in specific package
cargo nextest run -p package_name

# Run with verbose output
cargo nextest run --verbose

# Run ignored tests
cargo nextest run -- --ignored

# Run all tests including ignored
cargo nextest run -- --include-ignored

Configuration File

Create

.config/nextest.toml

in your project root:

toml

[profile.default]
# Number of retries for flaky tests
retries = 0

# Test threads (default: number of logical CPUs)
test-threads = 8

# Fail fast - stop on first failure
fail-fast = false

# Show output for passing tests
success-output = "never"  # never, immediate, final, immediate-final

# Show output for failing tests
failure-output = "immediate"  # never, immediate, final, immediate-final

[profile.ci]
# CI-specific configuration
retries = 2
fail-fast = true
success-output = "never"
failure-output = "immediate-final"

# Slow test timeout
slow-timeout = { period = "60s", terminate-after = 2 }

[profile.ci.junit]
# JUnit XML output for CI
path = "target/nextest/ci/junit.xml"

Test Filtering with Expression Language

bash

# Run tests matching pattern
cargo nextest run -E 'test(auth)'

# Run tests in specific binary
cargo nextest run -E 'binary(my_app)'

# Run tests in specific package
cargo nextest run -E 'package(my_crate)'

# Complex expressions with operators
cargo nextest run -E 'test(auth) and not test(slow)'

# Run all integration tests
cargo nextest run -E 'kind(test)'

# Run only unit tests in library
cargo nextest run -E 'kind(lib) and test(/)'

Expression Operators

```
test(pattern)
```
- Match test name (regex)
```
binary(pattern)
```
- Match binary name
```
package(pattern)
```
- Match package name
```
kind(type)
```
- Match test kind (lib, bin, test, bench, example)
```
platform(os)
```
- Match target platform
```
not expr
```
- Logical NOT
```
expr and expr
```
- Logical AND
```
expr or expr
```
- Logical OR

Parallel Execution

Nextest runs each test in its own process by default, providing:

Better isolation - Tests cannot interfere with each other
True parallelism - No global state conflicts
Fault isolation - One test crash doesn't affect others
Better resource management - Each test has clean environment

bash

# Control parallelism
cargo nextest run --test-threads 4

# Single-threaded execution
cargo nextest run --test-threads 1

# Use all available cores
cargo nextest run --test-threads 0

Output Formats

bash

# Human-readable output (default)
cargo nextest run

# JSON output for programmatic parsing
cargo nextest run --message-format json

# JSON with test output
cargo nextest run --message-format json-pretty

# Generate JUnit XML for CI
cargo nextest run --profile ci

# Combine with cargo-llvm-cov for coverage
cargo llvm-cov nextest --html

Flaky Test Management

toml

# In .config/nextest.toml
[profile.default]
# Retry flaky tests automatically
retries = 3

# Detect tests that pass on retry
[profile.default.overrides]
filter = 'test(flaky_)'
retries = 5

bash

# Run with retries
cargo nextest run --retries 3

# Show retry statistics
cargo nextest run --retries 3 --failure-output immediate-final

GitHub Actions Integration

yaml

name: Test

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: dtolnay/rust-toolchain@stable

      - name: Install nextest
        uses: taiki-e/install-action@v2
        with:
          tool: nextest

      - name: Run tests
        run: cargo nextest run --profile ci --all-features

      - name: Upload test results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: test-results
          path: target/nextest/ci/junit.xml

      - name: Publish test results
        uses: EnricoMi/publish-unit-test-result-action@v2
        if: always()
        with:
          files: target/nextest/ci/junit.xml

Advanced Configuration

toml

# .config/nextest.toml
[profile.default]
# Timeout for slow tests
slow-timeout = { period = "30s", terminate-after = 3 }

# Test groups for resource management
[test-groups.database]
max-threads = 1  # Serialize database tests

[profile.default.overrides]
filter = 'test(db_)'
test-group = 'database'

# Platform-specific overrides
[[profile.default.overrides]]
platform = 'x86_64-pc-windows-msvc'
slow-timeout = { period = "60s" }

Doctests Limitation

Important: nextest does not support doctests. Use cargo test for doctests:

bash

# Run doctests separately
cargo test --doc

# Run both nextest and doctests in CI
cargo nextest run && cargo test --doc

Workspace Configuration

toml

# In workspace root .config/nextest.toml
[profile.default]
default-filter = 'all()'

# Per-package overrides
[[profile.default.overrides]]
filter = 'package(slow_tests)'
test-threads = 1
slow-timeout = { period = "120s" }

Comparison with cargo test

Feature	cargo test	cargo nextest
Execution model	In-process	Per-test process
Parallelism	Thread-based	Process-based
Test isolation	Shared state	Complete isolation
Output format	Limited	Rich (JSON, JUnit)
Flaky test handling	Manual	Built-in retries
Doctests	Supported	Not supported
Performance	Good	Excellent

Best Practices

Use profiles for different environments:
- ```
default
```
  for local development
- ```
ci
```
  for continuous integration
- ```
coverage
```
  for coverage analysis
Configure flaky test detection:
toml
```
[profile.default]
retries = 2
```
Group resource-intensive tests:
toml
```
[test-groups.expensive]
max-threads = 2
```

Set appropriate timeouts:

toml

[profile.default]
slow-timeout = { period = "60s", terminate-after = 2 }

Use expression filters effectively:

bash

# Run fast tests during development
cargo nextest run -E 'not test(slow_)'

Always run doctests separately in CI:

yaml

- run: cargo nextest run --all-features
- run: cargo test --doc --all-features

Troubleshooting

Tests timeout too quickly:

toml

[profile.default]
slow-timeout = { period = "120s", terminate-after = 3 }

Too much parallel execution:

bash

cargo nextest run --test-threads 4

Need test output for debugging:

bash

cargo nextest run --success-output immediate --failure-output immediate

Flaky tests in CI:

toml

[profile.ci]
retries = 3
failure-output = "immediate-final"

cargo-nextest

NPX Install

Tags

SKILL.md Content

cargo-nextest - Next-Generation Test Runner

Installation

Basic Usage

Configuration File

Test Filtering with Expression Language

Expression Operators

Parallel Execution

Output Formats

Flaky Test Management

GitHub Actions Integration

Advanced Configuration

Doctests Limitation

Workspace Configuration

Comparison with cargo test

Best Practices

Troubleshooting

References