Add TerminalRun IAsyncDisposable for consistent CLI E2E diagnostics capture

[JamesNK]

Description

Add a TerminalRun type (IAsyncDisposable) that wraps the CLI E2E terminal lifecycle, ensuring CaptureAspireDiagnosticsAsync always runs at the end of a test — even when the test fails. This replaces the manual exit/await pendingRun boilerplate and guarantees diagnostics are consistently captured across all tests.

Before: Each test manually called exit, Enter, and await pendingRun at the end. Tests that failed mid-execution would skip diagnostics capture entirely.

After: Tests use await using var terminalRun = CliE2ETestHelpers.StartRun(...) which automatically handles diagnostics capture, terminal exit, and run completion on disposal.

using var terminal = CliE2ETestHelpers.CreateDockerTestTerminal(repoRoot, strategy, output, workspace: workspace);

var counter = new SequenceCounter();
var auto = new Hex1bTerminalAutomator(terminal, defaultTimeout: TimeSpan.FromSeconds(500));
await using var terminalRun = CliE2ETestHelpers.StartRun(terminal, workspace, auto, counter, TestContext.Current.CancellationToken);

// ... test body — no exit/pendingRun needed

Applied to 10 tests as an initial rollout. The remaining tests will be migrated once this pattern is validated.

Checklist

• Is this feature complete?
  • Yes. Ready to ship.
  • No. Follow-up changes expected.
• Are you including unit tests for the changes and scenario tests if relevant?
  • Yes
  • No
• Did you add public API?
  • Yes
  • No
• Does the change make any security assumptions or guarantees?
  • Yes
  • No

