Reduce xdist worker count on Windows

[strawgate]

GitHub Runners on Windows are extremely slow, we should reduce the worker count to 2 for xdist to improve test reliability

[claude]

Claude finished @strawgate's task —— View job

---

Investigation Complete ✓

Tasks

• Generate project summary
• Get issue details
• Search for related issues and pull requests
• Locate pytest-xdist configuration files
• Analyze current xdist setup
• Provide recommendation and detailed action plan

---

Recommendation

Configure pytest-xdist to use 2 workers on Windows by adding a platform-specific pytest flag in the test workflow configuration. The current configuration uses -n=auto which automatically detects CPU cores and creates one worker per core. On Windows runners, this leads to excessive parallelization and test instability.

The solution is to add a conditional pytest argument in .github/workflows/test.yml that sets -n=2 specifically for Windows platforms while keeping -n=auto for Linux and macOS.

---

Findings

Current xdist Configuration

pytest-xdist is currently configured in three project pyproject.toml files with identical settings:

Files:

• key-value/key-value-aio/pyproject.toml (lines 55-67)
• key-value/key-value-sync/pyproject.toml (lines 54-66)
• key-value/key-value-shared/pyproject.toml (lines 31-43)

Current Settings:

[tool.pytest.ini_options]
asyncio_mode = "auto"
addopts = [
    "--inline-snapshot=disable",
    "-n=auto",              # ← Automatically uses all CPU cores
    "--dist=loadfile",      # ← One file per worker (correct for these tests)
    "--maxfail=5"
]
timeout = 10
timeout_func_only = true

Key Observations

1. -n=auto: Automatically creates one worker per CPU core. Windows runners typically have 2-4 cores, but tests run significantly slower on Windows.

2. --dist=loadfile: Correctly configured to distribute entire test files to workers, not individual tests. This was mentioned in issue MultiDiskStore on Windows test flaky #166 and prevents test isolation issues.

3. Test Platforms: The workflow runs tests on 6 platforms:

   • ubuntu-22.04, ubuntu-latest
   • macos-14, macos-latest
   • windows-2022, windows-latest

4. Related Issues:

   • Issue MultiDiskStore on Windows test flaky #166: "MultiDiskStore on Windows test flaky" - Windows worker crashes
   • Issue Ubuntu 22.04 tests hanging #129: "Ubuntu 22.04 tests hanging" - Performance issues on specific platforms
   • Issue Improve test runtime #82: "Improve test runtime" - Original PR that added xdist

Why Windows Is Slow

GitHub-hosted Windows runners are known to be 2-4x slower than Linux runners for Python tests due to:

• Slower I/O operations
• Different process spawning overhead
• Filesystem locking differences
• Container/virtualization overhead

Detailed Action Plan

Implementation Steps

Step 1: Modify .github/workflows/test.yml

Add a conditional pytest argument for Windows platforms in both test_quick and test_all jobs.

For test_quick job (lines 148-149):

Replace:

- name: "Test with latest dependencies"
  run: uv run pytest tests . -vv
  working-directory: ${{ matrix.project }}

With:

- name: "Test with latest dependencies"
  run: |
    if [[ "${{ matrix.platform }}" == windows-* ]]; then
      uv run pytest tests . -vv -n=2
    else
      uv run pytest tests . -vv
    fi
  working-directory: ${{ matrix.project }}
  shell: bash

And replace (lines 156-158):

- name: "Test with oldest dependencies"
  run: uv run pytest tests . -vv
  working-directory: ${{ matrix.project }}

With:

- name: "Test with oldest dependencies"
  run: |
    if [[ "${{ matrix.platform }}" == windows-* ]]; then
      uv run pytest tests . -vv -n=2
    else
      uv run pytest tests . -vv
    fi
  working-directory: ${{ matrix.project }}
  shell: bash

For test_all job (lines 199-201):

Replace:

- name: "Test with latest dependencies"
  run: uv run pytest tests . -vv
  working-directory: ${{ matrix.project }}

With:

- name: "Test with latest dependencies"
  run: |
    if [[ "${{ matrix.platform }}" == windows-* ]]; then
      uv run pytest tests . -vv -n=2
    else
      uv run pytest tests . -vv
    fi
  working-directory: ${{ matrix.project }}
  shell: bash

And replace (lines 207-209):

- name: "Test with oldest dependencies"
  run: uv run pytest tests . -vv
  working-directory: ${{ matrix.project }}

With:

- name: "Test with oldest dependencies"
  run: |
    if [[ "${{ matrix.platform }}" == windows-* ]]; then
      uv run pytest tests . -vv -n=2
    else
      uv run pytest tests . -vv
    fi
  working-directory: ${{ matrix.project }}
  shell: bash

Step 2: Test the Changes

1. Commit and push the workflow changes
2. Monitor the next CI run on a PR or push
3. Verify Windows tests complete successfully with 2 workers
4. Check that Linux and macOS tests still use -n=auto

Step 3: Monitor Test Reliability

After merging, monitor Windows test runs for:

• Reduced flakiness
• Improved completion rates
• Acceptable test duration (should still be faster than sequential)

Alternative Approach (Not Recommended)

An alternative would be to modify the pyproject.toml files to set -n=2 globally, but this would:

• Reduce parallelization on Linux/macOS unnecessarily
• Increase overall CI time
• Not take advantage of faster platforms

The workflow-level conditional is the best solution.

Related Items

Related Issues and Pull Requests

