Skip to content

Chrome DevTools for coding agents

chore: install HostBindingAdapter (#2186)

Nikolay Vitkovbede4fbdfacb
diff --git a/src/McpContext.ts b/src/McpContext.ts
index 876dc832..a7ac1475 100644
--- a/src/McpContext.ts
+++ b/src/McpContext.ts
@@ -10,8 +10,11 @@ import os from 'node:os';
import path from 'node:path';
import {fileURLToPath, pathToFileURL} from 'node:url';
-import type {TargetUniverse} from './DevtoolsUtils.js';
-import {UniverseManager} from './DevtoolsUtils.js';
+import type {TargetUniverse} from './devtools/DevtoolsUtils.js';
+import {
+ overrideDevToolsGlobals,
+ UniverseManager,
+} from './devtools/DevtoolsUtils.js';
import {HeapSnapshotManager} from './HeapSnapshotManager.js';
import type {AggregatedInfoWithId} from './HeapSnapshotManager.js';
import {McpPage} from './McpPage.js';
@@ -110,6 +113,8 @@ export class McpContext implements Context {
options: McpContextOptions,
locatorClass: typeof Locator,
) {
+ overrideDevToolsGlobals();
+
this.browser = browser;
this.logger = logger;
this.#locatorClass = locatorClass;
diff --git a/src/PageCollector.ts b/src/PageCollector.ts
index bfed5c15..48681ea4 100644
--- a/src/PageCollector.ts
+++ b/src/PageCollector.ts
@@ -4,7 +4,7 @@
* SPDX-License-Identifier: Apache-2.0
*/
-import {FakeIssuesManager} from './DevtoolsUtils.js';
+import {FakeIssuesManager} from './devtools/DevtoolsUtils.js';
import {logger} from './logger.js';
import type {
Target,
diff --git a/src/DevToolsConnectionAdapter.ts b/src/devtools/DevToolsConnectionAdapter.ts
similarity index 95%
rename from src/DevToolsConnectionAdapter.ts
rename to src/devtools/DevToolsConnectionAdapter.ts
index e1f5d0bf..24a737af 100644
--- a/src/DevToolsConnectionAdapter.ts
+++ b/src/devtools/DevToolsConnectionAdapter.ts
@@ -4,9 +4,9 @@
* SPDX-License-Identifier: Apache-2.0
*/
-import type * as puppeteer from './third_party/index.js';
-import type {DevTools} from './third_party/index.js';
-import {CDPSessionEvent} from './third_party/index.js';
+import type * as puppeteer from '../third_party/index.js';
+import type {DevTools} from '../third_party/index.js';
+import {CDPSessionEvent} from '../third_party/index.js';
/**
* This class makes a puppeteer connection look like DevTools CDPConnection.
diff --git a/src/DevtoolsUtils.ts b/src/devtools/DevtoolsUtils.ts
similarity index 84%
rename from src/DevtoolsUtils.ts
rename to src/devtools/DevtoolsUtils.ts
index c09a1d87..5f130a15 100644
--- a/src/DevtoolsUtils.ts
+++ b/src/devtools/DevtoolsUtils.ts
@@ -4,9 +4,8 @@
* SPDX-License-Identifier: Apache-2.0
*/
-import {PuppeteerDevToolsConnection} from './DevToolsConnectionAdapter.js';
-import {Mutex} from './Mutex.js';
-import {DevTools} from './third_party/index.js';
+import {Mutex} from '../Mutex.js';
+import {DevTools} from '../third_party/index.js';
import type {
Browser,
CDPSession,
@@ -14,7 +13,10 @@ import type {
Page,
Protocol,
Target as PuppeteerTarget,
-} from './third_party/index.js';
+} from '../third_party/index.js';
+
+import {PuppeteerDevToolsConnection} from './DevToolsConnectionAdapter.js';
+import {McpHostBindingAdapter} from './McpHostBindingAdapter.js';
/**
* A mock implementation of an issues manager that only implements the methods
@@ -27,90 +29,101 @@ export class FakeIssuesManager extends DevTools.Common.ObjectWrapper
}
}
-// DevTools CDP errors can get noisy.
-DevTools.ProtocolClient.InspectorBackend.test.suppressRequestErrors = true;
-
-// Stub out Network emulation commands on the DevTools Agent prototype globally.
-// This prevents the DevTools Frontend from ever resetting/clearing Puppeteer's
-// active network blocking/throttling rules during target setup or session lifetime.
-const networkAgentPrototype =
- DevTools.ProtocolClient.InspectorBackend.inspectorBackend.agentPrototypes.get(
- 'Network',
+export function overrideDevToolsGlobals(): void {
+ DevTools.Host.InspectorFrontendHost.installInspectorFrontendHost(
+ new McpHostBindingAdapter(),
);
-if (networkAgentPrototype) {
- Object.defineProperty(
- networkAgentPrototype,
- 'invoke_emulateNetworkConditionsByRule',
- {
+
+ // DevTools CDP errors can get noisy.
+ DevTools.ProtocolClient.InspectorBackend.test.suppressRequestErrors = true;
+
+ // Stub out Network emulation commands on the DevTools Agent prototype globally.
+ // This prevents the DevTools Frontend from ever resetting/clearing Puppeteer's
+ // active network blocking/throttling rules during target setup or session lifetime.
+ const networkAgentPrototype =
+ DevTools.ProtocolClient.InspectorBackend.inspectorBackend.agentPrototypes.get(
+ 'Network',
+ );
+ if (networkAgentPrototype) {
+ Object.defineProperty(
+ networkAgentPrototype,
+ 'invoke_emulateNetworkConditionsByRule',
+ {
+ value: () => {
+ return Promise.resolve({
+ ruleIds: [],
+ getError: () => undefined,
+ });
+ },
+ writable: true,
+ configurable: true,
+ enumerable: true,
+ },
+ );
+ Object.defineProperty(
+ networkAgentPrototype,
+ 'invoke_overrideNetworkState',
+ {
+ value: () => {
+ return Promise.resolve({
+ getError: () => undefined,
+ });
+ },
+ writable: true,
+ configurable: true,
+ enumerable: true,
+ },
+ );
+ Object.defineProperty(networkAgentPrototype, 'invoke_enable', {
value: () => {
return Promise.resolve({
- ruleIds: [],
getError: () => undefined,
});
},
writable: true,
configurable: true,
enumerable: true,
+ });
+ Object.defineProperty(networkAgentPrototype, 'invoke_disable', {
+ value: () => {
+ return Promise.resolve({
+ getError: () => undefined,
+ });
+ },
+ writable: true,
+ configurable: true,
+ enumerable: true,
+ });
+ Object.defineProperty(networkAgentPrototype, 'invoke_setBlockedURLs', {
+ value: () => {
+ return Promise.resolve({
+ getError: () => undefined,
+ });
+ },
+ writable: true,
+ configurable: true,
+ enumerable: true,
+ });
+ }
+
+ DevTools.I18n.DevToolsLocale.DevToolsLocale.instance({
+ create: true,
+ data: {
+ navigatorLanguage: 'en-US',
+ settingLanguage: 'en-US',
+ lookupClosestDevToolsLocale: l => l,
},
- );
- Object.defineProperty(networkAgentPrototype, 'invoke_overrideNetworkState', {
- value: () => {
- return Promise.resolve({
- getError: () => undefined,
- });
- },
- writable: true,
- configurable: true,
- enumerable: true,
- });
- Object.defineProperty(networkAgentPrototype, 'invoke_enable', {
- value: () => {
- return Promise.resolve({
- getError: () => undefined,
- });
- },
- writable: true,
- configurable: true,
- enumerable: true,
- });
- Object.defineProperty(networkAgentPrototype, 'invoke_disable', {
- value: () => {
- return Promise.resolve({
- getError: () => undefined,
- });
- },
- writable: true,
- configurable: true,
- enumerable: true,
});
- Object.defineProperty(networkAgentPrototype, 'invoke_setBlockedURLs', {
- value: () => {
- return Promise.resolve({
- getError: () => undefined,
- });
- },
- writable: true,
- configurable: true,
- enumerable: true,
+
+ DevTools.I18n.i18n.registerLocaleDataForTest('en-US', {});
+
+ DevTools.Formatter.FormatterWorkerPool.FormatterWorkerPool.instance({
+ forceNew: true,
+ entrypointURL: import.meta
+ .resolve('../third_party/devtools-formatter-worker.js'),
});
}
-DevTools.I18n.DevToolsLocale.DevToolsLocale.instance({
- create: true,
- data: {
- navigatorLanguage: 'en-US',
- settingLanguage: 'en-US',
- lookupClosestDevToolsLocale: l => l,
- },
-});
-DevTools.I18n.i18n.registerLocaleDataForTest('en-US', {});
-
-DevTools.Formatter.FormatterWorkerPool.FormatterWorkerPool.instance({
- forceNew: true,
- entrypointURL: import.meta
- .resolve('./third_party/devtools-formatter-worker.js'),
-});
-
export interface TargetUniverse {
/** The DevTools target corresponding to the puppeteer Page */
target: DevTools.Target;
diff --git a/src/devtools/McpHostBindingAdapter.ts b/src/devtools/McpHostBindingAdapter.ts
new file mode 100644
index 00000000..b4574bad
--- /dev/null
+++ b/src/devtools/McpHostBindingAdapter.ts
@@ -0,0 +1,255 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/* eslint-disable @typescript-eslint/no-empty-function */
+
+import type {DevTools} from '../third_party/index.js';
+
+/**
+ * BaseClass that is noop or throws for methods.
+ * the McpHostBindingAdapter should only implement methods
+ * that it needs to support.
+ */
+class BaseMcpHostBindingAdapter
+ implements DevTools.Host.InspectorFrontendHostAPI.InspectorFrontendHostAPI
+{
+ declare events: DevTools.Common.EventTarget.EventTarget<DevTools.Host.InspectorFrontendHostAPI.EventTypes>;
+ connectAutomaticFileSystem(): void {}
+
+ disconnectAutomaticFileSystem(): void {}
+
+ addFileSystem(): void {}
+
+ loadCompleted(): void {}
+
+ indexPath(): void {}
+
+ setInspectedPageBounds(): void {}
+
+ showCertificateViewer(): void {}
+
+ setWhitelistedShortcuts(): void {}
+
+ setEyeDropperActive(): void {}
+
+ inspectElementCompleted(): void {}
+
+ openInNewTab(): void {}
+
+ openSearchResultsInNewTab(): void {}
+
+ showItemInFolder(): void {}
+
+ removeFileSystem(): void {}
+
+ requestFileSystems(): void {}
+
+ save(): void {}
+
+ append(): void {}
+
+ close(): void {}
+
+ searchInPath(): void {}
+
+ stopIndexing(): void {}
+
+ bringToFront(): void {}
+
+ closeWindow(): void {}
+
+ copyText(): void {}
+
+ inspectedURLChanged(): void {}
+
+ isolatedFileSystem(): null {
+ throw new Error('Not implemented');
+ }
+
+ registerPreference(): void {}
+
+ getPreferences(): void {}
+
+ getPreference(): void {}
+
+ setPreference(): void {}
+
+ removePreference(): void {}
+
+ clearPreferences(): void {}
+
+ getSyncInformation(): void {}
+
+ getHostConfig(): void {}
+
+ upgradeDraggedFileSystemPermissions(): void {}
+
+ platform(): string {
+ throw new Error('Not implemented');
+ }
+
+ recordCountHistogram(): void {}
+
+ recordEnumeratedHistogram(): void {}
+
+ recordPerformanceHistogram(): void {}
+
+ recordPerformanceHistogramMedium(): void {}
+
+ recordUserMetricsAction(): void {}
+
+ recordNewBadgeUsage(): void {}
+
+ sendMessageToBackend(): void {}
+
+ setDevicesDiscoveryConfig(): void {}
+
+ setDevicesUpdatesEnabled(): void {}
+
+ openRemotePage(): void {}
+
+ openNodeFrontend(): void {}
+
+ setInjectedScriptForOrigin(): void {}
+
+ setIsDocked(): void {}
+
+ showSurvey(): void {}
+
+ canShowSurvey(): void {}
+
+ zoomFactor(): number {
+ throw new Error('Not implemented');
+ }
+
+ zoomIn(): void {}
+
+ zoomOut(): void {}
+
+ resetZoom(): void {}
+
+ showContextMenuAtPoint(): void {}
+
+ reattach(): void {}
+
+ readyForTest(): void {}
+
+ connectionReady(): void {}
+
+ setOpenNewWindowForPopups(): void {}
+
+ isHostedMode(): boolean {
+ throw new Error('Not implemented');
+ }
+
+ setAddExtensionCallback(): void {}
+
+ initialTargetId(): Promise<string | null> {
+ throw new Error('Not implemented');
+ }
+
+ doAidaConversation(
+ _request: string,
+ _streamId: number,
+ cb: (
+ result: DevTools.Host.InspectorFrontendHostAPI.DoAidaConversationResult,
+ ) => void,
+ ): void {
+ cb({
+ error: 'Not implemented',
+ });
+ }
+
+ registerAidaClientEvent(
+ _request: string,
+ cb: (
+ result: DevTools.Host.InspectorFrontendHostAPI.AidaClientResult,
+ ) => void,
+ ): void {
+ cb({
+ error: 'Not implemented',
+ });
+ }
+
+ aidaCodeComplete(
+ _request: string,
+ cb: (
+ result: DevTools.Host.InspectorFrontendHostAPI.AidaCodeCompleteResult,
+ ) => void,
+ ): void {
+ cb({
+ error: 'Not implemented',
+ });
+ }
+
+ dispatchHttpRequest(
+ _request: DevTools.Host.InspectorFrontendHostAPI.DispatchHttpRequestRequest,
+ cb: (
+ result: DevTools.Host.InspectorFrontendHostAPI.DispatchHttpRequestResult,
+ ) => void,
+ ): void {
+ cb({
+ error: 'Not implemented',
+ });
+ }
+
+ recordImpression(): void {}
+
+ recordResize(): void {}
+
+ recordClick(): void {}
+
+ recordHover(): void {}
+
+ recordDrag(): void {}
+
+ recordChange(): void {}
+
+ recordKeyDown(): void {}
+
+ recordSettingAccess(): void {}
+
+ recordFunctionCall(): void {}
+
+ setChromeFlag(): void {}
+
+ requestRestart(): void {}
+
+ loadNetworkResource(): void {}
+}
+
+export class McpHostBindingAdapter extends BaseMcpHostBindingAdapter {
+ override isolatedFileSystem(): null {
+ return null;
+ }
+
+ override platform(): string {
+ switch (process.platform) {
+ case 'darwin':
+ return 'mac';
+ case 'win32':
+ return 'windows';
+ default:
+ return 'linux';
+ }
+ }
+
+ override zoomFactor(): number {
+ return 1;
+ }
+
+ override isHostedMode(): boolean {
+ return true;
+ }
+
+ override initialTargetId(): Promise<string | null> {
+ return Promise.resolve(null);
+ }
+
+ override loadNetworkResource(): void {
+ // TODO(nvitkov): Add support for this
+ }
+}
diff --git a/src/formatters/ConsoleFormatter.ts b/src/formatters/ConsoleFormatter.ts
index 5cbf4d66..5c77c216 100644
--- a/src/formatters/ConsoleFormatter.ts
+++ b/src/formatters/ConsoleFormatter.ts
@@ -8,7 +8,7 @@ import {
createStackTraceForConsoleMessage,
type TargetUniverse,
SymbolizedError,
-} from '../DevtoolsUtils.js';
+} from '../devtools/DevtoolsUtils.js';
import {UncaughtError} from '../PageCollector.js';
import * as DevTools from '../third_party/index.js';
import type {ConsoleMessage} from '../third_party/index.js';
diff --git a/tests/DevtoolsUtils.test.ts b/tests/devtools/DevtoolsUtils.test.ts
similarity index 92%
rename from tests/DevtoolsUtils.test.ts
rename to tests/devtools/DevtoolsUtils.test.ts
index d51e6f02..a01127a4 100644
--- a/tests/DevtoolsUtils.test.ts
+++ b/tests/devtools/DevtoolsUtils.test.ts
@@ -9,18 +9,17 @@ import {afterEach, describe, it} from 'node:test';
import sinon from 'sinon';
-import {UniverseManager} from '../src/DevtoolsUtils.js';
-import {DevTools} from '../src/third_party/index.js';
-import type {Browser, Target} from '../src/third_party/index.js';
-
-import {serverHooks} from './server.js';
+import {UniverseManager} from '../../src/devtools/DevtoolsUtils.js';
+import {DevTools} from '../../src/third_party/index.js';
+import type {Browser, Target} from '../../src/third_party/index.js';
+import {serverHooks} from '../server.js';
import {
getMockBrowser,
getMockPage,
html,
mockListener,
withBrowser,
-} from './utils.js';
+} from '../utils.js';
describe('UniverseManager', () => {
const server = serverHooks();
diff --git a/tests/formatters/ConsoleFormatter.test.ts b/tests/formatters/ConsoleFormatter.test.ts
index 977492b2..2213f429 100644
--- a/tests/formatters/ConsoleFormatter.test.ts
+++ b/tests/formatters/ConsoleFormatter.test.ts
@@ -6,7 +6,7 @@
import {describe, it} from 'node:test';
-import {SymbolizedError} from '../../src/DevtoolsUtils.js';
+import {SymbolizedError} from '../../src/devtools/DevtoolsUtils.js';
import {ConsoleFormatter} from '../../src/formatters/ConsoleFormatter.js';
import {UncaughtError} from '../../src/PageCollector.js';
import type {ConsoleMessage, Protocol} from '../../src/third_party/index.js';
diff --git a/tests/setup.ts b/tests/setup.ts
index b9a54b0d..ed916290 100644
--- a/tests/setup.ts
+++ b/tests/setup.ts
@@ -7,7 +7,13 @@
import '../src/polyfill.js';
import path from 'node:path';
-import {it} from 'node:test';
+import {before, it} from 'node:test';
+
+import {overrideDevToolsGlobals} from '../src/devtools/DevtoolsUtils.js';
+
+before(() => {
+ overrideDevToolsGlobals();
+});
// This is run by Node when we execute the tests via the --import flag.
it.snapshot.setResolveSnapshotPath(testPath => {
diff --git a/tests/trace-processing/parse.test.ts b/tests/trace-processing/parse.test.ts
index c9b87434..19510ffc 100644
--- a/tests/trace-processing/parse.test.ts
+++ b/tests/trace-processing/parse.test.ts
@@ -12,8 +12,6 @@ import {
parseRawTraceBuffer,
} from '../../src/trace-processing/parse.js';
-import '../../src/DevtoolsUtils.js';
-
import {loadTraceAsBuffer} from './fixtures/load.js';
describe('Trace parsing', async () => {