Use --dist=worksteal to speed up tests + move -n auto to config to make it default

.claude/skills/tool-renderer/SKILL.md

@@ -369,7 +369,7 @@ class Test{ToolName}OutputFormatting:
 uv run pytest test/test_{toolname}_rendering.py -v
 
 # Run full test suite to check for regressions
-uv run pytest -n auto -m "not (tui or browser)" -v
+uv run pytest -m "not (tui or browser)" -v
 ```
 
 ## Checklist

.github/workflows/ci.yml

@@ -33,13 +33,13 @@ jobs:
       run: uv sync --all-extras --dev && uv run playwright install chromium
 
     - name: Run unit tests with coverage
-      run: uv run pytest -n auto -m "not (tui or browser or benchmark)" --cov=claude_code_log --cov-report=xml --cov-report=html --cov-report=term
+      run: uv run pytest -m "not (tui or browser or benchmark)" --cov=claude_code_log --cov-report=xml --cov-report=html --cov-report=term
 
     - name: Run TUI tests with coverage append
-      run: uv run pytest -n auto -m tui --cov=claude_code_log --cov-append --cov-report=xml --cov-report=html --cov-report=term
+      run: uv run pytest -m tui --cov=claude_code_log --cov-append --cov-report=xml --cov-report=html --cov-report=term
 
     - name: Run browser tests with coverage append
-      run: uv run pytest -n auto -m browser --cov=claude_code_log --cov-append --cov-report=xml --cov-report=html --cov-report=term
+      run: uv run pytest -m browser --cov=claude_code_log --cov-append --cov-report=xml --cov-report=html --cov-report=term
 
     - name: Run benchmark tests with coverage append (primary only)
       if: matrix.is-primary

CLAUDE.md

@@ -51,26 +51,26 @@ See @CONTRIBUTING.md for detailed development setup, testing, architecture, and
 
 ### Claude-Specific Testing Tips
 
-**Always use `-n auto` for parallel test execution:**
+**Config in `pyproject.toml` sets `-n auto --dist=worksteal` so you might need to unset for pdb, etc**
 
 ```bash
 # Unit tests (fast, recommended for development)
 just test
-# or: uv run pytest -n auto -m "not (tui or browser)" -v
+# or: uv run pytest -m "not (tui or browser)" -v
 
 # TUI tests
 just test-tui
-# or: uv run pytest -n auto -m tui
+# or: uv run pytest -m tui
 
 # Browser tests
 just test-browser
-# or: uv run pytest -n auto -m browser
+# or: uv run pytest -m browser
 
 # All tests
 just test-all
 ```
 
-**Tip:** Add `-x` to stop on first failure (e.g., `uv run pytest -n auto -m "not (tui or browser)" -v -x`).
+**Tip:** Add `-x` to stop on first failure (e.g., `uv run pytest -m "not (tui or browser)" -v -x`).
 
 ### Code Quality
 

CONTRIBUTING.md

@@ -96,7 +96,7 @@ The project uses a categorized test system to avoid async event loop conflicts.
 ```bash
 # Unit tests only (fast, recommended for development)
 just test
-# or: uv run pytest -n auto -m "not (tui or browser)" -v
+# or: uv run pytest -m "not (tui or browser)" -v
 
 # TUI tests (isolated event loop)
 just test-tui
@@ -117,21 +117,18 @@ Snapshot tests detect unintended HTML output changes using [syrupy](https://gith
 
 ```bash
 # Run snapshot tests (parallel mode is fine for read-only runs)
-uv run pytest -n auto test/test_snapshot_html.py -v
+uv run pytest test/test_snapshot_html.py -v
 
 # Update snapshots after intentional HTML changes
-# IMPORTANT: run --snapshot-update WITHOUT -n auto (see warning below)
-uv run pytest test/test_snapshot_html.py --snapshot-update
+# IMPORTANT: run --snapshot-update with -n0 (see warning below)
+uv run pytest test/test_snapshot_html.py -n0 --snapshot-update
 ```
 
-> **Warning — don't combine `--snapshot-update` with `-n auto`.** Syrupy
+> **Warning — don't let `--snapshot-update` run with `-n auto`.** Syrupy
 > and pytest-xdist race when writing snapshot files in parallel: the
 > `.ambr` file ends up truncated (observed: ~6000 lines silently
 > deleted on a single run, leaving the file structurally broken but
-> still passing on next read). Run `--snapshot-update` serially. This
-> is also why pytest is **not** configured with a default `-n auto`
-> in `pyproject.toml`; the `just test` recipes opt in for read-only
-> runs where the race doesn't apply.
+> still passing on next read). Run `--snapshot-update` serially.
 
 When snapshot tests fail:
 1. Review the diff to verify changes are intentional
