cargo-nextest

cargo-nextest - 次世代テストランナー

cargo-nextest は、Rust 向けの高速で信頼性の高いテストランナーです。テストごとに個別のプロセスで実行することで、分離性と並列実行のパフォーマンスを向上させます。

このスキルを使用する場面

次のような場合にこのスキルを使用します	次のような場合は代わりに関連スキルを使用します
プロセスを分離してテストを並列実行する	コードカバレッジを測定する場合 — cargo-llvm-cov を使用します
パッケージ、名前、パターンでテストをフィルタリングする	テストコードのスタイルを lint する場合 — 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 - 論理 NOT
• expr and expr - 論理 AND
• expr or expr - 論理 OR

並列実行

Nextest はデフォルトでテストごとに個別のプロセスで実行するため、次の利点があります。

• 分離性の向上 - テスト同士が干渉しません
• 真の並列実行 - グローバル状態の競合がありません
• 障害の分離 - 1 つのテストがクラッシュしても、ほかのテストに影響しません
• リソース管理の改善 - 各テストでクリーンな環境が使用されます

# 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 の機能