Add /attachdebugger option to automatically launch WinDbgX for test debugging

When /attachdebugger is passed to test.bat, run-tests.ps1 now:
- Starts te.exe with /waitfordebugger in the background
- Polls for the TE.ProcessHost.exe child process via WMI
- Launches WinDbgX attached directly to the test host PID
- With /inproc, attaches to TE.exe itself instead

This replaces the manual workflow of running /waitfordebugger, reading
the PID from the output, and launching WinDbgX separately.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: Ben Hillis

.github/copilot-instructions.md

@@ -92,7 +92,8 @@ Test execution:
 - **Requires Administrator privileges** - test.bat will fail without admin rights
 
 Test debugging:
-- Wait for debugger: `/waitfordebugger`
+- Attach WinDbgX automatically: `/attachdebugger`
+- Wait for debugger (manual attach): `/waitfordebugger`
 - Break on failure: `/breakonfailure`
 - Run in-process: `/inproc`
 

doc/docs/dev-loop.md

@@ -96,7 +96,8 @@ bin\x64\debug\test.bat /name:*UnitTest* -f
 
 See [debugging](debugging.md) for general debugging instructions.
 
-To attach a debugger to the unit test process, use: `/waitfordebugger` when calling `test.bat`. 
+To automatically attach WinDbgX to the unit test process, use: `/attachdebugger` when calling `test.bat`.
+To wait for a debugger to be manually attached, use: `/waitfordebugger`.
 Use `/breakonfailure` to automatically break on the first test failure. 
 
 ## Tips and tricks

test/README.md

@@ -12,6 +12,16 @@ Executing tests with TAEF is done by invoking the `TE.exe` binary:
 2. Navigate to the subdirectory containing the built test binaries (`bin/<X64|Arm64>/<Debug|Release>/`)
 3. Execute the binaries via invoking TE and passing the test dll/s as arguments: `TE.exe test1.dll test2.dll test3.dll`
 
+## test.bat Options
+
+The following options are handled by `test.bat` / `run-tests.ps1` before invoking TE.exe:
+
+### **/attachdebugger**
+
+Automatically launches WinDbgX and attaches it to the test host process. Requires [WinDbg](https://aka.ms/windbg) to be installed (`winget install Microsoft.WinDbg`). Under the hood it passes `/waitfordebugger` to TE.exe, finds the `TE.ProcessHost.exe` child process, and attaches WinDbgX to it. When combined with `/inproc`, WinDbgX attaches to `TE.exe` directly instead.
+
+`test.bat /attachdebugger /name:*MyTest*`
+
 ## Useful **TE.exe** Command Line Parameters for Debugging/Executing Tests
 
 Command Line parameters are passed to `TE.exe` after supplying the target `.dll`:

tools/test/run-tests.ps1

@@ -45,9 +45,52 @@ if ($Fast)
     $SetupScript = $null
 }
 
-te.exe $TestDllPath /p:SetupScript=$SetupScript  /p:Version=$Version /p:DistroPath=$DistroPath /p:Package=$Package /p:UnitTestsPath=$UnitTestsPath /p:PullRequest=$PullRequest /p:AllowUnsigned=1 @TeArgs
+# Handle /attachdebugger: verify WinDbgX is available, then add /waitfordebugger so we can find and attach to the test host.
+$AttachDebugger = $false
+if ($TeArgs -and ($TeArgs -icontains '/attachdebugger'))
+{
+    $TeArgs = @($TeArgs | Where-Object { $_ -ine '/attachdebugger' })
+    if (Get-Command "WinDbgX.exe" -ErrorAction SilentlyContinue)
+    {
+        $AttachDebugger = $true
+        $TeArgs += '/waitfordebugger'
+    }
+    else
+    {
+        Write-Warning "/attachdebugger was requested, but WinDbgX.exe was not found. Continuing without debugger."
+    }
+}
 
-if (!$?)
+$teArgList = @($TestDllPath, "/p:SetupScript=$SetupScript", "/p:Version=$Version", "/p:DistroPath=$DistroPath",
+    "/p:Package=$Package", "/p:UnitTestsPath=$UnitTestsPath", "/p:PullRequest=$PullRequest", "/p:AllowUnsigned=1") + $TeArgs
+$teProcess = Start-Process -FilePath "te.exe" -ArgumentList $teArgList -PassThru -NoNewWindow
+
+if ($AttachDebugger)
 {
-    exit 1
-}
+    $targetPid = if ($TeArgs -icontains '/inproc') { $teProcess.Id } else { $null }
+
+    if (-not $targetPid)
+    {
+        for ($i = 0; $i -lt 120 -and -not $teProcess.HasExited; $i++)
+        {
+            Start-Sleep -Milliseconds 500
+            $child = Get-CimInstance Win32_Process -Filter "ParentProcessId = $($teProcess.Id) AND Name = 'TE.ProcessHost.exe'" -ErrorAction SilentlyContinue
+            if ($child) { $targetPid = $child[0].ProcessId; break }
+        }
+    }
+
+    if ($targetPid)
+    {
+        $targetName = if ($targetPid -eq $teProcess.Id) { "TE.exe" } else { "TE.ProcessHost.exe" }
+        Write-Host "Launching WinDbgX attached to $targetName (PID: $targetPid)..."
+        Start-Process "WinDbgX.exe" -ArgumentList "-p $targetPid"
+    }
+    else
+    {
+        Write-Warning "Could not find TE.ProcessHost.exe within 60 seconds."
+        Write-Host "Attach a debugger manually to TE.exe (PID: $($teProcess.Id))."
+    }
+}
+
+$teProcess | Wait-Process
+if ($teProcess.ExitCode -ne 0) { exit 1 }