Cover per-language debugger launch flows in extension E2E

[Adam Ratzman (adamint)]

Description

Adds an end-to-end proof that Aspire launches a Node resource under its real language debugger, stops on a source breakpoint, and tears down the complete debuggee process tree.

• Adds Linux and Windows resource-debugger E2E shards using VS Code's built-in js-debug adapter.
• Registers a shard-only Node fixture so existing E2E resource trees remain unchanged.
• Starts the AppHost, starts the resource through the Aspire control channel, sets a marker-based breakpoint, and verifies the stopped stack frame belongs to the fixture.
• Verifies the resource debugger session is distinct from the AppHost/Aspire launcher session.
• Captures bounded debugger output and PID markers for process-tree teardown proof.
• Applies one shared deadline across external E2E awaits so a hung VS Code Thenable cannot outlive the test.
• Always runs AppHost refresh/state settling after stop attempts and preserves both stop and cleanup failures.
• Fails the shard when results are missing, zero tests execute, or every test is pending, so ExTester exit code 0 cannot false-green the proof.

Other language adapters remain separate follow-up work because the E2E VS Code instance does not install Marketplace extensions.

Refs #18957

Dependencies

• Re-enable VS Code extension E2E tests in CI #19142 must land first. It owns the generic extension E2E re-enable scaffolding and shard-result guard.
• Fix browser debug targets, empty webRoot, and resource stop ordering #19145 must land first. Its resource-before-AppHost shutdown ordering is the behavior this proof exercises while the resource is suspended at a breakpoint.

This PR stays draft until both dependencies land. The branch can then be rebased and the hosted resource-debugger shards can run against the final combined workflow.

Validation

• TypeScript unit and E2E compilation
• Webpack and ESLint
• 77 focused resource-proof, deadline, launch-profile, output-capture, and cleanup tests
• Runner-result suite: 103 passing, including missing, zero, all-pending, successful, non-opted, production-wiring, deadline-wiring, and mutation cases
• Shared-deadline helper suite: 6 passing
• Real hosted E2E execution remains the final gate after Re-enable VS Code extension E2E tests in CI #19142 and Fix browser debug targets, empty webRoot, and resource stop ordering #19145 land

Checklist

• Node proof and reusable harness are complete
• Unit tests cover helper behavior and failure preservation
• The runner rejects a shard with no executed tests
• No public API added
• Re-enable VS Code extension E2E tests in CI #19142 has landed
• Fix browser debug targets, empty webRoot, and resource stop ordering #19145 has landed
• Hosted Linux and Windows resource-debugger shards pass after rebase

[github-actions]

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 19133

Or

• Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 19133"

[Copilot]

Pull request overview

Adds real VS Code extension E2E coverage for Node resource debugging and strengthens debugger lifecycle handling.

Changes:

• Adds breakpoint, session-isolation, and process-tree teardown E2E proofs.
• Adds shard validation and Node-only fixture provisioning.
• Improves browser validation, diagnostics, localization structure, and debug-session shutdown ordering.

Show a summary per file

File	Description
.github/workflows/extension-e2e-tests.yml	Runs the debugger shard on Linux and Windows.
.gitignore	Ignores E2E logs.
extension/CONTRIBUTING.md	Documents the new shard.
extension/scripts/e2e-shard-results.js	Rejects empty or skipped proof runs.
extension/scripts/run-e2e.js	Creates and runs the Node fixture.
extension/src/debugger/AspireDebugSession.ts	Stops resource sessions before AppHost.
extension/src/debugger/languages/azureFunctions.ts	Extracts session display labels.
extension/src/debugger/languages/browser.ts	Validates browser adapters and web roots.
extension/src/loc/strings.ts	Adds debugger-related strings.
extension/src/test-e2e/helpers/fixtures.ts	Adds breakpoint and process helpers.
extension/src/test-e2e/helpers/paths.ts	Resolves the Node fixture path.
extension/src/test-e2e/resourceDebugger.e2e.test.ts	Proves Node debugging end to end.
extension/src/test/aspireDebugSession.test.ts	Verifies debugger shutdown ordering.
extension/src/test/azureFunctionsDebugger.test.ts	Covers Azure Functions adapter behavior.
extension/src/test/browserDebugger.test.ts	Covers browser adapter validation.
extension/src/test/e2eLaunchProfile.test.ts	Updates fixture source assertions.
extension/src/test/e2eShardMatrix.test.ts	Verifies CI shard coverage.
extension/src/test/e2eShardResults.test.ts	Tests shard-result validation.
extension/src/test/javascriptRuntime.test.ts	Expands JavaScript runtime coverage.
extension/src/test/processDiagnostics.test.ts	Tests process parsing and formatting.
extension/src/test/resourceDebugProof.test.ts	Tests proof-request normalization.
extension/src/testing/e2eStateFileBridge.ts	Implements the language-neutral proof.
extension/src/testing/processDiagnostics.ts	Adds process diagnostic helpers.
extension/src/types/extensionApi.ts	Defines the generalized proof command.

