cargo-nextest

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

cargo-nextest - Next-Generation Test Runner

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

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.

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

Installation

安装

bash

undefined

bash

undefined

Install cargo-nextest

cargo install cargo-nextest --locked

Verify installation

cargo nextest --version

undefined

cargo nextest --version

undefined

Basic Usage

基本用法

bash

undefined

bash

undefined

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

undefined

cargo nextest run -- --include-ignored

undefined

Configuration File

配置文件

Create

.config/nextest.toml

in your project root:

toml

[profile.default]

在项目根目录创建

.config/nextest.toml

：

toml

[profile.default]

Number of retries for flaky tests

不稳定测试的重试次数

retries = 0

Test threads (default: number of logical CPUs)

测试线程数（默认：逻辑CPU数量）

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]

failure-output = "immediate" # never, immediate, final, immediate-final

[profile.ci]

CI-specific configuration

CI专属配置

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]

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

[profile.ci.junit]

JUnit XML output for CI

用于CI的JUnit XML输出

path = "target/nextest/ci/junit.xml"

undefined

path = "target/nextest/ci/junit.xml"

undefined

Test Filtering with Expression Language

使用表达式语言进行测试过滤

bash

undefined

bash

undefined

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

undefined

cargo nextest run -E 'kind(lib) and test(/)'

undefined

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

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

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

undefined

默认情况下，Nextest在独立进程中运行每个测试，提供以下优势：

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

bash

undefined

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

undefined

cargo nextest run --test-threads 0

undefined

Output Formats

输出格式

bash

undefined

bash

undefined

Human-readable output (default)

人类可读格式输出（默认）

cargo nextest run

JSON output for programmatic parsing

用于程序化解析的JSON输出

cargo nextest run --message-format json

JSON with test output

包含测试输出的JSON格式

cargo nextest run --message-format json-pretty

Generate JUnit XML for CI

为CI生成JUnit XML

cargo nextest run --profile ci

Combine with cargo-llvm-cov for coverage

结合cargo-llvm-cov生成覆盖率报告

cargo llvm-cov nextest --html

undefined

cargo llvm-cov nextest --html

undefined

Flaky Test Management

不稳定测试管理

toml

undefined

toml

undefined

In .config/nextest.toml

在 .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

[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

undefined

cargo nextest run --retries 3 --failure-output immediate-final

undefined

GitHub Actions Integration

GitHub Actions集成

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

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

undefined

toml

undefined

.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'

[test-groups.database] max-threads = 1 # 串行执行数据库测试

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

undefined

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

undefined

Doctests Limitation

文档测试限制

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

bash

undefined

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

bash

undefined

Run doctests separately

单独运行文档测试

cargo test --doc

Run both nextest and doctests in CI

在CI中同时运行nextest和文档测试

cargo nextest run && cargo test --doc

undefined

cargo nextest run && cargo test --doc

undefined

Workspace Configuration

工作区配置

toml

undefined

toml

undefined

In workspace root .config/nextest.toml

在工作区根目录的 .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" }

undefined

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

undefined

Comparison with cargo test

与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

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

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

为不同环境使用不同配置文件：
- ```
default
```
  用于本地开发
- ```
ci
```
  用于持续集成
- ```
coverage
```
  用于覆盖率分析
配置不稳定测试检测：
toml
```
[profile.default]
retries = 2
```
对资源密集型测试进行分组：
toml
```
[test-groups.expensive]
max-threads = 2
```

设置合适的超时时间：

toml

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

有效使用表达式过滤器：

bash

# 开发期间仅运行快速测试
cargo nextest run -E 'not test(slow_)'

在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"

测试超时过快：

toml

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

并行执行过度：

bash

cargo nextest run --test-threads 4

调试时需要测试输出：

bash

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

CI中存在不稳定测试：

toml

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