Make xdist opt-in

Tests can fail under xdist in surprising ways. When they fail
the failures are hard to debug (and cascade).

Author: akshayka

.github/workflows/test_be.yaml

@@ -186,11 +186,21 @@ jobs:
           fi
 
       # Test with base dependencies
-      # Exit code 5 = no tests collected (e.g. only CLI test files changed);
-      # treat that as success since CLI tests run in a separate workflow.
+      # Exit code 5 = no tests collected (e.g. only CLI test files changed,
+      # or no xdist_safe-marked tests in the changed set); treat that as
+      # success since CLI tests run in a separate workflow and the xdist
+      # step legitimately collects nothing when no marked modules changed.
       #
-      # TODO: xdist is disabled on Windows because several tests
-      # crash workers. Fix and re-enable. Failing tests:
+      # xdist is opt-in: tests run serially by default. Modules opt in by
+      # adding `pytestmark = pytest.mark.xdist_safe`. On Linux/macOS the
+      # serial step excludes xdist_safe and a second step runs the marked
+      # tests under -n auto. On Windows, xdist is disabled entirely and
+      # the serial step runs every test (marked tests included).
+      #
+      # Note: The following tests crashed workers on Windows under xdist.
+      # If/when any of their modules are opted into xdist_safe, re-verify
+      # behavior on Windows (Windows will still run them serially, but the
+      # underlying issues may resurface on Linux/macOS parallel runs):
       #   - tests/_islands/test_island_generator.py::test_build
       #   - tests/_islands/test_island_generator.py::test_render
       #   - tests/_islands/test_island_generator.py::test_render_multiline_markdown
@@ -200,12 +210,29 @@ jobs:
       #   - tests/_server/test_session_manager.py::test_create_session_absolute_url
       #   - tests/_server/test_session_manager.py::test_create_session_with_script_config_overrides
       #   - tests/_server/test_session_manager.py::test_recents_touch_called_on_session_create
-      - name: Test changed with base dependencies
+      - name: Test changed with base dependencies (serial)
         if: ${{ matrix.dependencies == 'core' }}
         run: |
           uv run --python ${{ matrix.python-version }} --group test pytest tests/ \
             -v \
-            ${{ matrix.os != 'windows-latest' && '-n auto' || '-p no:xdist' }} \
+            -p no:xdist \
+            ${{ matrix.os != 'windows-latest' && '-m "not xdist_safe"' || '' }} \
+            -k "not test_cli" \
+            --durations=10 \
+            -p packages.pytest_changed \
+            --changed-from=${{ steps.setup-flags.outputs.changed_from }} \
+            --include-unchanged=${{ steps.setup-flags.outputs.include_unchanged }} \
+            --picked=first \
+            --inline-snapshot=disable \
+          || { ec=$?; [ $ec -eq 5 ] && exit 0 || exit $ec; }
+
+      - name: Test changed with base dependencies (xdist)
+        if: ${{ matrix.dependencies == 'core' && matrix.os != 'windows-latest' }}
+        run: |
+          uv run --python ${{ matrix.python-version }} --group test pytest tests/ \
+            -v \
+            -n auto \
+            -m xdist_safe \
             -k "not test_cli" \
             --durations=10 \
             -p packages.pytest_changed \
@@ -216,12 +243,29 @@ jobs:
           || { ec=$?; [ $ec -eq 5 ] && exit 0 || exit $ec; }
 
       # Test with optional dependencies
-      - name: Test changed with optional dependencies
+      - name: Test changed with optional dependencies (serial)
         if: ${{ matrix.dependencies == 'core,optional' }}
         run: |
           uv run --python ${{ matrix.python-version }} --group test-optional pytest tests/ \
             -v \
-            ${{ matrix.os != 'windows-latest' && '-n auto' || '-p no:xdist' }} \
+            -p no:xdist \
+            ${{ matrix.os != 'windows-latest' && '-m "not xdist_safe"' || '' }} \
+            -k "not test_cli" \
+            --durations=10 \
+            -p packages.pytest_changed \
+            --changed-from=${{ steps.setup-flags.outputs.changed_from }} \
+            --include-unchanged=${{ steps.setup-flags.outputs.include_unchanged }} \
+            --picked=first \
+            --inline-snapshot=disable \
+          || { ec=$?; [ $ec -eq 5 ] && exit 0 || exit $ec; }
+
+      - name: Test changed with optional dependencies (xdist)
+        if: ${{ matrix.dependencies == 'core,optional' && matrix.os != 'windows-latest' }}
+        run: |
+          uv run --python ${{ matrix.python-version }} --group test-optional pytest tests/ \
+            -v \
+            -n auto \
+            -m xdist_safe \
             -k "not test_cli" \
             --durations=10 \
             -p packages.pytest_changed \
@@ -234,12 +278,31 @@ jobs:
       # Test with minimal dependencies using lowest resolution
       # https://docs.astral.sh/uv/concepts/resolution/#lowest-resolution
       # https://docs.astral.sh/uv/reference/environment/#uv_resolution
-      - name: Test with minimal dependencies (lowest resolution)
+      - name: Test with minimal dependencies (lowest resolution, serial)
         if: ${{ matrix.dependencies == 'minimal' }}
         run: |
           uv run --python ${{ matrix.python-version }} --group test pytest tests/ \
             -v \
-            ${{ matrix.os != 'windows-latest' && '-n auto' || '-p no:xdist' }} \
+            -p no:xdist \
+            ${{ matrix.os != 'windows-latest' && '-m "not xdist_safe"' || '' }} \
+            -k "not test_cli" \
+            --durations=10 \
+            -p packages.pytest_changed \
+            --changed-from=${{ steps.setup-flags.outputs.changed_from }} \
+            --include-unchanged=${{ steps.setup-flags.outputs.include_unchanged }} \
+            --picked=first \
+            --inline-snapshot=disable \
+          || { ec=$?; [ $ec -eq 5 ] && exit 0 || exit $ec; }
+        env:
+          UV_RESOLUTION: lowest-direct
+
+      - name: Test with minimal dependencies (lowest resolution, xdist)
+        if: ${{ matrix.dependencies == 'minimal' && matrix.os != 'windows-latest' }}
+        run: |
+          uv run --python ${{ matrix.python-version }} --group test pytest tests/ \
+            -v \
+            -n auto \
+            -m xdist_safe \
             -k "not test_cli" \
             --durations=10 \
             -p packages.pytest_changed \

AGENTS.md

@@ -41,6 +41,26 @@ make fe-check              # Typecheck and lint frontend
 cd frontend && pnpm test src/path/to/file.test.ts
 ```
 
+## Parallel tests (xdist)
+
+Backend tests run **serially by default** in CI. Tests are opted into
+parallel execution under `pytest-xdist` only after being audited as
+independent (no shared global state, no port/file collisions, no reliance
+on collection order).
+
+To opt a module in, add near the top of the test file:
+
+```python
+import pytest
+
+pytestmark = pytest.mark.xdist_safe
+```
+
+Individual tests or classes can also be opted in via
+`@pytest.mark.xdist_safe`. If a regression appears under parallel
+execution, the fastest fix is to remove the marker from the offending
+module and open an issue — do not re-disable xdist globally.
+
 ## Commits
 
 - Run `make check` before committing

pyproject.toml

@@ -521,6 +521,7 @@ markers = [
     "unit: marks tests as unit tests",
     "flaky: marks tests that are known to be flaky",
     "requires(dep1, dep2, ...): requires one or more dependencies to be installed",
+    "xdist_safe: module/test has been audited as safe to run under pytest-xdist (-n auto)",
 ]
 
 [tool.coverage.run]