Review details

Suppressed comments (2)

extension/src/testing/e2eStateFileBridge.ts:900

• This “head” is global across every tracked debug session. The AppHost sessions start first, so their first 20 output events can fill the array before the resource prints its PID lines; readReportedPid can then lose those lines once they also fall out of the tail ring buffer. Keep the first events per session (or specifically for the resource session) instead.

            // The first lines a debuggee writes identify it (for example the pid it reports), so the
            // head is kept separately from the ring buffer that holds the most recent lines.
            if (outputHeadEvents.length < 20) {
              outputHeadEvents.push(outputEvent);

extension/src/testing/e2eStateFileBridge.ts:1106

• This wait uses a global, capped ring buffer as its completion signal. Output from the AppHost can satisfy it without the resource producing anything, while once the buffer reaches 200 entries its length never increases and the wait always times out. Track a monotonic output count scoped to session.id instead.

  const outputEventsBefore = outputEvents.length;
  await session.customRequest('continue', { threadId });
  await waitForE2eValue(
    'the resumed resource process to produce output',
    timeoutMs,
    () => outputEvents.length > outputEventsBefore ? true : undefined);

• Files reviewed: 23/24 changed files
• Comments generated: 4
• Review effort level: Balanced

[Copilot]

Review details

Suppressed comments (3)

extension/src/debugger/AspireDebugSession.ts:138

• Promise.all rejects as soon as one resource stop fails, so another resource stop can still be in flight when the AppHost is stopped. That reintroduces the shutdown ordering problem this change is intended to fix for multi-resource sessions. Wait for every stop attempt to settle, retain the first failure, and only then stop the AppHost/parent.

      await Promise.all(resourceDebugSessions.map(session => session.stopSession()));

extension/src/test-e2e/resourceDebugger.e2e.test.ts:168

• The fallback to all sessions is chosen only when the stopped session emitted no output at all. If that child session emits any js-debug diagnostic while the PID markers remain on the launching parent session (the split documented above), its nonempty output hides the valid parent markers and this test fails. Search the stopped-session output for the marker first, then fall back to all captured output only when that search has no match.

    const stoppedSessionEvents = events.filter(event => event.sessionId === proof.resourceDebugSession?.id);
    const output = (stoppedSessionEvents.length > 0 ? stoppedSessionEvents : events).map(event => event.output).join('');
    const matches = [...output.matchAll(new RegExp(`${marker}=(\\d+)`, 'g'))];

extension/src/test-e2e/resourceDebugger.e2e.test.ts:141

• The control-channel deadline is 360 seconds, but the handler deliberately gives startup, resource start, and breakpoint phases independent budgets of 180 + 180 + 240 seconds (plus up to 60 seconds to resume). A successful slow startup can therefore exhaust this outer deadline long before the breakpoint phase's advertised budget, leaving the proof running after the test reports a timeout. Make the outer command and Mocha test timeouts cover the sum of the independent phase caps, or use one shared deadline consistently.

    }, { timeoutMs: proofTimeoutMs + 60000 });

• Files reviewed: 25/26 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[Copilot]

Review details

Suppressed comments (3)

extension/src/debugger/AspireDebugSession.ts:152

• Promise.all rejects as soon as one resource stop fails, so this method can begin stopping the AppHost while other resource-stop promises are still pending. That breaks the ordering this change is intended to guarantee and can leave the AppHost shutdown blocked on one of those resources. Await all resource stops with allSettled, then propagate the first failure after the AppHost and parent have been stopped.

    let resourceStopError: unknown;
    try {
      const resourceDebugSessions = this._resourceDebugSessions.filter(session => session.id !== this._appHostDebugSession?.id);
      await Promise.all(resourceDebugSessions.map(session => session.stopSession()));

extension/src/test-e2e/resourceDebugger.e2e.test.ts:141

• The control-channel wait is only 360 seconds, but the handler can legitimately consume 180 seconds for AppHost startup + 180 seconds for resource start + 240 seconds for the breakpoint, plus another 60 seconds when resuming for the teardown proof. Under load this caller abandons a still-valid proof after six minutes, and the 600-second Mocha timeout is also shorter than the 660-second handler budget. Align the outer and suite timeouts with the sum of the independent phase budgets, or change the handler to use one shared deadline.

        timeoutMs: proofTimeoutMs,
        expectedResourceDebugSessionType: 'pwa-node',
        stopDebuggingOnCompletion: options.stopDebuggingOnCompletion,
    }, { timeoutMs: proofTimeoutMs + 60000 });

