cargo-nextest

cargo-nextest - 新一代测试运行器

cargo-nextest 是一款速度更快、更可靠的 Rust 测试运行器，它会在独立进程中执行每项测试，以实现更好的隔离性和并行性能。

何时使用此技能

适合使用此技能的场景……	适合改用相关技能的场景……
通过进程隔离并行运行测试	测量代码覆盖率——使用 cargo-llvm-cov
按软件包、名称或模式筛选测试	检查测试代码风格——使用 clippy-advanced
在 CI 中设置不稳定测试的重试	审查未使用的测试依赖——使用 cargo-machete
通过分区优化测试运行时间	编写测试／使用异步模式——使用 rust-development

安装

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

# Verify installation
cargo nextest --version

基本用法

# 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

配置文件

在项目根目录中创建 .config/nextest.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"

使用表达式语言筛选测试

# 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(/)'

表达式运算符

• test(pattern) - 匹配测试名称（正则表达式）
• binary(pattern) - 匹配二进制文件名称
• package(pattern) - 匹配软件包名称
• kind(type) - 匹配测试类型（lib、bin、test、bench、example）
• platform(os) - 匹配目标平台
• not expr - 逻辑非
• expr and expr - 逻辑与
• expr or expr - 逻辑或

并行执行

Nextest 默认会在独立进程中运行每项测试，从而提供：

• 更好的隔离性 - 测试之间不会相互干扰
• 真正的并行处理 - 不会发生全局状态冲突
• 故障隔离 - 一项测试崩溃不会影响其他测试
• 更好的资源管理 - 每项测试都有干净的环境

# 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

输出格式

# 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

不稳定测试管理

# 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

# Run with retries
cargo nextest run --retries 3

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

GitHub Actions 集成

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

高级配置

# .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" }

文档测试的限制

重要：nextest 不支持文档测试。请使用 cargo test 运行文档测试：

# Run doctests separately
cargo test --doc

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

工作区配置

# 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" }

与 cargo test 的比较

功能	cargo test	cargo nextest
执行模型	进程内	每项测试一个进程
并行方式	基于线程	基于进程
测试隔离	共享状态	完全隔离
输出格式	有限	丰富（JSON、JUnit）
不稳定测试处理	手动	内置重试
文档测试	支持	不支持
性能	良好	出色

最佳实践

1. 为不同环境使用不同配置档：

   • default 用于本地开发
   • ci 用于持续集成
   • coverage 用于覆盖率分析

2. 配置不稳定测试检测：

   [profile.default]
   retries = 2
   

3. 将资源密集型测试分组：

   [test-groups.expensive]
   max-threads = 2
   

4. 设置合适的超时时间：

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

5. 有效使用表达式筛选器：

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

6. 始终在 CI 中单独运行文档测试：

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

故障排除

测试超时过快：

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

并行执行过多：

cargo nextest run --test-threads 4

需要测试输出来进行调试：

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

CI 中出现不稳定测试：

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

参考资料

• nextest 文档
• 配置参考
• 表达式语言
• CI 功能