@@ -163,7 +160,7 @@ Running all tests together can cause "RuntimeError: This event loop is already r
 just test-cov
 
 # Or manually:
-uv run pytest -n auto --cov=claude_code_log --cov-report=html --cov-report=term
+uv run pytest --cov=claude_code_log --cov-report=html --cov-report=term
 ```
 
 HTML coverage reports are generated in `htmlcov/index.html`.

justfile

@@ -5,47 +5,45 @@ default:
 cli *ARGS:
     uv run claude-code-log {{ ARGS }}
 
-# Run only unit tests (fast, no external dependencies)
+# Run unit + integration tests (excludes TUI, browser, and benchmark)
 test:
-    uv run pytest -n auto -m "not (tui or browser or benchmark)" -v
+    uv run pytest -m "not (tui or browser or benchmark)" -v
 
-# Run benchmark tests (outputs to GITHUB_STEP_SUMMARY in CI)
-
-# DEBUG_TIMING enables coverage of renderer_timings.py
+# Run benchmark tests serially for stable measurements (outputs to GITHUB_STEP_SUMMARY in CI). DEBUG_TIMING enables coverage of renderer_timings.py
 test-benchmark:
-    CLAUDE_CODE_LOG_DEBUG_TIMING=1 uv run pytest -m benchmark -v
+    CLAUDE_CODE_LOG_DEBUG_TIMING=1 uv run pytest -n0 -m benchmark -v
 
 # Update snapshot tests (runs serially for deterministic file ordering)
 update-snapshot:
-    uv run pytest -m snapshot --snapshot-update -v
+    uv run pytest -n0 -m snapshot --snapshot-update -v
 
 # Run TUI tests (requires isolated event loop)
 test-tui:
-    uv run pytest -n auto -m tui -v
+    uv run pytest -m tui -v
 
 # Run browser tests (requires Chromium)
 test-browser:
-    uv run pytest -n auto -m browser -v
+    uv run pytest -m browser -v
 
 # Run integration tests with realistic JSONL data
 test-integration:
-    uv run pytest -n auto -m integration -v
+    uv run pytest -m integration -v
 
 # Run all tests in sequence (separated to avoid event loop conflicts)
 test-all:
     #!/usr/bin/env bash
     set -e  # Exit on first failure
     echo "🧪 Running all tests in sequence..."
     echo "📦 Running unit tests..."
-    uv run pytest -n auto -m "not (tui or browser or integration or benchmark)" -v
+    uv run pytest -m "not (tui or browser or integration or benchmark)" -v
     echo "🖥️  Running TUI tests..."
-    uv run pytest -n auto -m tui -v
+    uv run pytest -m tui -v
     echo "🌐 Running browser tests..."
-    uv run pytest -n auto -m browser -v
+    uv run pytest -m browser -v
     echo "🔄 Running integration tests..."
-    uv run pytest -n auto -m integration -v
+    uv run pytest -m integration -v
     echo "📊 Running benchmark tests..."
-    CLAUDE_CODE_LOG_DEBUG_TIMING=1 uv run pytest -m benchmark -v
+    CLAUDE_CODE_LOG_DEBUG_TIMING=1 uv run pytest -n0 -m benchmark -v
     echo "✅ All tests completed!"
 
 # Run tests with coverage (all categories)
@@ -54,15 +52,15 @@ test-cov:
     set -e  # Exit on first failure
     echo "📊 Running all tests with coverage..."
     echo "📦 Running unit tests with coverage..."
-    uv run pytest -n auto -m "not (tui or browser or integration or benchmark)" --cov=claude_code_log --cov-report=xml --cov-report=html --cov-report=term -v
+    uv run pytest -m "not (tui or browser or integration or benchmark)" --cov=claude_code_log --cov-report=xml --cov-report=html --cov-report=term -v
     echo "🖥️  Running TUI tests with coverage append..."
-    uv run pytest -n auto -m tui --cov=claude_code_log --cov-append --cov-report=xml --cov-report=html --cov-report=term -v
+    uv run pytest -m tui --cov=claude_code_log --cov-append --cov-report=xml --cov-report=html --cov-report=term -v
     echo "🌐 Running browser tests with coverage append..."
-    uv run pytest -n auto -m browser --cov=claude_code_log --cov-append --cov-report=xml --cov-report=html --cov-report=term -v
+    uv run pytest -m browser --cov=claude_code_log --cov-append --cov-report=xml --cov-report=html --cov-report=term -v
     echo "🔄 Running integration tests with coverage append..."
-    uv run pytest -n auto -m integration --cov=claude_code_log --cov-append --cov-report=xml --cov-report=html --cov-report=term -v
+    uv run pytest -m integration --cov=claude_code_log --cov-append --cov-report=xml --cov-report=html --cov-report=term -v
     echo "📊 Running benchmark tests with coverage append..."
-    CLAUDE_CODE_LOG_DEBUG_TIMING=1 uv run pytest -m benchmark --cov=claude_code_log --cov-append --cov-report=xml --cov-report=html --cov-report=term -v
+    CLAUDE_CODE_LOG_DEBUG_TIMING=1 uv run pytest -n0 -m benchmark --cov=claude_code_log --cov-append --cov-report=xml --cov-report=html --cov-report=term -v
     echo "✅ All tests with coverage completed!"
 
 format:

pyproject.toml

@@ -46,6 +46,11 @@ exclude = ["/docs", "/test", "/scripts"]
 testpaths = ["test"]
 asyncio_mode = "auto"
 asyncio_default_fixture_loop_scope = "function"
+# Parallelise across all cores; worksteal rebalances heavyweight integration
+# tests across workers (default `load` left workers idle while one slogged
+# through the queue). Override with `-n0 --dist=no` for serial runs, or with
+# `--dist=no --pdb` for debugging (worksteal distribution must be disabled).
+addopts = "-n auto --dist=worksteal"
 markers = [
     "tui: TUI tests using Textual framework (requires isolated event loop)",
     "browser: Browser integration tests using Playwright (requires Chromium)",

test/README.md

@@ -148,10 +148,10 @@ Snapshot tests capture the full HTML output and detect unintended regressions. T
 
 ```bash
 # Run snapshot tests