[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 -- 17576

Or

• Run remotely in PowerShell:

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

[Copilot]

Pull request overview

Introduces a TerminalRun : IAsyncDisposable helper that wraps the CLI E2E terminal lifecycle so CaptureAspireDiagnosticsAsync, exit/Enter, and await pendingRun are always executed at the end of a test — including when the test body throws. Migrates 10 existing CLI E2E tests to the new pattern and documents the convention in the cli-e2e-testing skill. Remaining tests will be migrated in follow-ups.

Changes:

• Add TerminalRun type and CliE2ETestHelpers.StartRun(...) factory.
• Replace manual pendingRun/exit/await pendingRun in 10 tests with await using var terminalRun = CliE2ETestHelpers.StartRun(...).
• Document the TerminalRun pattern (DO/DON'T) in .agents/skills/cli-e2e-testing/SKILL.md.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
tests/Aspire.Cli.EndToEnd.Tests/Helpers/TerminalRun.cs	New IAsyncDisposable ensuring diagnostics capture, exit, and run-await on dispose, each best-effort.
tests/Aspire.Cli.EndToEnd.Tests/Helpers/CliE2ETestHelpers.cs	Adds StartRun factory returning a TerminalRun.
tests/Aspire.Cli.EndToEnd.Tests/WaitCommandTests.cs	Migrate CreateStartWaitAndStopAspireProject to StartRun.
tests/Aspire.Cli.EndToEnd.Tests/StopNonInteractiveTests.cs	Migrate StopNonInteractiveSingleAppHost to StartRun.
tests/Aspire.Cli.EndToEnd.Tests/StartStopTests.cs	Migrate StopWithNoRunningAppHostExitsSuccessfully to StartRun.
tests/Aspire.Cli.EndToEnd.Tests/SmokeTests.cs	Migrate three smoke tests to StartRun.
tests/Aspire.Cli.EndToEnd.Tests/DocsCommandE2ETests.cs	Migrate docs E2E test to StartRun.
tests/Aspire.Cli.EndToEnd.Tests/ConfigHealingTests.cs	Migrate InvalidAppHostPathWithComments_IsHealedOnRun to StartRun.
tests/Aspire.Cli.EndToEnd.Tests/CertificatesCommandTests.cs	Migrate two certificate tests to StartRun.
tests/Aspire.Cli.EndToEnd.Tests/BundleSmokeTests.cs	Migrate bundle smoke test to StartRun.
.agents/skills/cli-e2e-testing/SKILL.md	Documents the TerminalRun pattern with DO/DON'T examples.

[davidfowl]

deployment tests?

[JamesNK]

deployment tests?

Working up to them.

[github-actions]

❓ CLI E2E Tests unknown — 107 passed, 0 failed, 2 unknown (commit 29f49b0)

View all recordings

Status	Test	Recording	Job	Artifacts
✅	AddPackageInteractiveWhileAppHostRunningDetached	Recording	#78288456621	Logs
✅	AddPackageWhileAppHostRunningDetached	Recording	#78288456621	Logs
✅	AgentCommands_AllHelpOutputs_AreCorrect	Recording	#78288456647	Logs
✅	AgentInitCommand_DefaultSelection_InstallsDefaultSkills	Recording	#78288456647	Logs
✅	AgentInitCommand_MigratesDeprecatedConfig	Recording	#78288456647	Logs
✅	AgentMcpListStructuredLogsReturnsLogsFromStarterApp	Recording	#78288457251	Logs
✅	AgentMcpListStructuredLogsReturnsLogsFromStarterApp_DevLocalhost	Recording	#78288457251	Logs
✅	AgentMcpListStructuredLogsReturnsLogsFromStarterApp_Isolated	Recording	#78288457251	Logs
✅	AllPublishMethodsBuildDockerImages	Recording	#78288456997	Logs
✅	AspireAddAndStartWorkAgainstLegacyAppHostTs	Recording	#78288457806	Logs
✅	AspireAddPackageVersionToDirectoryPackagesProps	Recording	#78288456919	Logs
✅	AspireInitSingleFileAppHostRunsViaDotnetRunAppHost	Recording	#78288456951	Logs
✅	AspireInitWithExistingAppHostDirRecreatesMissingNuGetConfigAndPreservesFiles	Recording	#78288456513	Logs
❔	AspireInitWithSolutionFileGeneratesAppHostThatBuildsAgainstChannelHive	Recording	#78288456513	Logs
✅	AspireStartUpdatesStaleTypeScriptAppHostPath	Recording	#78288457471	Logs
✅	AspireUpdateRemovesAppHostPackageVersionFromDirectoryPackagesProps	Recording	#78288456919	Logs
✅	AspireUpdateRemovesOrphanAppHostPackageVersionWhenSdkAlreadyCurrent	Recording	#78288456919	Logs
✅	Banner_DisplayedOnFirstRun	Recording	#78288456942	Logs
✅	Banner_DisplayedWithExplicitFlag	Recording	#78288456942	Logs
✅	Banner_NotDisplayedWithNoLogoFlag	Recording	#78288456942	Logs
✅	CertificatesClean_RemovesCertificates	Recording	#78288456752	Logs
✅	CertificatesTrust_WithNoCert_CreatesAndTrustsCertificate	Recording	#78288456752	Logs
✅	CertificatesTrust_WithUntrustedCert_TrustsCertificate	Recording	#78288456752	Logs
✅	ConfigSetGet_CreatesNestedJsonFormat	Recording	#78288457102	Logs
✅	CreateAndRunAspireStarterProject	Recording	#78288456716	Logs
✅	CreateAndRunAspireStarterProjectWithBundle	Recording	#78288456646	Logs
✅	CreateAndRunEmptyAppHostProject	Recording	#78288457129	Logs
✅	CreateAndRunJavaEmptyAppHostProject	Recording	#78288457282	Logs
✅	CreateAndRunJsReactProject	Recording	#78288456258	Logs
✅	CreateAndRunPythonReactProject	Recording	#78288456644	Logs
✅	CreateAndRunTypeScriptEmptyAppHostProject	Recording	#78288456605	Logs
✅	CreateAndRunTypeScriptStarterProject	Recording	#78288457530	Logs
✅	CreateJavaAppHostWithViteApp	Recording	#78288457105	Logs
✅	CreateTypeScriptAppHostWithViteApp_AllowsGuestAppPackageManagerToDiffer	Recording	#78288457120	Logs
✅	CreateTypeScriptAppHostWithViteApp_UsesConfiguredToolchain	Recording	#78288457120	Logs
✅	DashboardRunWithAgentMcpListTracesReturnsNoTraces	Recording	#78288456221	Logs
✅	DashboardRunWithAgentMcpListTracesReturnsNoTraces_DevLocalhost	Recording	#78288456221	Logs
✅	DashboardRunWithOtelTracesReturnsNoTraces	Recording	#78288456221	Logs
✅	DashboardRunWithOtelTracesReturnsNoTraces_DevLocalhost	Recording	#78288456221	Logs
✅	DeployK8sBasicApiService	Recording	#78288456812	Logs
✅	DeployK8sWithExternalHelmChart	Recording	#78288456868	Logs
✅	DeployK8sWithGarnet	Recording	#78288457267	Logs
✅	DeployK8sWithMongoDB	Recording	#78288457160	Logs
✅	DeployK8sWithMySql	Recording	#78288456650	Logs
✅	DeployK8sWithPostgres	Recording	#78288456893	Logs
✅	DeployK8sWithRabbitMQ	Recording	#78288456790	Logs
✅	DeployK8sWithRedis	Recording	#78288457065	Logs
✅	DeployK8sWithSqlServer	Recording	#78288456679	Logs
✅	DeployK8sWithValkey	Recording	#78288456993	Logs
✅	DeployTypeScriptAppToKubernetes	Recording	#78288457245	Logs
✅	DescribeCommandResolvesReplicaNames	Recording	#78288456977	Logs
✅	DescribeCommandShowsRunningResources	Recording	#78288456977	Logs
✅	DetachFormatJsonProducesValidJson	Recording	#78288457451	Logs
✅	DetachFormatJsonProducesValidJsonWhenRestartingExistingInstance	Recording	#78288457451	Logs
✅	DoPublishAndDeployListStepsWork	Recording	#78288457607	Logs
✅	DocsCommand_RendersInteractiveMarkdownFromLocalSource	Recording	#78288457579	Logs
✅	DoctorCommand_DetectsDeprecatedAgentConfig	Recording	#78288456647	Logs
✅	DoctorCommand_TypeScriptAppHostReportsMissingConfiguredToolchain	Recording	#78288457067	Logs
✅	DoctorCommand_WithSslCertDir_ShowsTrusted	Recording	#78288457067	Logs
✅	DoctorCommand_WithoutSslCertDir_ShowsPartiallyTrusted	Recording	#78288457067	Logs
✅	GatewayWithoutExternalEndpoint_FailsPublishWithGuidance	Recording	#78288456484	Logs
✅	GeneratedAspireDevScript_StartsWatchMode_WithConfiguredToolchain	Recording	#78288457120	Logs
✅	GlobalMigration_HandlesCommentsAndTrailingCommas	Recording	#78288457102	Logs
✅	GlobalMigration_HandlesMalformedLegacyJson	Recording	#78288457102	Logs
✅	GlobalMigration_PreservesAllValueTypes	Recording	#78288457102	Logs
✅	GlobalMigration_SkipsWhenNewConfigExists	Recording	#78288457102	Logs
✅	GlobalSettings_MigratedFromLegacyFormat	Recording	#78288457102	Logs
✅	IngressWithoutExternalEndpoint_FailsPublishWithGuidance	Recording	#78288456484	Logs
✅	InitTypeScriptAppHost_AugmentsExistingViteRepoInWorkspaceSubdirectory	Recording	#78288457120	Logs
✅	InteractiveCSharpInitCreatesExpectedFiles	Recording	#78288456798	Logs
✅	InvalidAppHostPathWithComments_IsHealedOnRun	Recording	#78288456875	Logs
✅	JavaScriptHostingApisRunFromTypeScriptAppHost	Recording	#78288456997	Logs
✅	LatestCliCanStartStableChannelAppHost	Recording	#78288456716	Logs
✅	LatestCliCanStartStableChannelTypeScriptAppHost	Recording	#78288456716	Logs
✅	LegacySettingsMigration_AdjustsRelativeAppHostPath	Recording	#78288457471	Logs
✅	LogsCommandShowsResourceLogs	Recording	#78288456801	Logs
✅	OtelLogsReturnsStructuredLogsFromStarterApp	Recording	#78288456889	Logs
✅	OtelLogsReturnsStructuredLogsFromStarterAppIsolated	Recording	#78288456889	Logs
✅	PsCommandListsRunningAppHost	Recording	#78288457687	Logs
✅	PsFormatJsonOutputsOnlyJsonToStdout	Recording	#78288457687	Logs
✅	PublishJavaScriptPatternsGeneratesExpectedDockerComposeArtifacts	Recording	#78288456828	Logs
✅	PublishWithConfigureEnvFileUpdatesEnvOutput	Recording	#78288456828	Logs
✅	PublishWithDockerComposeServiceCallbackSucceeds	Recording	#78288456828	Logs
✅	PublishWithoutOutputPathUsesAppHostDirectoryDefault	Recording	#78288456828	Logs
✅	ResourceCommand_FailedExecution_DisplaysAppHostLogPathAndLogContainsEntries	Recording	#78288456836	Logs
✅	ResourceCommand_SetAndDeleteParameterUpdatesDescribeOutput	Recording	#78288456836	Logs
✅	RestoreGeneratesSdkFiles	Recording	#78288456694	Logs
✅	RestoreGeneratesSdkFiles_WithConfiguredToolchain	Recording	#78288457219	Logs
✅	RestoreRefreshesGeneratedSdkAfterAddingIntegration	Recording	#78288457219	Logs
✅	RestoreSupportsConfigOnlyHelperPackageAndCrossPackageTypes	Recording	#78288457005	Logs
✅	RunFromParentDirectory_UsesExistingConfigNearAppHost	Recording	#78288456945	Logs
✅	RunReportsSyntaxErrorsForDotNetAppHost	Recording	#78288457060	Logs
✅	RunReportsSyntaxErrorsForTypeScriptAppHost	Recording	#78288457060	Logs
✅	SecretCrudOnDotNetAppHost	Recording	#78288456906	Logs
✅	SecretCrudOnTypeScriptAppHost	Recording	#78288456780	Logs
✅	StagingChannel_ConfigureAndVerifySettings_ThenSwitchChannels	Recording	#78288456662	Logs
✅	StartAndWaitForTypeScriptSqlServerAppHostWithNativeAssets	Recording	#78288457201	Logs
✅	StartReportsSyntaxErrorsForDotNetAppHost	Recording	#78288457060	Logs
✅	StartReportsSyntaxErrorsForTypeScriptAppHost	Recording	#78288457060	Logs
✅	StopAllAppHostsFromAppHostDirectory	Recording	#78288457453	Logs
✅	StopJavaPolyglotAppHostUsingApphostDirectory	Recording	#78288457079	Logs
✅	StopNonInteractiveSingleAppHost	Recording	#78288457453	Logs
✅	StopTypeScriptPolyglotAppHostUsingApphostDirectory	Recording	#78288456677	Logs
✅	StopWithNoRunningAppHostExitsSuccessfully	Recording	#78288456621	Logs
✅	UnAwaitedChainsCompileWithAutoResolvePromises	Recording	#78288457219	Logs
❔	UpdateProjectChannelToStable_CSharpEmptyAppHost_PreservesAspireConfigChannel	Recording	#78288457174	Logs
✅	UpdateProjectChannelToStable_CSharpSingleFileInit_PreservesAspireConfigChannel	Recording	#78288457174	Logs
✅	UpdateProjectChannelToStable_TypeScriptSingleFileInit_PreservesAspireConfigChannel	Recording	#78288457174	Logs
✅	UpdateProjectChannelToStable_TypeScript_PreviewsStablePackagesAndPreservesChannel	Recording	#78288457174	Logs

---

_{📹 Recordings uploaded automatically from CI run #26572248035}

[aspire-repo-bot]

✅ No documentation update needed.

docs_optional → test_only

No signals triggered (signal_count = 0). The advisory only_test_or_build_changes flag is true.

This PR adds a TerminalRun (IAsyncDisposable) test helper to the CLI E2E test suite to ensure consistent diagnostics capture. The author explicitly confirmed no public API was added. All 76 changed files are CLI E2E test infrastructure (helpers, test files) with no user-facing behavior, configuration, or public API surface affected.