Cargo Tools

Cargo Tools

Essential cargo ecosystem tools for testing, coverage, and dependency management.

cargo-nextest (Testing)

Next-generation test runner with process isolation and parallel execution.

Installation & Usage

cargo install cargo-nextest --locked

cargo nextest run                    # Run all tests
cargo nextest run test_name          # Run specific test
cargo nextest run -p package_name    # Run tests in package
cargo nextest run -- --ignored       # Run ignored tests
cargo nextest run --test-threads 4   # Control parallelism

Test Filtering

cargo nextest run -E 'test(auth)'              # Match test name
cargo nextest run -E 'package(my_crate)'       # Match package
cargo nextest run -E 'test(auth) and not test(slow)'  # Complex filter
cargo nextest run -E 'kind(test)'              # Integration tests only

Configuration (.config/nextest.toml)

[profile.default]
retries = 0
test-threads = 8
fail-fast = false
success-output = "never"
failure-output = "immediate"

[profile.ci]
retries = 2
fail-fast = true
slow-timeout = { period = "60s", terminate-after = 2 }

[profile.ci.junit]
path = "target/nextest/ci/junit.xml"

[test-groups.database]
max-threads = 1

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

Notes

• Nextest does NOT support doctests. Run separately: cargo test --doc
• Each test runs in its own process for isolation
• Use profiles for different environments (default, ci, coverage)

cargo-llvm-cov (Coverage)

Code coverage using LLVM instrumentation.

Installation & Usage

cargo install cargo-llvm-cov
rustup component add llvm-tools-preview

cargo llvm-cov                    # Run with coverage
cargo llvm-cov --html             # Generate HTML report
cargo llvm-cov --lcov --output-path lcov.info  # LCOV format
cargo llvm-cov --json             # JSON format
cargo llvm-cov --text             # Text summary

Coverage Thresholds

cargo llvm-cov --fail-under-lines 80
cargo llvm-cov --fail-under-functions 75
cargo llvm-cov --fail-under-branches 70  # Requires nightly

With nextest

cargo llvm-cov nextest --html
cargo llvm-cov nextest --profile ci --lcov --output-path lcov.info

Advanced Options

cargo llvm-cov --workspace --html           # All workspace members
cargo llvm-cov --all-features --html        # All features
cargo llvm-cov --ignore-filename-regex '.*generated.*'  # Exclude files
cargo llvm-cov --doc --html                 # Include doctests
cargo llvm-cov clean                        # Clean coverage data

Branch Coverage (Nightly)

rustup toolchain install nightly
rustup component add llvm-tools-preview --toolchain nightly
cargo +nightly llvm-cov --branch --html

cargo-machete (Unused Dependencies)

Fast detection of unused dependencies.

Installation & Usage

cargo install cargo-machete

cargo machete                     # Check for unused deps
cargo machete --with-metadata     # Detailed output
cargo machete --fix               # Remove unused deps
cargo machete --workspace         # Check workspace

Handling False Positives

Create .cargo-machete.toml:

[ignore]
dependencies = ["serde", "log"]

[ignore.my_crate]
dependencies = ["tokio"]

Or use inline comments in Cargo.toml:

[dependencies]
serde = "1.0"  # machete:ignore - used via derive macro

Comparison with cargo-udeps

# Use both for best results
cargo machete                    # Fast check
cargo +nightly udeps             # Verify with udeps

CI Integration

GitHub Actions

name: Rust CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
        with:
          components: llvm-tools-preview

      - uses: taiki-e/install-action@v2
        with:
          tool: nextest,cargo-llvm-cov,cargo-machete

      - uses: Swatinem/rust-cache@v2

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

      - name: Run doctests
        run: cargo test --doc --all-features

      - name: Check coverage
        run: |
          cargo llvm-cov nextest \
            --all-features \
            --fail-under-lines 80 \
            --lcov --output-path lcov.info

      - name: Upload coverage
        uses: codecov/codecov-action@v4
        with:
          files: lcov.info
          token: ${{ secrets.CODECOV_TOKEN }}

      - name: Check unused dependencies
        run: cargo machete --with-metadata

Pre-commit Hook

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: cargo-nextest
        name: cargo nextest
        entry: cargo nextest run
        language: system
        pass_filenames: false
        files: \.rs$

      - id: cargo-machete
        name: cargo machete
        entry: cargo machete
        language: system
        pass_filenames: false
        files: Cargo.toml$

Best Practices

Testing:

• Use nextest for faster parallel execution
• Run doctests separately: cargo nextest run && cargo test --doc
• Configure flaky test retries in CI profile
• Group resource-intensive tests with test-groups

Coverage:

• Use nextest with llvm-cov: cargo llvm-cov nextest
• Set coverage thresholds in CI
• Generate LCOV for coverage services (Codecov, Coveralls)
• Clean coverage data between runs: cargo llvm-cov clean

Dependencies:

• Run machete regularly in CI
• Document false positives with inline comments
• Verify critical projects with cargo-udeps
• Always run cargo check after --fix

References

• nextest documentation
• cargo-llvm-cov
• cargo-machete