build(ci): switch to cargo nextest for testing

Problem:
- cargo test runs integration tests in parallel in the same process
- This causes port conflicts when multiple tests try to start servers
- CI tests were failing with "Server failed to start within timeout"

Solution:
- Switch to cargo-nextest which runs tests in separate processes
- This provides better test isolation and prevents port conflicts

Changes:
- CI: Install and use cargo-nextest instead of cargo test
- README.md: Document nextest usage with installation instructions
- CONTRIBUTING.md: Add prominent note about using nextest
- CLAUDE.md: Add critical reminder section about nextest requirement

Why nextest:
- Tests run in separate processes (no port conflicts)
- Better test isolation and reliability
- Cleaner output and better performance
- Industry best practice for Rust integration testing

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

.github/workflows/ci.yml

@@ -31,6 +31,11 @@ jobs:
         with:
           components: rustfmt, clippy
 
+      - name: Install cargo-nextest
+        uses: taiki-e/install-action@v2
+        with:
+          tool: cargo-nextest
+
       - name: Cache cargo registry
         uses: actions/cache@v4
         with:
@@ -66,7 +71,7 @@ jobs:
         run: cargo build --verbose
 
       - name: Run tests
-        run: cargo test --verbose
+        run: cargo nextest run --verbose
 
   security:
     name: Security Audit

CLAUDE.md

@@ -25,14 +25,40 @@ cargo run --release
 # Check code without building
 cargo check
 
-# Run tests
+# Run tests (IMPORTANT: use cargo nextest, not cargo test)
-cargo test
+cargo nextest run
 
 # Run with logging (uses RUST_LOG environment variable)
 RUST_LOG=debug cargo run
 RUST_LOG=barycenter=trace cargo run
 ```
 
+## Testing
+
+**CRITICAL: Always use `cargo nextest run` instead of `cargo test`.**
+
+This project uses [cargo-nextest](https://nexte.st/) for running tests because:
+- Tests run in separate processes, preventing port conflicts in integration tests
+- Better test isolation and reliability
+- Cleaner output and better performance
+
+Install nextest if you don't have it:
+```bash
+cargo install cargo-nextest
+```
+
+Run tests:
+```bash
+# Run all tests
+cargo nextest run
+
+# Run with verbose output
+cargo nextest run --verbose
+
+# Run specific test
+cargo nextest run test_name
+```
+
 ## Configuration
 
 The application loads configuration from:

CONTRIBUTING.md

@@ -218,20 +218,35 @@ docs: update API endpoint documentation
 
 ## Testing
 
+**IMPORTANT: We use `cargo nextest` for running tests, not `cargo test`.**
+
+Nextest runs tests in separate processes, which prevents port conflicts and other issues when running integration tests in parallel.
+
 - Write unit tests for new functions
 - Add integration tests for new endpoints
 - Test both success and error cases
 - Aim for meaningful test coverage
 
+### Installing nextest
+
+```bash
+cargo install cargo-nextest
+```
+
+### Running Tests
+
 ```bash
 # Run all tests
-cargo test
+cargo nextest run
 
 # Run specific test
-cargo test test_name
+cargo nextest run test_name
 
-# Run with output
+# Run with verbose output
-cargo test -- --nocapture
+cargo nextest run --verbose
+
+# Run in release mode
+cargo nextest run --release
 ```
 
 ## Documentation

README.md

@@ -91,12 +91,17 @@ cargo check
 
 ### Testing
 
+**This project uses [cargo-nextest](https://nexte.st/) for running tests.**
+
 ```bash
+# Install nextest (one-time setup)
+cargo install cargo-nextest
+
 # Run all tests
-cargo test
+cargo nextest run
 
 # Run tests with logging
-RUST_LOG=debug cargo test
+RUST_LOG=debug cargo nextest run
 ```
 
 ### Logging