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/actions/test-python/action.yaml

@@ -54,11 +54,21 @@ runs:
         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
@@ -68,13 +78,31 @@ runs:
     #   - 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: ${{ inputs.dependencies == 'core' }}
       shell: bash
       run: |
         uv run --python ${{ inputs.python-version }} --group test pytest tests/ \
           -v \
-          ${{ inputs.os != 'windows-latest' && '-n auto' || '-p no:xdist' }} \
+          -p no:xdist \
+          ${{ inputs.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: ${{ inputs.dependencies == 'core' && inputs.os != 'windows-latest' }}
+      shell: bash
+      run: |
+        uv run --python ${{ inputs.python-version }} --group test pytest tests/ \
+          -v \
+          -n auto \
+          -m xdist_safe \
           -k "not test_cli" \
           --durations=10 \
           -p packages.pytest_changed \
@@ -85,13 +113,31 @@ runs:
         || { 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: ${{ inputs.dependencies == 'core,optional' }}
       shell: bash
       run: |
         uv run --python ${{ inputs.python-version }} --group test-optional pytest tests/ \
           -v \
-          ${{ inputs.os != 'windows-latest' && '-n auto' || '-p no:xdist' }} \
+          -p no:xdist \
+          ${{ inputs.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: ${{ inputs.dependencies == 'core,optional' && inputs.os != 'windows-latest' }}
+      shell: bash
+      run: |
+        uv run --python ${{ inputs.python-version }} --group test-optional pytest tests/ \
+          -v \
+          -n auto \
+          -m xdist_safe \
           -k "not test_cli" \
           --durations=10 \
           -p packages.pytest_changed \
@@ -104,15 +150,35 @@ runs:
     # 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: ${{ inputs.dependencies == 'minimal' }}
       shell: bash
       env:
         UV_RESOLUTION: lowest-direct
       run: |
         uv run --python ${{ inputs.python-version }} --group test pytest tests/ \
           -v \
-          ${{ inputs.os != 'windows-latest' && '-n auto' || '-p no:xdist' }} \
+          -p no:xdist \
+          ${{ inputs.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 with minimal dependencies (lowest resolution, xdist)
+      if: ${{ inputs.dependencies == 'minimal' && inputs.os != 'windows-latest' }}
+      shell: bash
+      env:
+        UV_RESOLUTION: lowest-direct
+      run: |
+        uv run --python ${{ inputs.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]