Add browser automation resource commands

[David Fowler (davidfowl)]

Description

This builds on the browser diagnostics work and turns the browser child resource into a browser automation resource that can be driven from the dashboard/resource-command API. The goal is to make local web apps inspectable and operable by agents and humans without leaving the Aspire app model: open a tracked browser, inspect the current page, run common interactions, wait for UI readiness, capture screenshots, and stream browser diagnostics back into resource logs.

The user-visible behavior is:

• WithBrowserAutomation() adds a browser child resource for an HTTP/HTTPS resource.
• The browser resource can open a tracked Chromium-based browser session for the parent resource endpoint.
• Resource commands can inspect page state, query selectors, navigate, click, fill, type, press keys, scroll, wait for URL/text/load/element/function conditions, manage cookies/storage/dialogs/tabs/downloads/uploads, run CDP escape-hatch commands, and capture screenshots.
• Browser console, exception, log, and network events are forwarded into the browser resource logs.
• Browser, profile, and user data mode can be configured via AppHost API, Aspire:Hosting:Browser configuration, or the dashboard configure command.
• TypeScript AppHost code generation recognizes the new browser automation export.

Implementation details:

• Renames the previous browser logs resource surface to browser automation while preserving legacy configuration fallback for earlier Aspire:Hosting:BrowserAutomation settings.
• Adds a fixed browser-side helper script plus small generated JavaScript command expressions evaluated through CDP Runtime.evaluate.
• Adds browser host/session management for owned pipe-backed Chromium processes and validated WebSocket endpoint adoption.
• Adds CDP protocol framing/parsing, resource-command input validation callbacks, localized command strings, playground usage, and browser-focused tests.

User-facing usage

C# AppHost:

var frontend = builder.AddProject<Projects.MyFrontend>("frontend")
    .WithExternalHttpEndpoints()
    .WithBrowserAutomation();

Optional explicit browser configuration:

builder.AddProject<Projects.WebFrontend>("web")
    .WithExternalHttpEndpoints()
    .WithBrowserAutomation(
        browser: "msedge",
        profile: "Default",
        userDataMode: BrowserUserDataMode.Shared);

Configuration can also set global or resource-specific defaults:

{
  "Aspire": {
    "Hosting": {
      "Browser": {
        "Browser": "msedge",
        "UserDataMode": "Shared",
        "Profile": "Default",
        "frontend": {
          "Browser": "chrome"
        }
      }
    }
  }
}

Examples of resource-command payloads exposed by the browser child resource:

{ "command": "inspect-browser", "arguments": { "maxElements": 80, "maxTextLength": 8000 } }

{ "command": "click-browser", "arguments": { "selector": "#submit", "snapshotAfter": true } }

{ "command": "wait", "arguments": { "urlContains": "/dashboard", "timeoutMilliseconds": 3000 } }

{ "command": "capture-screenshot", "arguments": { "format": "jpeg", "quality": 80, "fullPage": true } }

Security considerations

This change needs security review because it introduces browser automation capabilities that spawn local Chromium-based browser processes, create persistent Aspire-managed browser user data directories, evaluate generated JavaScript in the tracked page through CDP, accept command input used for selectors/URLs/CDP parameters/file paths, and expose upload/download/screenshot commands.

Important boundaries and mitigations in this PR:

• The tracked browser does not use the user's normal browser profile root; shared and isolated modes use Aspire-managed browser data paths.
• The default owned-browser path uses a private CDP pipe instead of opening a browser debug port.
• WebSocket endpoint adoption is treated as a stale/untrusted hint and validates schema, browser identity, user data root, process liveness, endpoint reachability, and profile compatibility before use.
• Resource-command arguments are validated before execution for ranges, required conditional inputs, absolute navigation URLs, JSON object payloads, upload array shape, wait conditions, and screenshot quality.
• JavaScript command arguments are JSON-literal encoded before embedding into generated script source.

Validation:

• ./dotnet.sh build src/Aspire.Hosting.Browsers/Aspire.Hosting.Browsers.csproj --no-restore /p:SkipNativeBuild=true --nologo -v:minimal
• ./dotnet.sh test --project tests/Aspire.Hosting.Browsers.Tests/Aspire.Hosting.Browsers.Tests.csproj --no-launch-profile -- --filter-method "*.WithBrowserAutomation_BrowserCommandsForwardArgumentsAndReturnJson" --filter-method "*.WithBrowserAutomation_BrowserCommandValidationRejectsInvalidArgumentsBeforeExecution" --filter-not-trait "quarantined=true" --filter-not-trait "outerloop=true"
• ./dotnet.sh test --project tests/Aspire.Hosting.CodeGeneration.TypeScript.Tests/Aspire.Hosting.CodeGeneration.TypeScript.Tests.csproj --no-launch-profile -- --filter-method "*.Scanner_BrowsersAssembly_WithBrowserAutomationCapability" --filter-not-trait "quarantined=true" --filter-not-trait "outerloop=true"
• git diff --check

