Add pathMappings option to debugger#2251
Merged
Merged
Conversation
Contributor
There was a problem hiding this comment.
Pull Request Overview
This PR adds a pathMappings option to the PowerShell debugger that enables mapping between local and remote file paths during debugging sessions. This is particularly useful when debugging remote PowerShell instances where the local development environment has the same files but at different paths.
Key changes:
- Adds
PathMappingrecord to define local-to-remote path mappings - Integrates path mapping logic into breakpoint setting, stack trace handling, and script launching
- Adds comprehensive end-to-end test for attach scenarios with path mappings
Reviewed Changes
Copilot reviewed 9 out of 9 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| PathMapping.cs | New record defining the structure for local/remote path mappings |
| DebugService.cs | Core path mapping logic with methods to translate between local and remote paths |
| LaunchAndAttachHandler.cs | Integration of path mappings into launch and attach request handling |
| StackTraceHandler.cs | Updates stack trace paths using path mappings for remote debugging |
| BreakpointService.cs | Modified to use mapped paths when setting breakpoints |
| BreakpointApiUtils.cs | Added script path override parameter for breakpoint setting |
| DisconnectHandler.cs | Cleanup of path mappings on disconnect |
| DscBreakpointCapability.cs | Minor refactor to extract module name instead of full module info |
| DebugAdapterProtocolMessageTests.cs | Comprehensive E2E test for path mapping functionality |
Comments suppressed due to low confidence (1)
test/PowerShellEditorServices.Test.E2E/DebugAdapterProtocolMessageTests.cs:580
- Spelling error: 'cotinue' should be 'continue'.
// background and requesting the st is the only wait to ensure
Contributor
Author
3 tasks
a182fe6 to
23ef91b
Compare
649a4c1 to
163cd74
Compare
Adds the `pathMappings` option to the debugger that can be used to map a local to remote path and vice versa. This is useful if the local environment has a checkout of the files being run on a remote target but at a different path. The mappings are used to translate the paths that will the breakpoint will be set to in the target PowerShell instance. It is also used to update the stack trace paths received from the remote. For a launch scenario, the path mappings are also used when launching a script if the integrated terminal has entered a remote runspace.
163cd74 to
6dda2c6
Compare
pathMappings option to debugger
andyleejordan
pushed a commit
to PowerShell/vscode-powershell
that referenced
this pull request
Sep 4, 2025
Contributor
Author
|
Thanks for the review and merge! |
andyleejordan
added a commit
that referenced
this pull request
Jun 22, 2026
…ression); cap CI job (#2318) * Reduce CI test timeout and fix busy-spin in `ReadScriptLogLineAsync` The `CanAttachScriptWithPathMappings` E2E test intermittently hung `windows-latest` CI for the full six-hour default — three of the last eleven `main` runs died this way, all the same test, interspersed with green runs (a classic flaky race, not a regression). None of the commits whose runs hung touched the debugger attach path. The hang mechanism lived in `ReadScriptLogLineAsync`: at EOF `StreamReader.ReadLineAsync()` completes *synchronously* with `null`, so the `while`/`await` polling loop never actually yielded. It busy-spun one CPU at 100%, which starved the scheduler so none of the existing cooperative safety nets — xUnit's `[SkippableFact(Timeout = 15000)]`, the 30s `debugTaskCts`, or `WaitForExitAsync` — could ever schedule their continuations. A flaky few-second race thus escalated into a six-hour wedge. Ironically the busy-loop landed in #2208, a PR meant to reduce flakiness, and lay dormant until #2251 added a Windows-racy attach test that actually hits the EOF spin. - Back off with `await Task.Delay(100, token)` on EOF so we yield instead of busy-spinning, and cap the whole read with a 15s linked CTS that throws a clear `TimeoutException` naming the log path. - Add `timeout-minutes: 15` to the `ci` job as a backstop so any future hang fails in 15 minutes instead of riding GitHub's 6-hour default. A normal run finishes well under that (Windows, the slowest, is ~12-14m). The underlying attach race (reflection-based wait for `Debug-Runspace` to subscribe) is still worth hardening, but it now fails fast instead of hanging. Drafted by Copilot (Claude Opus 4.8). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Revert "Match strong-name identity when resolving PSES dependencies (#2303)" This reverts commit b9fd1b3. #2303 is what broke `CanAttachScriptWithPathMappings` on Windows. A clean bisection shows its parent (#2304, 6ad4f46) passed Windows E2E in ~12 minutes, while #2303 itself hung for 5h51m on that exact test -- and every commit built on top of it inherited the hang. Months of green Windows runs precede #2303. The mechanism is in `PsesLoadContext.Load`. #2303 tightened `IsSatisfyingAssembly` to also require a matching public key token and culture. When a `$PSHOME` assembly previously satisfied a dependency by name+version, `Load` returned `null` and PSES *shared* PowerShell's single copy. Under the stricter check a token mismatch now fails that first test, so `Load` falls through and loads our *own* bundled copy into the isolated `PsesLoadContext` instead -- producing two copies of the same assembly in two load contexts and a split type identity. The debugger-attach handshake (`Debug-Runspace` subscribing to `RunspaceBase.AvailabilityChanged`, plus the stopped-event plumbing in SMA) relies on cross-context event wiring that silently breaks under such a split, so the attach never completes and the test waits forever. It only trips on Windows because that is where the `$PSHOME`-versus-bundled token divergence occurs. #2303's "no bundled dependency changes resolution" check was static and missed an assembly loaded dynamically during attach. #2303 was self-described as "a focused trial of tightening" the matching, so reverting it restores the long-standing, known-good behavior. We can re-attempt the hardening later with this attach test as a guard. Drafted by Copilot (Claude Opus 4.8). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Bump CI timeout backstop to 30 minutes Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Lower `ReadScriptLogLineAsync` cap below per-test xUnit timeout The internal `CancelAfter` cap was 15s, exactly equal to the `[SkippableFact(Timeout = 15000)]` on `CanAttachScriptWithPathMappings`. Because xUnit's per-test timer covers the whole test -- attach, setBreakpoints, configurationDone and waiting for stopped events all run before `ReadScriptLogLineAsync` is even entered -- xUnit's generic timeout would almost always fire first, so the descriptive `TimeoutException` naming the log path would never surface for the very test that motivated it. Drop the cap to 10s so the clearer message can win for that test, while still bounding the untimed `[Fact]` callers. Per review feedback from copilot-pull-request-reviewer on #2318. Drafted by Copilot (Claude Opus 4.8). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Restore #2303 and test helper, keeping only the CI timeout backstop Reduce this branch to its one honest, effective change: a 30-minute `timeout-minutes` on the CI test job. A normal run finishes well under that (Windows, the slowest, is ~12-14 minutes), so the cap only bounds a hung test instead of letting it ride GitHub's 6-hour default. This un-reverts #2303 and drops the earlier `ReadScriptLogLineAsync` change, both of which were based on a per-commit bisection that has since been disproven. The Windows debugger-attach test `CanAttachScriptWithPathMappings` intermittently wedges on the attach handshake and rides the default timeout; the same hang reproduces on `main` (which contains #2303) and reproduced here with #2303 reverted, so #2303 is not the cause and is restored. The attach test wedges before it ever reaches `ReadScriptLogLineAsync`, so that change could not affect the hang and its short internal cap risked introducing new flakiness on a slow-but-healthy attach; it is reverted too. The intermittent attach hang is tracked separately. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Fix thread-pool starvation that wedged attach E2E test CanAttachScriptWithPathMappings intermittently hung Windows CI for hours instead of failing fast. Its ReadScriptLogLineAsync tailed the script log with `while (...) await ReadLineAsync()`, but at EOF ReadLineAsync completes synchronously with null, so the loop never released its thread-pool thread. On constrained CI runners that starved the pool, which both wedged the DAP client's background I/O and prevented the xUnit (15s) and harness (30s) timeout continuations from ever running -- so a transient stall rode the job timeout for hours. Await a short delay between reads so the tail loop yields, and add a matching sleep to the child process's Debug-Runspace readiness poll so it cannot peg a core during the attach handshake. Combined with the 30-minute CI job cap, a genuine stall now fails fast via the test's own timeout instead of hanging. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Skip attach E2E test on in-box Windows PowerShell CanAttachScriptWithPathMappings hangs on in-box Windows PowerShell 5.1 since the windows-2025-vs2026 runner image refreshed from 20260608 to 20260614. The cross-process Debug-Runspace attach wedges and the test rides the job timeout; the windows-latest leg cannot complete. Scope the skip to IsWindowsPowerShell so the in-box WinPS suites (including CLM) are exempt while PowerShell Core, the preview, macOS, and Linux keep full coverage of the attach path. This is a stopgap pending a real fix for the in-box attach deadlock, tracked by #2323; the 30-minute timeout-minutes backstop in ci-test.yml stays as a guard. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Soften ReadScriptLogLineAsync comment to match root cause The earlier comment asserted the EOF tight-loop was the cause of the multi-hour Windows hang. Deconfounding analysis disproved that: the hang is the in-box Windows PowerShell attach regression from the 20260614 runner image, not thread-pool starvation here. Keep the yield as genuine harness hardening but describe it as such rather than claiming it as the fix. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Skip attach E2E test at discovery time on Windows PowerShell CanAttachScriptWithPathMappings wedges during the per-test InitializeAsync (PSES debug-adapter server startup) on in-box Windows PowerShell since the windows-2025-vs2026 runner image refresh, riding the job timeout in CI. The prior in-body Skip.If(IsWindowsPowerShell) never fired because xUnit runs IAsyncLifetime.InitializeAsync before the test body, and that setup is where the hang occurs. Add a SkippableFact subclass that sets Skip in its constructor so xUnit skips the test at discovery time, before it instantiates the class or runs InitializeAsync. The SkippableFact discoverer is retained so the runtime Constrained Language Mode skip still works off-Windows. See #2323. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * ci: raise test job timeout to 60 minutes The 30-minute cap was too aggressive as a backstop; bump it to 60 so a genuinely slow (but not hung) run is not killed prematurely, while still capping a wedged test well short of GitHub's 6-hour default. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Skip all debug adapter E2E tests on Windows PowerShell The CI hang is in the shared per-test InitializeAsync that starts the PSES debug-adapter server, not in any single test, so skipping only CanAttachScriptWithPathMappings just promotes the next test to first victim. Each test pays a fresh cold-start, and intermittently any one of them can be the test that wedges on the 20260614 runner image. Broaden the discovery-time Windows PowerShell skip to the entire DebugAdapterProtocolMessageTests class: add a SkippableTheory companion to the existing SkippableFact variant, share the skip reason, and apply the attributes to all test methods. The pwsh (.NET 8) E2E suite still runs the full set, so only in-box Windows PowerShell debug-adapter coverage is paused, pending a real fix tracked in #2323. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Skip all language server E2E tests on Windows PowerShell The in-box Windows PowerShell server wedges during startup on the current windows-latest runner image, riding the job timeout. This is a runner-image regression, not our code: re-running an old commit that predates all of our recent PRs (and previously passed) now hangs the same way, while macOS and Linux stay green. Because both E2E suites spawn the same WinPS-hosted server, skipping only the debug adapter tests just relocated the hang to the language server fixture's `LSPTestsFixture.InitializeAsync`, where `_psesHost.Start()` launches the server. - Apply the discovery-time `[SkippableFactOnWindowsPowerShell]` skip to every test method in `LanguageServerProtocolMessageTests`. - Guard `LSPTestsFixture` so it does not start the server under Windows PowerShell, and dispose safely when it wasn't started. xUnit still creates an `IClassFixture<>` even when every method in the class is skipped at discovery time, so the discovery-time skip alone does not stop the fixture's own startup from hanging. - Generalize the shared skip reason from `WindowsPowerShellDebugAdapterSkip` to `WindowsPowerShellServerStartupSkip`, since it now covers both protocols. Windows PowerShell unit coverage (`TestPS51`) still runs; this only skips the WinPS-hosted E2E server tests as a stopgap pending a real fix. See #2323. Drafted by Copilot (Claude Opus 4.8). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.

PR Summary
Adds the
pathMappingsoption to the debugger that can be used to map a local to remote path and vice versa. This is useful if the local environment has a checkout of the files being run on a remote target but at a different path. The mappings are used to translate the paths that will the breakpoint will be set to in the target PowerShell instance. It is also used to update the stack trace paths received from the remote.For a launch scenario, the path mappings are also used when launching a script if the integrated terminal has entered a remote runspace.
PR Context
Fixes: #2242