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! ✅

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

---

## Basic Usage

### Replace `cargo test` with `cargo nextest run`

```bash
# 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

```bash
# 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**

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
# 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:

```bash
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

```bash
# 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