diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index b8431f1..e27b4ea 100644
--- a/.github/workflows/ci.yml
+++ b/.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
diff --git a/CLAUDE.md b/CLAUDE.md
index 902c522..466f4c6 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -25,14 +25,40 @@ cargo run --release
 # Check code without building
 cargo check
 
-# Run tests
-cargo test
+# Run tests (IMPORTANT: use cargo nextest, not 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:
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index f5a8afb..93bdfda 100644
--- a/CONTRIBUTING.md
+++ b/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
-cargo test -- --nocapture
+# Run with verbose output
+cargo nextest run --verbose
+
+# Run in release mode
+cargo nextest run --release
 ```
 
 ## Documentation
diff --git a/README.md b/README.md
index 8a23f6a..5a7f66a 100644
--- a/README.md
+++ b/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