Run the CI test job in parallel with pytest-xdist

.github/workflows/ci.yml

@@ -30,8 +30,11 @@ jobs:
 
   test:
     runs-on: ubuntu-latest
-    # Slowest of 12 successful runs, 2026-10-05..08: 7.2 minutes. Fail a hung
-    # job instead of holding a shared runner for GitHub's 6-hour default.
+    # Serially, the test job on main took 29.5 minutes at b0c8f2e and hit
+    # this limit at ec5413c (2026-11-02). In parallel it took 12.3 minutes
+    # with -n logical (4 workers, run 41526298328), and 12.5 to 16.2 minutes
+    # in three attempts with -n auto (run 41490222217). Fail a hung job
+    # instead of holding a shared runner for GitHub's 6-hour default.
     timeout-minutes: 30
     steps:
       - uses: actions/checkout@v6
@@ -44,7 +47,11 @@ jobs:
           python-version: "3.12"
       - run: pip install uv
       - run: uv sync --locked --extra dev
-      - run: uv run pytest -m "not slow" --tb=short -q
+      # One worker per logical CPU (-n auto would count physical cores, since
+      # psutil is installed); the "created: N/N workers" line gives the count.
+      # --dist loadfile keeps each test file on one worker; on the 4-core VM it
+      # ran faster than --dist load (10.1 minutes).
+      - run: uv run pytest -m "not slow" -n logical --dist loadfile --tb=short
 
   app:
     runs-on: ubuntu-latest

CLAUDE.md

@@ -28,6 +28,8 @@ ruff format .             # Format
 ## Testing
 - All tests mock external calls (LiteLLM, PE-US API)
 - `pytest -m "not slow"` to skip slow tests
+- `pytest -m "not slow" -n 4 --dist loadfile` to split them across four workers (CI starts one per CPU)
+- Some tests read git history, so run the suite from a full clone (`git fetch --unshallow`)
 - Full benchmark runs are manual and expensive
 
 ## Formatting

pyproject.toml

@@ -26,6 +26,7 @@ dev = [
     "hypothesis>=6.100",
     "pytest>=8.0",
     "pytest-cov>=5.0",
+    "pytest-xdist>=3.6",
     "ruff>=0.4",
 ]
 # The paper render environment (paper/render_paper.py, .github/workflows/paper.yml):

tests/test_reference_audit_pins.py

@@ -513,7 +513,7 @@ def call(*args, **kwargs):
 
 @pytest.mark.parametrize(
     ("audit", "path"),
-    [(audit, path) for audit in IMPACT for path in IMPACT[audit].inputs],
+    [(audit, path) for audit in IMPACT for path in sorted(IMPACT[audit].inputs)],
 )
 def test_any_refused_input_stops_the_impact_script_before_it_scores(
     scratch, monkeypatch, audit, path
@@ -533,7 +533,7 @@ def test_any_refused_input_stops_the_impact_script_before_it_scores(
 
 @pytest.mark.parametrize(
     ("script", "path"),
-    [(script, path) for script in DIRECT for path in DIRECT[script].inputs],
+    [(script, path) for script in DIRECT for path in sorted(DIRECT[script].inputs)],
 )
 def test_any_refused_input_stops_the_direct_script_before_it_writes(
     scratch, monkeypatch, script, path