Repository	Issue or PR	Relevance
strawgate/py-key-value	#166: MultiDiskStore on Windows test flaky	Directly related - Windows worker crashes during parallel test execution
strawgate/py-key-value	#129: Ubuntu 22.04 tests hanging	Similar issue - platform-specific test performance problems
strawgate/py-key-value	#82: Improve test runtime	Original issue that led to implementing pytest-xdist
strawgate/py-key-value	#233: fix: separate fixture timeouts from test timeouts	Recent fix for test timeout handling

Related Files

Repository	File	Relevance	Sections
strawgate/py-key-value	.github/workflows/test.yml	CI workflow that runs tests - needs modification	112-163, 164-214
strawgate/py-key-value	key-value/key-value-aio/pyproject.toml	Contains pytest-xdist configuration with -n=auto	55-67
strawgate/py-key-value	key-value/key-value-sync/pyproject.toml	Contains pytest-xdist configuration with -n=auto	54-66
strawgate/py-key-value	key-value/key-value-shared/pyproject.toml	Contains pytest-xdist configuration with -n=auto	31-43

Related Webpages

Name	URL	Relevance
pytest-xdist Documentation	https://pytest-xdist.readthedocs.io/	Official documentation for the parallelization plugin
GitHub Actions: Windows Runners	https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources	Information about Windows runner performance characteristics

---

Problems Encountered During Investigation

None - all investigation tools were accessible and provided comprehensive information about the codebase, test infrastructure, and related issues.

---

[strawgate]

@claude please make a pull request for this

[claude]

Claude finished @strawgate's task —— View job

---

Windows xdist worker reduction - Permission Issue

Tasks

• Read current workflow configuration
• Implement conditional xdist worker count for Windows
• Attempt to commit and push changes
• Document permission issue and provide alternatives

---

Issue Encountered

I successfully implemented the changes to reduce xdist worker count to 2 on Windows, but I'm unable to push the changes due to GitHub App permissions. Modifying workflow files (.github/workflows/*.yml) requires the workflows permission, which is restricted for security reasons.

Error:

! [remote rejected] claude/issue-242-20251112-1607 -> claude/issue-242-20251112-1607 
(refusing to allow a GitHub App to create or update workflow `.github/workflows/test.yml` 
without `workflows` permission)

---

Changes Required

I've prepared the exact changes needed for .github/workflows/test.yml. You'll need to apply these changes manually:

For test_quick job (lines 148-170):

Replace:

      - name: "Test with latest dependencies"
        run: uv run pytest tests . -vv
        working-directory: ${{ matrix.project }}

      - name: "Install oldest dependencies"
        run: uv sync --group dev --python ${{ matrix.python-version }} --resolution lowest-direct
        working-directory: ${{ matrix.project }}

      - name: "Test with oldest dependencies"
        run: uv run pytest tests . -vv
        working-directory: ${{ matrix.project }}

With:

      - name: "Test with latest dependencies"
        run: |
          if [[ "${{ matrix.platform }}" == windows-* ]]; then
            uv run pytest tests . -vv -n=2
          else
            uv run pytest tests . -vv
          fi
        working-directory: ${{ matrix.project }}
        shell: bash

      - name: "Install oldest dependencies"
        run: uv sync --group dev --python ${{ matrix.python-version }} --resolution lowest-direct
        working-directory: ${{ matrix.project }}

      - name: "Test with oldest dependencies"
        run: |
          if [[ "${{ matrix.platform }}" == windows-* ]]; then
            uv run pytest tests . -vv -n=2
          else
            uv run pytest tests . -vv
          fi
        working-directory: ${{ matrix.project }}
        shell: bash

For test_all job (lines 211-233):

Replace:

      - name: "Test with latest dependencies"
        run: uv run pytest tests . -vv
        working-directory: ${{ matrix.project }}

      - name: "Install oldest dependencies"
        run: uv sync --group dev --python ${{ matrix.python-version }} --resolution lowest-direct
        working-directory: ${{ matrix.project }}

      - name: "Test with oldest dependencies"
        run: uv run pytest tests . -vv
        working-directory: ${{ matrix.project }}

With:

      - name: "Test with latest dependencies"
        run: |
          if [[ "${{ matrix.platform }}" == windows-* ]]; then
            uv run pytest tests . -vv -n=2
          else
            uv run pytest tests . -vv
          fi
        working-directory: ${{ matrix.project }}
        shell: bash

      - name: "Install oldest dependencies"
        run: uv sync --group dev --python ${{ matrix.python-version }} --resolution lowest-direct
        working-directory: ${{ matrix.project }}

      - name: "Test with oldest dependencies"
        run: |
          if [[ "${{ matrix.platform }}" == windows-* ]]; then
            uv run pytest tests . -vv -n=2
          else
            uv run pytest tests . -vv
          fi
        working-directory: ${{ matrix.project }}
        shell: bash

---

How This Works

The changes add conditional logic that:

• Detects when running on Windows platforms (windows-2022, windows-latest)
• Uses -n=2 to limit pytest-xdist to 2 workers on Windows
• Uses the default -n=auto (from pyproject.toml) on Linux and macOS

This will improve test reliability on Windows while maintaining optimal parallelization on faster platforms.

---

Alternative Approaches

If you prefer a different solution, here are alternatives:

1. Environment variable approach: Set a PYTEST_XDIST_WORKERS environment variable and reference it in pyproject.toml
2. Separate pytest config: Create a Windows-specific pytest configuration file
3. Grant workflows permission: Enable the workflows permission for the Claude Code GitHub App (see FAQ)

---

| Branch: claude/issue-242-20251112-1607 (local changes only)