foxhunt/NEXTEST_QUICK_START.md

cargo-nextest Quick Start Guide

Version: cargo-nextest 0.9.105 Platform: Linux x86_64, 16 CPU cores Project: Foxhunt HFT Trading System

---

What is cargo-nextest?

A next-generation test runner for Rust that runs tests in parallel with better performance and cleaner output.

---

Installation

Already installed! ✅

$ cargo nextest --version
cargo-nextest 0.9.105 (716b1fba8 2025-10-02)

---

Basic Usage

Replace cargo test with cargo nextest run

# Instead of: cargo test
cargo nextest run

# Instead of: cargo test --package common
cargo nextest run --package common

# Instead of: cargo test --workspace
cargo nextest run --workspace

Common Commands

# List all tests without running
cargo nextest list

# Run tests in a specific package
cargo nextest run --package trading_service

# Run tests matching a pattern
cargo nextest run test_order_

# Run with specific number of threads (default: 16 for this system)
cargo nextest run --test-threads 8

# Generate JUnit XML report for CI
cargo nextest run --junit junit.xml

# Show detailed timing
cargo nextest run --verbose

---

Comparison: cargo test vs cargo nextest

Syntax Translation

cargo test	cargo nextest run	Notes
cargo test	cargo nextest run	Run all tests
cargo test --lib	cargo nextest run --lib	Library tests only
cargo test --test integration	cargo nextest run --test integration	Specific test file
cargo test -- --nocapture	cargo nextest run --no-capture	Show output
cargo test -- --ignored	cargo nextest run --ignored	Run ignored tests

What's Different?

Advantages:

• ✅ Faster parallel execution (up to 60% speedup on 16-core systems)
• ✅ Better output formatting (cleaner, per-test timing)
• ✅ Automatic test retry for flaky tests
• ✅ JUnit XML reports for CI/CD
• ✅ Better test isolation (separate processes)

Limitations:

• ❌ No doctest support (use cargo test --doc separately)
• ⚠️ Different output format (may break parsing scripts)
• ⚠️ Requires separate installation

---

System-Specific Configuration

CPU Cores: 16

Default parallelism: 16 test threads

# Use all cores (default)
cargo nextest run

# Limit to 8 cores (for load testing)
cargo nextest run --test-threads 8

# Maximum parallelism
cargo nextest run --test-threads 32

---

Foxhunt-Specific Usage

Package-Level Testing

# Common library tests (fast)
cargo nextest run --package common

# ML tests (GPU-enabled)
cargo nextest run --package ml

# Trading service tests
cargo nextest run --package trading_service

# Backtesting service tests
cargo nextest run --package backtesting_service

Workspace-Level Testing

# All tests in parallel (recommended)
cargo nextest run --workspace

# All tests with timing info
cargo nextest run --workspace --verbose

# Skip slow tests
cargo nextest run --workspace --skip-pattern "slow_*"

CI/CD Integration

# Generate JUnit report for CI
cargo nextest run --workspace --junit test-results.xml --no-fail-fast

# Partition tests across 4 CI jobs
cargo nextest run --workspace --partition count:1/4  # Job 1
cargo nextest run --workspace --partition count:2/4  # Job 2
cargo nextest run --workspace --partition count:3/4  # Job 3
cargo nextest run --workspace --partition count:4/4  # Job 4

---

Performance Expectations

Compilation Phase

• Impact: Similar speed (±5%)
• Reason: Same rustc compiler

Test Execution Phase

• Expected speedup: 25-45% faster
• Reason: Better parallelism, 16 cores fully utilized

Overall Impact

• Small packages (common): 10-20% faster
• Large packages (trading_service): 30-50% faster
• Full workspace: 35-55% faster

---

When to Use Each Tool

Use cargo test when:

• Running doctests (cargo test --doc)
• Debugging single test with --show-output
• CI scripts depend on exact output format
• Quick smoke tests

Use cargo nextest run when:

• Running full workspace tests
• CI/CD pipelines (time savings)
• Load testing (better parallelism)
• Regular development (faster feedback)

---

Troubleshooting

"Blocking waiting for file lock"

Another cargo process is running. Wait or kill it:

# Check for active builds
ps aux | grep cargo

# Kill if needed
pkill -9 cargo

Tests fail with nextest but pass with cargo test

Possible causes:

• Test assumes sequential execution
• Shared resource contention
• Test isolation issues

Solution: Mark tests with #[serial] or run sequentially:

cargo nextest run --test-threads 1

Performance is worse

Check:

• Are tests CPU-bound or I/O-bound? (I/O won't benefit)
• System load (other processes competing for CPU)
• Small test suite (overhead dominates)

---

Quick Reference Card

# Basic usage
cargo nextest run              # Run all tests
cargo nextest list             # List tests

# Filtering
cargo nextest run -p common    # Specific package
cargo nextest run test_foo     # Pattern match

# Configuration
cargo nextest run -j 8         # 8 threads
cargo nextest run --no-capture # Show output
cargo nextest run --ignored    # Ignored tests

# CI/CD
cargo nextest run --junit junit.xml  # XML report
cargo nextest run --no-fail-fast     # Run all tests

---

Next Steps

1. Run benchmark: Execute ./benchmark_nextest.sh when cargo is idle
2. Try it: Run cargo nextest run --package common and compare
3. Integrate: If faster, update CI/CD workflows
4. Document: Update CLAUDE.md with new practices

---

Quick Links:

• Docs: https://nexte.st/
• Book: https://nexte.st/book/
• GitHub: https://github.com/nextest-rs/nextest

Status: ✅ Installed and ready to use Version: 0.9.105 System: 16-core Linux x86_64