Integrated Browser and Port Forwarding

Purpose and Scope

The integrated browser is the in-editor surface for opening and interacting with web pages without leaving VS Code. In the product documentation, it is described as an experimental browser that can preview web applications, test authentication flows, and provide page elements as context for AI chat prompts. Port forwarding complements that workflow by making a locally running service reachable through the Ports view, so a developer can build a web app, open it in VS Code, share or inspect the forwarded address, and keep the edit-build-test loop inside the workbench.

For this repository-backed page, the strongest supplied source signals sit around the Copilot and agent side of that loop rather than the browser UI implementation itself. The evidence shows how agent workflows collect diagnostics, receive diagnostic-change notifications, normalize language-server results, log chat/tool spans, and handle remote code or documentation search failures. These pieces matter for browser-assisted web-app testing because an autonomous agent needs more than a page view: it also needs editor diagnostics, reliable tool telemetry, and clear error classes when context gathering fails.

Sources: extensions/copilot/src/extension/chatSessions/copilotcli/vscode-node/test/getDiagnostics.spec.ts, extensions/copilot/src/extension/chatSessions/copilotcli/vscode-node/test/diagnosticsChanged.spec.ts, extensions/copilot/test/simulation/diagnosticProviders/index.ts, extensions/copilot/src/extension/chat/vscode-node/test/chatDebugFileLoggerService.spec.ts, extensions/copilot/src/platform/remoteSearch/test/node/codeOrDocsSearchErrors.spec.ts

Relevant Source Files

extensions/copilot/src/platform/remoteSearch/test/node/codeOrDocsSearchErrors.spec.ts verifies typed construction of remote code-or-docs search errors, including inaccessible repositories, unavailable embeddings, not-indexed repositories, max retries, and endpoint-access failures.
extensions/copilot/test/simulation/diagnosticProviders/index.ts exposes KnownDiagnosticProviders for TypeScript, ESLint, Python, Roslyn, C++, and Ruff diagnostics and provides a shared getDiagnostics dispatch function for simulation tests.
extensions/copilot/src/extension/chat/vscode-node/test/chatDebugFileLoggerService.spec.ts tests chat debug file logging around completed OpenTelemetry spans, span events, chat sessions, tool calls, token usage, and model attributes.
extensions/copilot/src/extension/chatSessions/copilotcli/vscode-node/test/diagnosticsChanged.spec.ts tests registration and debouncing of diagnostics_changed push notifications broadcast from VS Code language diagnostics through an in-process HTTP server.
extensions/copilot/src/extension/chatSessions/copilotcli/vscode-node/test/getDiagnostics.spec.ts tests the get_diagnostics tool, including URI-scoped diagnostics, all-file diagnostics, severity mapping, empty results, and serialized ranges.
extensions/copilot/src/extension/completions-core/vscode-node/lib/src/prompt/test/defaultDiagnosticSettings.test.ts tests parsing and defaults for DefaultDiagnosticSettings, including warning policy, maximum line distance, and maximum diagnostic count.

Reader Workflow

A typical web-app workflow starts with a local service. The official port-forwarding documentation uses a simple npx serve example on port 3000, then directs the user to the Ports view with Ports: Focus on Ports View and Forward a Port. Once a port is forwarded, the Ports view shows a forwarded address and actions to copy the address, open it externally, or open an in-editor preview. Forwarded ports are private by default and require the same GitHub account used to create the tunnel, while public visibility removes that sign-in requirement.

The integrated browser then becomes the local verification surface. Official documentation lists several entry points: run Browser: Open Integrated Browser, use View > Browser, select the title-bar globe button when workbench.browser.showInTitleBar allows it, select a localhost link when workbench.browser.openLocalhostLinks is enabled, ask an agent to open or interact with a page, or start an editor-browser debug session. The browser supports multiple editor-tab instances and common navigation over http://, https://, and file:// URLs, so it fits both local preview and file-based repro scenarios.

Browser agent tools build on top of that surface. The official guide describes tools such as openBrowserPage, navigatePage, readPage, screenshotPage, clickElement, hoverElement, dragElement, typeInPage, handleDialog, and runPlaywrightCode. Those tools are experimental and must be explicitly enabled through workbench.browser.enableChatTools and the chat tools picker. The repository diagnostics tests show the other half of the loop: while the agent interacts with the page, it can also ask for compiler or linter diagnostics, observe when diagnostics change, and use those signals to decide whether a code fix actually improved the project.

System-to-Code Mapping

The diagnostic bridge is represented most directly by the Copilot CLI chat-session tests. registerGetDiagnosticsTool registers a tool named get_diagnostics, and the tests exercise both a specific file:///test/file.ts request and the no-URI case that returns diagnostics for every file. Results include a URI, filesystem path, diagnostic message, severity, optional source and code, and a range with start and end positions. This is the shape an agent needs when it has changed a web app and wants precise editor feedback instead of relying only on what appears in the browser.

registerDiagnosticsChangedNotification covers the push side of the same contract. The tests mock vscode.languages.onDidChangeDiagnostics, trigger URI change events, wait through fake timers, and assert that the in-process HTTP server broadcasts a diagnostics_changed notification. The suite also checks debouncing, so rapid editor updates do not cause a flood of agent notifications. In a browser-testing loop, that debounce matters because save, compile, hot reload, and type-checking steps can produce several intermediate diagnostic states before the page and source stabilize.