-uv run pytest -n auto test/test_snapshot_html.py -v
+uv run pytest test/test_snapshot_html.py -v
 
 # Update snapshots after intentional HTML changes
-uv run pytest -n auto test/test_snapshot_html.py --snapshot-update
+uv run pytest -n0 test/test_snapshot_html.py --snapshot-update
 
 # Review changes before committing
 git diff test/__snapshots__/
@@ -170,28 +170,28 @@ git diff test/__snapshots__/
 ```bash
 # Run only unit tests (fast, recommended for development)
 just test
-# or: uv run pytest -n auto -m "not (tui or browser or integration)" -v
+# or: uv run pytest -m "not (tui or browser or integration)" -v
 
 # Run TUI tests (isolated event loop)
 just test-tui
-# or: uv run pytest -n auto -m tui -v
+# or: uv run pytest -m tui -v
 
 # Run browser tests (requires Chromium)
 just test-browser
-# or: uv run pytest -n auto -m browser -v
+# or: uv run pytest -m browser -v
 
 # Run integration tests with realistic data
 just test-integration
-# or: uv run pytest -n auto -m integration -v
+# or: uv run pytest -m integration -v
 
 # Run all tests in sequence (separated to avoid conflicts)
 just test-all
 
 # Run specific test file
-uv run pytest -n auto test/test_template_rendering.py -v
+uv run pytest test/test_template_rendering.py -v
 
 # Run specific test method
-uv run pytest -n auto test/test_template_rendering.py::TestTemplateRendering::test_representative_messages_render -v
+uv run pytest test/test_template_rendering.py::TestTemplateRendering::test_representative_messages_render -v
 
 # Run tests with coverage
 just test-cov
@@ -214,10 +214,10 @@ Generate detailed coverage reports:
 
 ```bash
 # Run tests with coverage and HTML report
-uv run pytest -n auto --cov=claude_code_log --cov-report=html --cov-report=term
+uv run pytest --cov=claude_code_log --cov-report=html --cov-report=term
 
 # View coverage by module
-uv run pytest -n auto --cov=claude_code_log --cov-report=term-missing
+uv run pytest --cov=claude_code_log --cov-report=term-missing
 
 # Open HTML coverage report
 open htmlcov/index.html