@samitouri / QOSAMI-WSL / commits / 8496b405

Add /attachdebugger option to automatically launch WinDbgX for test debugging (#40116)

* 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> * run-tests: use /inproc with /attachdebugger, simplify exit Per review feedback from @OneBlue: - Add /inproc when /attachdebugger is set so WinDbgX attaches directly to TE.exe instead of polling for TE.ProcessHost.exe - Simplify exit to pass through TE.exe exit code directly Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs: update /attachdebugger to reflect /inproc behavior The script now always adds /inproc, so update the README to match: WinDbgX attaches directly to TE.exe, no ProcessHost polling. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Ben Hillis <benhill@ntdev.microsoft.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Ben Hillis committed Apr 7, 2026 at 18:45 UTC 8496b4051c2ac4b1d6d1e6bed12e6157f88ad61a
4 files changed +46 -6
.github/copilot-instructions.md
+2 -1
@@ -255,7 +255,8 @@ Test execution:
255 - **Requires Administrator privileges**
256
257 Test debugging:
258 -- Wait for debugger: `/waitfordebugger`
258 +- Attach WinDbgX automatically: `/attachdebugger`
259 +- Wait for debugger (manual attach): `/waitfordebugger`
260 - Break on failure: `/breakonfailure`
261 - Run in-process: `/inproc`
262
doc/docs/dev-loop.md
+2 -1
@@ -96,7 +96,8 @@ bin\x64\debug\test.bat /name:*UnitTest* -f
96
97 See [debugging](debugging.md) for general debugging instructions.
98
99 -To attach a debugger to the unit test process, use: `/waitfordebugger` when calling `test.bat`.
99 +To automatically attach WinDbgX to the unit test process, use: `/attachdebugger` when calling `test.bat`.
100 +To wait for a debugger to be manually attached, use: `/waitfordebugger`.
101 Use `/breakonfailure` to automatically break on the first test failure.
102
103 ## Tips and tricks
test/README.md
+10
@@ -12,6 +12,16 @@ Executing tests with TAEF is done by invoking the `TE.exe` binary:
12 2. Navigate to the subdirectory containing the built test binaries (`bin/<X64|Arm64>/<Debug|Release>/`)
13 3. Execute the binaries via invoking TE and passing the test dll/s as arguments: `TE.exe test1.dll test2.dll test3.dll`
14
15 +## test.bat Options
16 +
17 +The following options are handled by `test.bat` / `run-tests.ps1` before invoking TE.exe:
18 +
19 +### **/attachdebugger**
20 +
21 +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 /inproc` to TE.exe so tests run in-process, then attaches WinDbgX directly to `TE.exe`.
22 +
23 +`test.bat /attachdebugger /name:*MyTest*`
24 +
25 ## Useful **TE.exe** Command Line Parameters for Debugging/Executing Tests
26
27 Command Line parameters are passed to `TE.exe` after supplying the target `.dll`:
tools/test/run-tests.ps1
+32 -4
@@ -45,9 +45,37 @@ if ($Fast)
45 $SetupScript = $null
46 }
47
48 -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
48 +# Handle /attachdebugger: verify WinDbgX is available, then add /waitfordebugger so we can find and attach to the test host.
49 +$AttachDebugger = $false
50 +if ($TeArgs -and ($TeArgs -icontains '/attachdebugger'))
51 +{
52 + $TeArgs = @($TeArgs | Where-Object { $_ -ine '/attachdebugger' })
53 + if (Get-Command "WinDbgX.exe" -ErrorAction SilentlyContinue)
54 + {
55 + $AttachDebugger = $true
56 + $TeArgs += '/waitfordebugger'
57 + # Run in-process so WinDbgX can attach directly to TE.exe without
58 + # polling for a TE.ProcessHost.exe child process.
59 + if (-not ($TeArgs -icontains '/inproc'))
60 + {
61 + $TeArgs += '/inproc'
62 + }
63 + }
64 + else
65 + {
66 + Write-Warning "/attachdebugger was requested, but WinDbgX.exe was not found. Continuing without debugger."
67 + }
68 +}
69 +
70 +$teArgList = @($TestDllPath, "/p:SetupScript=$SetupScript", "/p:Version=$Version", "/p:DistroPath=$DistroPath",
71 + "/p:Package=$Package", "/p:UnitTestsPath=$UnitTestsPath", "/p:PullRequest=$PullRequest", "/p:AllowUnsigned=1") + $TeArgs
72 +$teProcess = Start-Process -FilePath "te.exe" -ArgumentList $teArgList -PassThru -NoNewWindow
73
50 -if (!$?)
74 +if ($AttachDebugger)
75 {
52 - exit 1
53 -}
\ No newline at end of file
76 + # /inproc is always added above, so attach directly to TE.exe.
77 + Write-Host "Launching WinDbgX attached to TE.exe (PID: $($teProcess.Id))..."
78 + Start-Process "WinDbgX.exe" -ArgumentList "-p $($teProcess.Id)"
79 +}
80 +
81 +exit ($teProcess | Wait-Process -PassThru).ExitCode