Simplify Windows debug scripts based on working solution

- Add setup-environment.ps1 to configure Git for Windows tee in PATH
- Simplify all scripts to use working -o addopts="" approach
- Add tee availability checks to all scripts
- Update README with clear setup instructions and troubleshooting
- Remove complex xdist workarounds in favor of simple override

Author: felixweinberger

scripts/windows-debug/README.md

@@ -8,31 +8,64 @@ This folder contains PowerShell scripts to help debug the flaky `test_stdio_cont
 - Python 3.11 or 3.12
 - `uv` installed and configured
 - Virtual environment activated
+- Git for Windows installed (provides the `tee` command)
+
+## Quick Start
+
+1. First, set up your environment to make `tee` available:
+   ```powershell
+   . .\setup-environment.ps1
+   ```
+   **Note:** The dot (.) at the beginning is important - it sources the script.
+
+2. Verify the test runs:
+   ```powershell
+   .\test-stdio-simple.ps1
+   ```
+
+3. Run the flakiness tests:
+   ```powershell
+   .\test-stdio-flakiness-200-runs.ps1
+   ```
 
 ## Scripts
 
-### 1. `check-tee-command.ps1`
+### 1. `setup-environment.ps1`
+Sets up the environment by adding Git for Windows tools to PATH. **Must be dot-sourced.**
+
+```powershell
+. .\setup-environment.ps1
+```
+
+### 2. `check-tee-command.ps1`
 Checks if the `tee` command is available on your Windows system. The test requires `tee` to run.
 
 ```powershell
 .\check-tee-command.ps1
 ```
 
-### 2. `test-stdio-flakiness-200-runs.ps1`
+### 3. `test-stdio-simple.ps1`
+Runs the test once to verify it works.
+
+```powershell
+.\test-stdio-simple.ps1
+```
+
+### 4. `test-stdio-flakiness-200-runs.ps1`
 Runs the test 200 times and reports the failure rate.
 
 ```powershell
 .\test-stdio-flakiness-200-runs.ps1
 ```
 
-### 3. `test-stdio-flakiness-until-failure.ps1`
+### 5. `test-stdio-flakiness-until-failure.ps1`
 Runs the test in a loop until it fails, useful for catching intermittent failures.
 
 ```powershell
 .\test-stdio-flakiness-until-failure.ps1
 ```
 
-### 4. `test-stdio-verbose-debug.ps1`
+### 6. `test-stdio-verbose-debug.ps1`
 Runs the test once with maximum debugging output enabled.
 
 ```powershell
@@ -42,8 +75,9 @@ Runs the test once with maximum debugging output enabled.
 ## Usage Notes
 
 1. Make sure your virtual environment is activated before running these scripts
-2. Run scripts from the repository root directory
-3. If scripts fail with execution policy errors, run:
+2. Always run `setup-environment.ps1` first in each new PowerShell session
+3. Run scripts from the `scripts\windows-debug` directory
+4. If scripts fail with execution policy errors, run:
    ```powershell
    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
    ```
@@ -52,4 +86,20 @@ Runs the test once with maximum debugging output enabled.
 
 - If `tee` is not available, the test will be skipped
 - Flaky failures typically show up as timeout errors or process cleanup issues
-- Look for patterns in failure output, especially around process termination timing
+- Look for patterns in failure output, especially around process termination timing
+
+## Troubleshooting
+
+### "tee command not found"
+1. Install Git for Windows from https://gitforwindows.org/
+2. Run `. .\setup-environment.ps1` to add Git tools to PATH
+3. Verify with `python -c "import shutil; print(shutil.which('tee'))"`
+
+### "no tests ran" with xdist
+The scripts now use `-o addopts=""` to override the pytest configuration that enables xdist by default.
+
+### Making PATH changes permanent
+Add this line to your PowerShell profile:
+```powershell
+$env:PATH = "C:\Program Files\Git\usr\bin;$env:PATH"
+```

scripts/windows-debug/check-tee-command.ps1

@@ -5,6 +5,9 @@
 Write-Host "Checking for 'tee' command availability on Windows..." -ForegroundColor Cyan
 Write-Host ""
 