Fixes # (issue)

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
    • If yes, did you have an API Review for it?
      • Yes
      • No
    • Did you add <remarks /> and <code /> elements on your triple slash comments?
      • Yes
      • No
  • No
• Does the change make any security assumptions or guarantees?
  • Yes
    • If yes, have you done a threat model and had a security review?
      • Yes
      • No
  • 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 -- 16706

Or

• Run remotely in PowerShell:

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

[github-actions]

Re-running the failed jobs in the CI workflow for this pull request because 1 job was identified as retry-safe transient failures in the CI run attempt.
GitHub was asked to rerun all failed jobs for that attempt, and the rerun is being tracked in the rerun attempt.
The job links below point to the failed attempt jobs that matched the retry-safe transient failure rules.

• Tests / Hosting-1 / Hosting-1 (windows-latest) - Job-level runner or infrastructure failure matched the transient allowlist.

[Copilot]

Copilot wasn't able to review this pull request because it exceeds the maximum number of lines (20,000). Try reducing the number of changed lines and requesting a review from Copilot again.

[Copilot]

Copilot wasn't able to review this pull request because it exceeds the maximum number of lines (20,000). Try reducing the number of changed lines and requesting a review from Copilot again.

[github-actions]

❓ CLI E2E Tests unknown — 85 passed, 0 failed, 1 unknown (commit 10588c1)

View all recordings