The simulation diagnostic provider registry generalizes diagnostics across languages. KnownDiagnosticProviders includes tsc, tscIgnoreImportErrors, eslint, pyright, pylint, roslyn, cpp, and ruff, and the exported getDiagnostics function dispatches by DiagnosticProviderId. For browser and frontend work, TypeScript and ESLint are the obvious providers, but the registry is intentionally broader: agents can evaluate mixed repositories where a web UI is backed by Python services, .NET projects, C++ native modules, or Ruff-managed Python code.

Default diagnostic settings provide a further control surface for how much diagnostic context enters prompts. The tests for DefaultDiagnosticSettings.from cover null, undefined, empty, invalid JSON, empty objects, valid JSON, invalid warning values, and missing numeric fields. The resulting configuration includes warnings, maxLineDistance, and maxDiagnostics, with defaults such as warning behavior falling back to no and line distance falling back to 10. That keeps diagnostics useful without letting a large project overwhelm browser-agent context.

Sources: extensions/copilot/test/simulation/diagnosticProviders/index.ts, extensions/copilot/src/extension/completions-core/vscode-node/lib/src/prompt/test/defaultDiagnosticSettings.test.ts

API and Tooling Reference

Surface	Concrete names	Behavior shown by evidence
Integrated browser commands and settings	`Browser: Open Integrated Browser`, `View > Browser`, `workbench.browser.showInTitleBar`, `workbench.browser.openLocalhostLinks`	Reader-facing browser entry points and localhost-link behavior from official docs.
Browser agent tools	`openBrowserPage`, `navigatePage`, `readPage`, `screenshotPage`, `clickElement`, `hoverElement`, `dragElement`, `typeInPage`, `handleDialog`, `runPlaywrightCode`	Experimental agent tools for page navigation, inspection, interaction, dialogs, and custom Playwright automation.
Port forwarding	`Ports: Focus on Ports View`, `Forward a Port`, forwarded address visibility	Built-in dev-tunnel workflow for exposing local services, with private-by-default access and optional public visibility.
Diagnostics pull tool	`get_diagnostics`	Returns URI-scoped or all-file diagnostics with message, severity, source, code, and range.
Diagnostics push notification	`diagnostics_changed`	Broadcasts debounced diagnostic updates from VS Code language diagnostics through the chat-session server path.
Diagnostic prompt settings	`DefaultDiagnosticSettings`, `warnings`, `maxLineDistance`, `maxDiagnostics`	Parses diagnostic-context limits and defaults for completion prompt construction.

The error-handling tests define a second reliability boundary. constructSearchRepoError maps repository-search failure types to classes such as InaccessibleRepoOrgError, EmbeddingsUnavailableError, NotIndexedError, and the base CodeOrDocsSearchRepoError. constructSearchError maps non-repository failures to MaxRetriesExceededError, NoAccessToEndpointError, or a generic Error for unknown cases. Browser agents often need source and documentation context while debugging a page, so these typed failures let the chat layer distinguish access, indexing, embedding, retry, and endpoint problems instead of reporting every context failure as the same condition.

Sources: extensions/copilot/src/platform/remoteSearch/test/node/codeOrDocsSearchErrors.spec.ts

Execution Flow for Agent-Assisted Web Testing

A practical closed loop looks like this. First, run the web app locally and open it in the integrated browser, either manually or by letting an enabled browser agent tool open the page. Second, interact with the page through normal browser controls or through chat tools that can navigate, read, click, type, capture screenshots, and run Playwright snippets. Third, inspect the page result and ask the agent to correlate it with editor diagnostics. The get_diagnostics path supplies the current diagnostic set, while diagnostics_changed tells the agent that a new type-check or linting result is ready after an edit.

Fourth, the agent edits source files and repeats the browser interaction. Diagnostic settings should bound how many warnings and nearby messages are included so that the agent receives the most relevant compiler and linter feedback. If the agent also searches the repository or documentation for context, typed search errors explain whether the problem is lack of access, missing indexing, unavailable embeddings, exhausted retries, or an inaccessible endpoint. Finally, chat debug file logging records spans for chat and tool operations, including session identifiers, model names, token usage, and tool names, which gives developers a way to audit how the automated loop behaved.

Sources: extensions/copilot/src/extension/chat/vscode-node/test/chatDebugFileLoggerService.spec.ts, extensions/copilot/src/extension/completions-core/vscode-node/lib/src/prompt/test/defaultDiagnosticSettings.test.ts, extensions/copilot/src/platform/remoteSearch/test/node/codeOrDocsSearchErrors.spec.ts

Testing Signals and Next Steps

The most important repository signal is that diagnostics are treated as a first-class automation contract. Tests cover registration of the get_diagnostics tool, empty diagnostic results, all-file results, severity conversion for error, warning, information, and hint levels, and structured diagnostic ranges. Separate push-notification tests verify listener registration, broadcast payload shape, debouncing, and cleared diagnostics. Together, those tests protect the communication channel an agent depends on when using the integrated browser to validate a generated or modified web app.

When extending this area, keep the surfaces separate. Browser tools should prove what happened in the page; diagnostics tools should prove what the editor and language services know about the code; port forwarding should expose the correct local service with the intended visibility; and telemetry should explain which chat sessions and tools were involved. Start with the official browser and port-forwarding commands for user-facing behavior, then use the Copilot diagnostic tests as examples for agent-visible feedback contracts. Related pages to read next are terminal basics for starting local services, debugging overview for editor-browser sessions, and chat tools and approvals for autonomous tool permissions.

Ask a question...