+# Store original PATH
+$originalPath = $env:PATH
+
 # Method 1: Using where.exe
 Write-Host "Method 1: Using where.exe" -ForegroundColor Yellow
 try {
@@ -82,12 +85,47 @@ if ($pythonCheck -and $pythonCheck -ne "None") {
     Write-Host "  Python shutil.which() did not find tee" -ForegroundColor Red
 }
 
+Write-Host ""
+
+# Method 6: Try adding Git for Windows to PATH if it exists
+Write-Host "Method 6: Adding Git for Windows to PATH temporarily" -ForegroundColor Yellow
+$gitPaths = @(
+    "C:\Program Files\Git\usr\bin",
+    "C:\Program Files (x86)\Git\usr\bin"
+)
+
+$addedToPath = $false
+foreach ($gitPath in $gitPaths) {
+    if (Test-Path $gitPath) {
+        Write-Host "  Found Git directory: $gitPath" -ForegroundColor Green
+        $env:PATH = "$gitPath;$env:PATH"
+        $teeCheck = python -c "import shutil; print(shutil.which('tee'))"
+        if ($teeCheck -and $teeCheck -ne "None") {
+            Write-Host "  tee is now available at: $teeCheck" -ForegroundColor Green
+            $addedToPath = $true
+            break
+        }
+    }
+}
+
+if (-not $addedToPath) {
+    # Restore original PATH if we didn't find tee
+    $env:PATH = $originalPath
+    Write-Host "  Could not add Git for Windows tee to PATH" -ForegroundColor Red
+}
+
 Write-Host ""
 Write-Host "========== SUMMARY ==========" -ForegroundColor Cyan
-if ($whereResult -or $getCommandResult -or $found -or ($pythonCheck -and $pythonCheck -ne "None")) {
+if ($whereResult -or $getCommandResult -or $found -or ($pythonCheck -and $pythonCheck -ne "None") -or $addedToPath) {
     Write-Host "tee command is available" -ForegroundColor Green
     Write-Host ""
     Write-Host "The test_stdio_context_manager_exiting test should run." -ForegroundColor Green
+    if ($addedToPath) {
+        Write-Host ""
+        Write-Host "Note: Git for Windows tee was added to PATH for this session." -ForegroundColor Yellow
+        Write-Host "To make this permanent, add this to your PowerShell profile:" -ForegroundColor Yellow
+        Write-Host "  `$env:PATH = `"C:\Program Files\Git\usr\bin;`$env:PATH`"" -ForegroundColor Cyan
+    }
 } else {
     Write-Host "tee command is NOT available" -ForegroundColor Red
     Write-Host ""
@@ -98,4 +136,7 @@ if ($whereResult -or $getCommandResult -or $found -or ($pythonCheck -and $python
     Write-Host "  2. Install WSL (Windows Subsystem for Linux)"
     Write-Host "  3. Install MSYS2 or Cygwin"
     Write-Host "  4. Use PowerShell's Tee-Object cmdlet (different syntax)"
-}
+}
+
+# Restore original PATH
+$env:PATH = $originalPath

scripts/windows-debug/setup-environment.ps1

@@ -0,0 +1,59 @@
+#!/usr/bin/env pwsh
+# Script to set up the environment for running stdio tests on Windows
+# This adds Git for Windows tools to PATH if available
+# Usage: . .\setup-environment.ps1 (note the dot-sourcing)
+
+Write-Host "Setting up environment for stdio tests..." -ForegroundColor Cyan
+Write-Host ""
+
+# Check if Git for Windows is installed
+$gitPaths = @(
+    "C:\Program Files\Git\usr\bin",
+    "C:\Program Files (x86)\Git\usr\bin"
+)
+
+$gitFound = $false
+$gitPath = ""
+
+foreach ($path in $gitPaths) {
+    if (Test-Path $path) {
+        $gitPath = $path
+        $gitFound = $true
+        break
+    }
+}
+
+if ($gitFound) {
+    Write-Host "Found Git for Windows at: $gitPath" -ForegroundColor Green
+    
+    # Add to PATH
+    $env:PATH = "$gitPath;$env:PATH"
+    
+    # Verify tee is available
+    $teeCheck = python -c "import shutil; print(shutil.which('tee'))"
+    if ($teeCheck -and $teeCheck -ne "None") {
+        Write-Host "Successfully added tee to PATH: $teeCheck" -ForegroundColor Green
+        Write-Host ""
+        Write-Host "Environment is ready for stdio tests!" -ForegroundColor Green
+        Write-Host ""
+        Write-Host "You can now run the test scripts or individual tests:" -ForegroundColor Cyan
+        Write-Host "  .\test-stdio-flakiness-200-runs.ps1"
+        Write-Host "  .\test-stdio-flakiness-until-failure.ps1"
+        Write-Host "  .\test-stdio-verbose-debug.ps1"
+        Write-Host ""
+        Write-Host "Or run individual tests with:" -ForegroundColor Cyan
+        Write-Host "  uv run pytest tests/client/test_stdio.py::test_stdio_context_manager_exiting -v -o addopts="""""
+    } else {
+        Write-Host "WARNING: Git path was added but tee is still not available" -ForegroundColor Yellow
+    }
+} else {
+    Write-Host "Git for Windows not found in standard locations." -ForegroundColor Red
+    Write-Host ""
+    Write-Host "Please install Git for Windows from: https://gitforwindows.org/" -ForegroundColor Yellow
+    Write-Host "Or manually add the Git usr\bin directory to your PATH." -ForegroundColor Yellow
+}
+
+Write-Host ""
+Write-Host "Note: This only affects the current PowerShell session." -ForegroundColor Gray
+Write-Host "To make changes permanent, add to your PowerShell profile:" -ForegroundColor Gray
+Write-Host '  $env:PATH = "C:\Program Files\Git\usr\bin;$env:PATH"' -ForegroundColor Cyan

scripts/windows-debug/test-stdio-flakiness-200-runs.ps1

@@ -1,13 +1,21 @@
 #!/usr/bin/env pwsh
 # Script to run test_stdio_context_manager_exiting 200 times to detect flakiness
 # Usage: .\test-stdio-flakiness-200-runs.ps1
+#
+# Prerequisites: Run . .\setup-environment.ps1 first to ensure tee is available
 
 Write-Host "Running test_stdio_context_manager_exiting 200 times to detect flakiness..." -ForegroundColor Cyan
 Write-Host "Test: tests/client/test_stdio.py::test_stdio_context_manager_exiting" -ForegroundColor Yellow
 Write-Host ""
 
-# Disable pytest plugin autoload to avoid xdist issues
-$env:PYTEST_DISABLE_PLUGIN_AUTOLOAD = ""
+# Check if tee is available
+$teeCheck = python -c "import shutil; print(shutil.which('tee'))"
+if (-not $teeCheck -or $teeCheck -eq "None") {
+    Write-Host "ERROR: tee command not found!" -ForegroundColor Red
+    Write-Host "Please run: . .\setup-environment.ps1" -ForegroundColor Yellow
+    Write-Host "(Note the dot at the beginning to source the script)" -ForegroundColor Yellow
+    exit 1
+}
 
 $startTime = Get-Date
 $count = 0
@@ -17,10 +25,7 @@ $failedRuns = @()
 for ($i = 1; $i -le 200; $i++) {
     Write-Host "Run $i of 200..." -NoNewline
 
-    $output = & {
-        $env:PYTEST_DISABLE_PLUGIN_AUTOLOAD = ""
-        uv run --frozen pytest tests/client/test_stdio.py::test_stdio_context_manager_exiting -xvs --no-cov -p no:xdist 2>&1
-    }
+    $output = uv run --frozen pytest tests/client/test_stdio.py::test_stdio_context_manager_exiting -xvs -o addopts="" 2>&1
     $exitCode = $LASTEXITCODE
 
     if ($exitCode -ne 0) {
@@ -47,7 +52,4 @@ if ($failures -gt 0) {
     Write-Host "Failed on runs: $($failedRuns -join ', ')" -ForegroundColor Red
 }
 Write-Host "Duration: $($duration.ToString())"
-Write-Host "Failure rate: $([math]::Round(($failures / 200) * 100, 2))%"
-
-# Clean up environment variable
-Remove-Item Env:PYTEST_DISABLE_PLUGIN_AUTOLOAD -ErrorAction SilentlyContinue
+Write-Host "Failure rate: $([math]::Round(($failures / 200) * 100, 2))%"

scripts/windows-debug/test-stdio-flakiness-until-failure.ps1

@@ -1,14 +1,22 @@
 #!/usr/bin/env pwsh
 # Script to run test_stdio_context_manager_exiting until it fails
 # Usage: .\test-stdio-flakiness-until-failure.ps1
+#
+# Prerequisites: Run . .\setup-environment.ps1 first to ensure tee is available
 
 Write-Host "Running test_stdio_context_manager_exiting until failure..." -ForegroundColor Cyan
 Write-Host "Test: tests/client/test_stdio.py::test_stdio_context_manager_exiting" -ForegroundColor Yellow
 Write-Host "Press Ctrl+C to stop" -ForegroundColor Gray
 Write-Host ""
 
-# Disable pytest plugin autoload to avoid xdist issues
-$env:PYTEST_DISABLE_PLUGIN_AUTOLOAD = ""
+# Check if tee is available
+$teeCheck = python -c "import shutil; print(shutil.which('tee'))"
+if (-not $teeCheck -or $teeCheck -eq "None") {
+    Write-Host "ERROR: tee command not found!" -ForegroundColor Red
+    Write-Host "Please run: . .\setup-environment.ps1" -ForegroundColor Yellow
+    Write-Host "(Note the dot at the beginning to source the script)" -ForegroundColor Yellow
+    exit 1
+}
 
 $startTime = Get-Date
 $i = 0
@@ -17,10 +25,7 @@ while ($true) {
     $i++
     Write-Host "Run $i..." -NoNewline
 
-    $output = & {
-        $env:PYTEST_DISABLE_PLUGIN_AUTOLOAD = ""
-        uv run --frozen pytest tests/client/test_stdio.py::test_stdio_context_manager_exiting -xvs --no-cov -p no:xdist 2>&1
-    }
+    $output = uv run --frozen pytest tests/client/test_stdio.py::test_stdio_context_manager_exiting -xvs -o addopts="" 2>&1
     $exitCode = $LASTEXITCODE
 
     if ($exitCode -ne 0) {
@@ -45,7 +50,4 @@ while ($true) {
 }
 
 Write-Host ""
-Write-Host "Exiting after failure detection." -ForegroundColor Cyan
-
-# Clean up environment variable
-Remove-Item Env:PYTEST_DISABLE_PLUGIN_AUTOLOAD -ErrorAction SilentlyContinue
+Write-Host "Exiting after failure detection." -ForegroundColor Cyan