extension/src/test-e2e/resourceDebugger.e2e.test.ts:168

• The fallback is selected based on whether the stopped child session emitted any output, not whether it emitted this PID marker. js-debug sends the fixture's captured stdout from the launching parent session, while the stopped child can still emit its own diagnostics; one such diagnostic makes this code discard the parent events and falsely report the PID as missing. Only prefer the stopped-session stream when that stream actually contains a marker match.

    const events = [...proof.outputHead, ...proof.outputSample];
    const stoppedSessionEvents = events.filter(event => event.sessionId === proof.resourceDebugSession?.id);
    const output = (stoppedSessionEvents.length > 0 ? stoppedSessionEvents : events).map(event => event.output).join('');
    const matches = [...output.matchAll(new RegExp(`${marker}=(\\d+)`, 'g'))];

• Files reviewed: 25/26 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

[Copilot]

Review details

Suppressed comments (4)

extension/src/test-e2e/resourceDebugger.e2e.test.ts:168

• The fallback is selected based on whether the stopped session emitted any output, not whether that output contains the PID marker. js-debug normally sends the fixture's stdout on its launching parent session, so one unrelated output event from the stopped child makes this search ignore the parent PID and fail. Search the stopped-session stream first, then fall back to all events only when that stream contains no marker.

    const stoppedSessionEvents = events.filter(event => event.sessionId === proof.resourceDebugSession?.id);
    const output = (stoppedSessionEvents.length > 0 ? stoppedSessionEvents : events).map(event => event.output).join('');

extension/src/test-e2e/resourceDebugger.e2e.test.ts:141

• The command can legitimately spend up to 180s starting the AppHost, 180s starting the resource, and 240s waiting for the breakpoint (600s total), but this caller gives the control bridge only 360s. A slow proof can therefore time out in the test while it is still running in the serialized extension-host control channel, leaving teardown commands queued behind it. Either use one shared deadline in the handler or raise both this timeout and the Mocha timeout to cover the sum of the phase budgets plus teardown.

    }, { timeoutMs: proofTimeoutMs + 60000 });

extension/src/test-e2e/helpers/fixtures.ts:694

• If the diagnostic ps/PowerShell command fails, times out, or returns invalid JSON, getProcessSnapshot throws here and replaces the primary process-exit timeout with an inspection error. Process inspection is best-effort diagnostics, so preserve the timeout and append the inspection failure instead of masking it.

    throw new Error(`Timed out after ${timeoutMs}ms waiting for ${description} (pid ${pid}) to exit. Last observed process: ${formatProcessSnapshot(getProcessSnapshot(pid), pid)}.`);

extension/src/test-e2e/resourceDebugger.e2e.test.ts:95

• The PR description and testing section still claim browser allowlisting/webRoot fixes, resource-before-AppHost stop ordering, and Browser/Azure Functions/AspireDebugSession test additions, but the current 18-file diff contains none of those files. The current browser.ts still builds pwa-${browser} and always assigns webRoot, while AspireDebugSession.stopDebugging() still stops the AppHost first. Please either restore those changes and tests or update the PR description/testing claims to match this revision.

        await executeE2eControlCommand({ name: 'stopDebugging' }, { waitFor: 'started' });

• Files reviewed: 17/18 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[Copilot]

Review details

Suppressed comments (2)

extension/src/test-e2e/resourceDebugger.e2e.test.ts:160

• This committed comment narrates branch/PR dependency history (this PR declares as a prerequisite) rather than the current behavior. Keep the resource-before-AppHost shutdown rationale, but remove the PR-history wording so the comment remains accurate after merge.

        // The teardown this asserts on depends on the resource stop ordering fixed in
        // https://github.com/microsoft/aspire/pull/19145, which this PR declares as a prerequisite:
        // stopping while a resource is suspended on a breakpoint has to stop the resource session
        // before the AppHost or the debuggee and its children are left running.

extension/src/testing/e2eStateFileBridge.ts:804