Status	Test	Recording
✅	AddPackageInteractiveWhileAppHostRunningDetached	✅ ▶️ View recording
✅	AddPackageWhileAppHostRunningDetached	✅ ▶️ View recording
✅	AgentCommands_AllHelpOutputs_AreCorrect	✅ ▶️ View recording
✅	AgentInitCommand_DefaultSelection_InstallsSkillOnly	✅ ▶️ View recording
✅	AgentInitCommand_MigratesDeprecatedConfig	✅ ▶️ View recording
✅	AspireAddPackageVersionToDirectoryPackagesProps	✅ ▶️ View recording
✅	AspireInitSingleFileAppHostRunsViaDotnetRunAppHost	✅ ▶️ View recording
✅	AspireInitWithExistingAppHostDirRecreatesMissingNuGetConfigAndPreservesFiles	✅ ▶️ View recording
❔	AspireInitWithSolutionFileGeneratesAppHostThatBuildsAgainstChannelHive	❔ ▶️ View recording
✅	AspireUpdateRemovesAppHostPackageVersionFromDirectoryPackagesProps	✅ ▶️ View recording
✅	AspireUpdateRemovesOrphanAppHostPackageVersionWhenSdkAlreadyCurrent	✅ ▶️ View recording
✅	Banner_DisplayedOnFirstRun	✅ ▶️ View recording
✅	Banner_DisplayedWithExplicitFlag	✅ ▶️ View recording
✅	Banner_NotDisplayedWithNoLogoFlag	✅ ▶️ View recording
✅	CertificatesClean_RemovesCertificates	✅ ▶️ View recording
✅	CertificatesTrust_WithNoCert_CreatesAndTrustsCertificate	✅ ▶️ View recording
✅	CertificatesTrust_WithUntrustedCert_TrustsCertificate	✅ ▶️ View recording
✅	ConfigSetGet_CreatesNestedJsonFormat	✅ ▶️ View recording
✅	CreateAndRunAspireStarterProject	✅ ▶️ View recording
✅	CreateAndRunAspireStarterProjectWithBundle	✅ ▶️ View recording
✅	CreateAndRunEmptyAppHostProject	✅ ▶️ View recording
✅	CreateAndRunJavaEmptyAppHostProject	✅ ▶️ View recording
✅	CreateAndRunJsReactProject	✅ ▶️ View recording
✅	CreateAndRunPythonReactProject	✅ ▶️ View recording
✅	CreateAndRunTypeScriptEmptyAppHostProject	✅ ▶️ View recording
✅	CreateAndRunTypeScriptStarterProject	✅ ▶️ View recording
✅	CreateJavaAppHostWithViteApp	✅ ▶️ View recording
✅	CreateTypeScriptAppHostWithViteApp_UsesConfiguredToolchain	✅ ▶️ View recording
✅	DashboardRunWithOtelTracesReturnsNoTraces	✅ ▶️ View recording
✅	DeployK8sBasicApiService	✅ ▶️ View recording
✅	DeployK8sWithExternalHelmChart	✅ ▶️ View recording
✅	DeployK8sWithGarnet	✅ ▶️ View recording
✅	DeployK8sWithMongoDB	✅ ▶️ View recording
✅	DeployK8sWithMySql	✅ ▶️ View recording
✅	DeployK8sWithPostgres	✅ ▶️ View recording
✅	DeployK8sWithRabbitMQ	✅ ▶️ View recording
✅	DeployK8sWithRedis	✅ ▶️ View recording
✅	DeployK8sWithSqlServer	✅ ▶️ View recording
✅	DeployK8sWithValkey	✅ ▶️ View recording
✅	DeployTypeScriptAppToKubernetes	✅ ▶️ View recording
✅	DescribeCommandResolvesReplicaNames	✅ ▶️ View recording
✅	DescribeCommandShowsRunningResources	✅ ▶️ View recording
✅	DetachFormatJsonProducesValidJson	✅ ▶️ View recording
✅	DetachFormatJsonProducesValidJsonWhenRestartingExistingInstance	✅ ▶️ View recording
✅	DoListStepsShowsPipelineSteps	✅ ▶️ View recording
✅	DocsCommand_RendersInteractiveMarkdownFromLocalSource	✅ ▶️ View recording
✅	DoctorCommand_DetectsDeprecatedAgentConfig	✅ ▶️ View recording
✅	DoctorCommand_TypeScriptAppHostReportsMissingConfiguredToolchain	✅ ▶️ View recording
✅	DoctorCommand_WithSslCertDir_ShowsTrusted	✅ ▶️ View recording
✅	DoctorCommand_WithoutSslCertDir_ShowsPartiallyTrusted	✅ ▶️ View recording
✅	GlobalMigration_HandlesCommentsAndTrailingCommas	✅ ▶️ View recording
✅	GlobalMigration_HandlesMalformedLegacyJson	✅ ▶️ View recording
✅	GlobalMigration_PreservesAllValueTypes	✅ ▶️ View recording
✅	GlobalMigration_SkipsWhenNewConfigExists	✅ ▶️ View recording
✅	GlobalSettings_MigratedFromLegacyFormat	✅ ▶️ View recording
✅	InitTypeScriptAppHost_AugmentsExistingViteRepoAtRoot	✅ ▶️ View recording
✅	InteractiveCSharpInitCreatesExpectedFiles	✅ ▶️ View recording
✅	InvalidAppHostPathWithComments_IsHealedOnRun	✅ ▶️ View recording
✅	LatestCliCanStartStableChannelAppHost	✅ ▶️ View recording
✅	LatestCliCanStartStableChannelTypeScriptAppHost	✅ ▶️ View recording
✅	LegacySettingsMigration_AdjustsRelativeAppHostPath	✅ ▶️ View recording
✅	LogLevelTrace_ProducesTraceEntriesInCliLogFile	✅ ▶️ View recording
✅	LogsCommandShowsResourceLogs	✅ ▶️ View recording
✅	OtelLogsReturnsStructuredLogsFromStarterApp	✅ ▶️ View recording
✅	OtelLogsReturnsStructuredLogsFromStarterAppIsolated	✅ ▶️ View recording
✅	PsCommandListsRunningAppHost	✅ ▶️ View recording
✅	PsFormatJsonOutputsOnlyJsonToStdout	✅ ▶️ View recording
✅	PublishWithConfigureEnvFileUpdatesEnvOutput	✅ ▶️ View recording
✅	PublishWithDockerComposeServiceCallbackSucceeds	✅ ▶️ View recording
✅	PublishWithoutOutputPathUsesAppHostDirectoryDefault	✅ ▶️ View recording
✅	ResourceCommand_FailsWhenInteractionServiceIsRequired	✅ ▶️ View recording
✅	ResourceCommand_SetAndDeleteParameterUpdatesDescribeOutput	✅ ▶️ View recording
✅	RestoreGeneratesSdkFiles	✅ ▶️ View recording
✅	RestoreGeneratesSdkFiles_WithConfiguredToolchain	✅ ▶️ View recording
✅	RestoreRefreshesGeneratedSdkAfterAddingIntegration	✅ ▶️ View recording
✅	RestoreSupportsConfigOnlyHelperPackageAndCrossPackageTypes	✅ ▶️ View recording
✅	RunFromParentDirectory_UsesExistingConfigNearAppHost	✅ ▶️ View recording
✅	SecretCrudOnDotNetAppHost	✅ ▶️ View recording
✅	SecretCrudOnTypeScriptAppHost	✅ ▶️ View recording
✅	StagingChannel_ConfigureAndVerifySettings_ThenSwitchChannels	✅ ▶️ View recording
✅	StartAndWaitForTypeScriptSqlServerAppHostWithNativeAssets	✅ ▶️ View recording
✅	StopAllAppHostsFromAppHostDirectory	✅ ▶️ View recording
✅	StopNonInteractiveSingleAppHost	✅ ▶️ View recording
✅	StopWithNoRunningAppHostExitsSuccessfully	✅ ▶️ View recording
✅	UnAwaitedChainsCompileWithAutoResolvePromises	✅ ▶️ View recording
✅	UpdateProjectChannelToStable_TypeScript_PicksUpStablePackages	✅ ▶️ View recording

---

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