• stopDebuggingOnCompletion !== false silently treats every malformed JSON value (for example, the string "false") as true. This command comes from an untyped control file, and the normalizer validates the other request fields at runtime; reject a defined non-boolean before applying the default so a malformed teardown proof cannot stop the debuggee and invalidate the process-tree assertion.

    stopDebuggingOnCompletion: command.stopDebuggingOnCompletion !== false,

• Files reviewed: 18/18 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

[Copilot]

Review details

Suppressed comments (1)

extension/src/test-e2e/resourceDebugger.e2e.test.ts:77

• The teardown uses the same deadline as the test body. If any phase consumes the remaining budget, getRemainingE2eDeadlineMs rejects immediately for every cleanup, so the 30-second Mocha slack runs the hook but never starts stopDebugging, breakpoint cleanup, or AppHost cleanup. Reserve a separate bounded cleanup deadline (and include it in the Mocha timeout), rather than reusing an already-expired operation deadline.

            () => runResourceDebuggerPhase(
                'resource debugger teardown stop control',
                resourceDebuggerDeadline,
                resourceDebuggerPhaseTimeoutMs.stopDebuggingControl,
                timeoutMs => executeE2eControlCommand({ name: 'stopDebugging' }, { timeoutMs })),

• Files reviewed: 17/17 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[Copilot]

Review details

• Files reviewed: 17/17 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

[Copilot]

Review details

Suppressed comments (2)

extension/src/test-e2e/resourceDebugger.e2e.test.ts:77

• If a test consumes the shared 900-second deadline, every teardown callback reaches getRemainingE2eDeadlineMs with an expired deadline and throws before invoking stopDebugging, breakpoint cleanup, or AppHost cleanup. The advertised 30-second Mocha teardown slack therefore cannot perform cleanup, leaving live sessions/processes to contaminate subsequent tests. Reserve a bounded cleanup budget within the overall timeout or use a separate bounded teardown deadline.

            () => runResourceDebuggerPhase(
                'resource debugger teardown stop control',
                resourceDebuggerDeadline,
                resourceDebuggerPhaseTimeoutMs.stopDebuggingControl,
                timeoutMs => executeE2eControlCommand({ name: 'stopDebugging' }, { timeoutMs })),

extension/src/testing/resourceDebugOutput.ts:33

• The fallback combines output from every debug session into one byte stream. DAP events from the Aspire parent, AppHost, and js-debug sessions can interleave, so a PID marker split across two events can either be broken by another session's output or completed with digits from the wrong session. Reassemble output independently per sessionId before matching the marker.

function findPidMatches(events: readonly DebugAdapterOutputEvent[], marker: string): RegExpMatchArray[] {
    const output = events.map(event => event.output).join('');

    return [...output.matchAll(new RegExp(`${marker}=(\\d+)`, 'g'))];

• Files reviewed: 17/17 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

[Copilot]

Review details

• Files reviewed: 17/17 changed files
• Comments generated: 1
• Review effort level: Balanced

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

[Copilot]

Review details

• Files reviewed: 16/17 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[Copilot]

Review details

Suppressed comments (2)

extension/CONTRIBUTING.md:125

• This documented command still uses the runner’s 40-minute default, while the new shard is explicitly budgeted for up to 54 minutes and CI raises its process timeout to 60 minutes. A slow/failing local run will therefore be killed before the shard’s bounded proof and teardown complete. Include the same 3600000 ms override in the command.

ASPIRE_EXTENSION_E2E_SHARD=resource-debugger ASPIRE_EXTENSION_E2E_SPEC=out/test-e2e/test-e2e/resourceDebugger.e2e.test.js ASPIRE_EXTENSION_E2E_CLI_PATH=/path/to/aspire corepack yarn test:e2e

.github/workflows/extension-e2e-tests.yml:275

• The new 60-minute ExTester timeout is nested inside the existing 75-minute job timeout, which starts before checkout, dependency setup, CLI extraction, compilation, restore, VSIX installation, and VS Code setup. Consequently these rows do not actually reserve the stated 15 minutes for post-timeout cleanup and diagnostics; if setup consumes 15 minutes, GitHub cancels the job before runWithProcessTreeTimeout can fire and the upload steps run. Increase the job-level timeout (preferably via a per-row override) to cover setup + 60 minutes + diagnostics.

            runTestsTimeoutMs: 3600000

• Files reviewed: 16/17 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

[Copilot]

Review details

• Files reviewed: 16/17 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.