Chrome DevTools for coding agents
refactor: use puppeteer Extension API (#1911)
Nicholas Roscinoec895f195aa2
diff --git a/package-lock.json b/package-lock.jsonindex 73246f61..66834337 100644--- a/package-lock.json+++ b/package-lock.json@@ -37,7 +37,7 @@"globals": "^17.0.0","lighthouse": "13.1.0","prettier": "^3.6.2",- "puppeteer": "24.41.0",+ "puppeteer": "24.42.0","rollup": "4.60.2","rollup-plugin-cleanup": "^3.2.1","rollup-plugin-license": "^3.6.0",@@ -7486,9 +7486,9 @@}},"node_modules/puppeteer": {- "version": "24.41.0",- "resolved": "https://registry.npmjs.org/puppeteer/-/puppeteer-24.41.0.tgz",- "integrity": "sha512-W6Fk0J3TPjjtwjXOyR/qf+YaL0H/Uq8HIgHcXG4mNM/IgbKMCH/HPyK0Fi2qbTU/QpSl9bCte2yBpGHKejTpIw==",+ "version": "24.42.0",+ "resolved": "https://registry.npmjs.org/puppeteer/-/puppeteer-24.42.0.tgz",+ "integrity": "sha512-94MoPfFp2eY3eYIMdINkez4IOP5TMHntlZbVx06fHlQTtiQiYgaY0L2Zzfod8PVUkPqP7m3Qlre2v8YS8cudPA==","dev": true,"hasInstallScript": true,"license": "Apache-2.0",@@ -7497,7 +7497,7 @@"chromium-bidi": "14.0.0","cosmiconfig": "^9.0.0","devtools-protocol": "0.0.1595872",- "puppeteer-core": "24.41.0",+ "puppeteer-core": "24.42.0","typed-query-selector": "^2.12.1"},"bin": {@@ -7508,9 +7508,9 @@}},"node_modules/puppeteer-core": {- "version": "24.41.0",- "resolved": "https://registry.npmjs.org/puppeteer-core/-/puppeteer-core-24.41.0.tgz",- "integrity": "sha512-rLIUri7E/NQ3APSEYCCozaSJx0u8Tu9wxO6BJwnvXmIgILSK3L0TombaVh3izp1njAGrO6H2ru0hcIrLF+gWLw==",+ "version": "24.42.0",+ "resolved": "https://registry.npmjs.org/puppeteer-core/-/puppeteer-core-24.42.0.tgz",+ "integrity": "sha512-T4zXokk/izH01fYPhyyev1A4piWiOKrYq7CUFpdoYQxmOnXoV6YjUabmfIjCYkNspSoAXIxRid3Tw+Vg0fthYg==","dev": true,"license": "Apache-2.0","dependencies": {diff --git a/package.json b/package.jsonindex 23cd72c4..328ec102 100644--- a/package.json+++ b/package.json@@ -71,7 +71,7 @@"globals": "^17.0.0","lighthouse": "13.1.0","prettier": "^3.6.2",- "puppeteer": "24.41.0",+ "puppeteer": "24.42.0","rollup": "4.60.2","rollup-plugin-cleanup": "^3.2.1","rollup-plugin-license": "^3.6.0",diff --git a/scripts/test.mjs b/scripts/test.mjsindex 004d344b..5e0457da 100644--- a/scripts/test.mjs+++ b/scripts/test.mjs@@ -77,7 +77,7 @@ const nodeArgs = [...files,];-function installChrome(version) {+function _installChrome(version) {try {return execSync(`npx puppeteer browsers install chrome@${version} --format "{{path}}"`,@@ -112,9 +112,6 @@ async function runTests(attempt) {});}-const chromePath = installChrome('146.0.7680.31');-process.env.CHROME_M146_EXECUTABLE_PATH = chromePath;-const maxAttempts = shouldRetry ? 3 : 1;let exitCode = 1;diff --git a/src/McpContext.ts b/src/McpContext.tsindex 198a91a5..c97715cb 100644--- a/src/McpContext.ts+++ b/src/McpContext.ts@@ -28,6 +28,7 @@ import type {SerializedAXNode,Viewport,Target,+ Extension,} from './third_party/index.js';import type {DevTools} from './third_party/index.js';import {Locator} from './third_party/index.js';@@ -47,10 +48,6 @@ import type {TextSnapshotNode,ExtensionServiceWorker,} from './types.js';-import {- ExtensionRegistry,- type InstalledExtension,-} from './utils/ExtensionRegistry.js';import {ensureExtension, saveTemporaryFile} from './utils/files.js';import {getNetworkMultiplierFromString} from './WaitForHelper.js';@@ -83,7 +80,6 @@ export class McpContext implements Context {#networkCollector: NetworkCollector;#consoleCollector: ConsoleCollector;#devtoolsUniverseManager: UniverseManager;- #extensionRegistry = new ExtensionRegistry();#isRunningTrace = false;#screenRecorderData: {recorder: ScreenRecorder; filePath: string} | null =@@ -882,38 +878,30 @@ export class McpContext implements Context {async installExtension(extensionPath: string): Promise<string> {const id = await this.browser.installExtension(extensionPath);- await this.#extensionRegistry.registerExtension(id, extensionPath);return id;}async uninstallExtension(id: string): Promise<void> {await this.browser.uninstallExtension(id);- this.#extensionRegistry.remove(id);}async triggerExtensionAction(id: string): Promise<void> {- const page = this.getSelectedPptrPage();- // @ts-expect-error internal puppeteer api is needed since we don't have a way to get- // a tab id at the moment- const theTarget = page._tabId;- const session = await this.browser.target().createCDPSession();-- try {- await session.send('Extensions.triggerAction', {- id,- targetId: theTarget,- });- } finally {- await session.detach();+ const extensions = await this.browser.extensions();+ const extension = extensions.get(id);+ if (!extension) {+ throw new Error(`Extension with ID ${id} not found.`);}+ const page = this.getSelectedPptrPage();+ await extension.triggerAction(page);}- listExtensions(): InstalledExtension[] {- return this.#extensionRegistry.list();+ listExtensions(): Promise<Map<string, Extension>> {+ return this.browser.extensions();}- getExtension(id: string): InstalledExtension | undefined {- return this.#extensionRegistry.getById(id);+ async getExtension(id: string): Promise<Extension | undefined> {+ const pptrExtensions = await this.browser.extensions();+ return pptrExtensions.get(id);}async getHeapSnapshotAggregates(diff --git a/src/McpResponse.ts b/src/McpResponse.tsindex c6e47908..0d5f926e 100644--- a/src/McpResponse.ts+++ b/src/McpResponse.ts@@ -23,6 +23,7 @@ import type {ResourceType,TextContent,JSONSchema7Definition,+ Extension,} from './third_party/index.js';import type {ToolGroup, ToolDefinition} from './tools/inPage.js';import {handleDialog} from './tools/pages.js';@@ -35,7 +36,6 @@ import type {} from './tools/ToolDefinition.js';import type {InsightName, TraceResult} from './trace-processing/parse.js';import {getInsightOutput, getTraceSummary} from './trace-processing/parse.js';-import type {InstalledExtension} from './utils/ExtensionRegistry.js';import {paginate} from './utils/pagination.js';import type {PaginationOptions} from './utils/types.js';@@ -527,9 +527,9 @@ export class McpResponse implements Response {}}- let extensions: InstalledExtension[] | undefined;+ let extensions: Map<string, Extension> | undefined;if (this.#listExtensions) {- extensions = context.listExtensions();+ extensions = await context.listExtensions();}let inPageTools: ToolGroup<ToolDefinition> | undefined;@@ -665,7 +665,7 @@ export class McpResponse implements Response {networkRequests?: NetworkFormatter[];traceSummary?: TraceResult;traceInsight?: TraceInsightData;- extensions?: InstalledExtension[];+ extensions?: Map<string, Extension>;lighthouseResult?: LighthouseData;inPageTools?: ToolGroup<ToolDefinition>;webmcpTools?: WebMCPTool[];@@ -947,14 +947,15 @@ Call ${handleDialog.name} to handle it before continuing.`);}if (data.extensions) {- structuredContent.extensions = data.extensions;+ const extensionArray = Array.from(data.extensions.values());+ structuredContent.extensions = extensionArray;response.push('## Extensions');- if (data.extensions.length === 0) {+ if (extensionArray.length === 0) {response.push('No extensions installed.');} else {- const extensionsMessage = data.extensions+ const extensionsMessage = extensionArray.map(extension => {- return `id=${extension.id} "${extension.name}" v${extension.version} ${extension.isEnabled ? 'Enabled' : 'Disabled'}`;+ return `id=${extension.id} "${extension.name}" v${extension.version} ${extension.enabled ? 'Enabled' : 'Disabled'}`;}).join('\n');response.push(extensionsMessage);diff --git a/src/tools/ToolDefinition.ts b/src/tools/ToolDefinition.tsindex b9b4a6af..1cf84b63 100644--- a/src/tools/ToolDefinition.ts+++ b/src/tools/ToolDefinition.ts@@ -10,6 +10,7 @@ import {zod} from '../third_party/index.js';import type {Dialog,ElementHandle,+ Extension,Page,ScreenRecorder,Viewport,@@ -21,7 +22,6 @@ import type {GeolocationOptions,ExtensionServiceWorker,} from '../types.js';-import type {InstalledExtension} from '../utils/ExtensionRegistry.js';import type {PaginationOptions} from '../utils/types.js';import type {ToolCategory} from './categories.js';@@ -218,8 +218,8 @@ export type Context = Readonly<{installExtension(path: string): Promise<string>;uninstallExtension(id: string): Promise<void>;triggerExtensionAction(id: string): Promise<void>;- listExtensions(): InstalledExtension[];- getExtension(id: string): InstalledExtension | undefined;+ listExtensions(): Promise<Map<string, Extension>>;+ getExtension(id: string): Promise<Extension | undefined>;getSelectedMcpPage(): McpPage;getExtensionServiceWorkers(): ExtensionServiceWorker[];getExtensionServiceWorkerId(diff --git a/src/tools/extensions.ts b/src/tools/extensions.tsindex 76cec7fb..d5d2f255 100644--- a/src/tools/extensions.ts+++ b/src/tools/extensions.ts@@ -77,7 +77,7 @@ export const reloadExtension = defineTool({},handler: async (request, response, context) => {const {id} = request.params;- const extension = context.getExtension(id);+ const extension = await context.getExtension(id);if (!extension) {throw new Error(`Extension with ID ${id} not found.`);}diff --git a/src/utils/ExtensionRegistry.ts b/src/utils/ExtensionRegistry.tsdeleted file mode 100644index e652d64f..00000000--- a/src/utils/ExtensionRegistry.ts+++ /dev/null@@ -1,53 +0,0 @@-/**- * @license- * Copyright 2026 Google LLC- * SPDX-License-Identifier: Apache-2.0- */--import fs from 'node:fs/promises';-import path from 'node:path';--export interface InstalledExtension {- id: string;- name: string;- version: string;- isEnabled: boolean;- path: string;-}--export class ExtensionRegistry {- #extensions = new Map<string, InstalledExtension>();-- async registerExtension(- id: string,- extensionPath: string,- ): Promise<InstalledExtension> {- const manifestPath = path.join(extensionPath, 'manifest.json');- const manifestContent = await fs.readFile(manifestPath, 'utf-8');- const manifest = JSON.parse(manifestContent);- const name = manifest.name ?? 'Unknown';- const version = manifest.version ?? 'Unknown';-- const extension = {- id,- name,- version,- isEnabled: true,- path: extensionPath,- };- this.#extensions.set(extension.id, extension);- return extension;- }-- remove(id: string): void {- this.#extensions.delete(id);- }-- list(): InstalledExtension[] {- return Array.from(this.#extensions.values());- }-- getById(id: string): InstalledExtension | undefined {- return this.#extensions.get(id);- }-}diff --git a/tests/McpResponse.test.js.snapshot b/tests/McpResponse.test.js.snapshotindex 641187d2..11a7be78 100644--- a/tests/McpResponse.test.js.snapshot+++ b/tests/McpResponse.test.js.snapshot@@ -1192,14 +1192,14 @@ exports[`extensions > lists extensions 2`] = `"id": "id1","name": "Extension 1","version": "1.0",- "isEnabled": true,+ "enabled": true,"path": "/path/to/ext1"},{"id": "id2","name": "Extension 2","version": "2.0",- "isEnabled": false,+ "enabled": false,"path": "/path/to/ext2"}]diff --git a/tests/McpResponse.test.ts b/tests/McpResponse.test.tsindex 30ba25d8..d49d9405 100644--- a/tests/McpResponse.test.ts+++ b/tests/McpResponse.test.ts@@ -16,7 +16,10 @@ import type {ParsedArguments} from '../src/bin/chrome-devtools-mcp-cli-options.jimport type {McpContext} from '../src/McpContext.js';import type {McpResponse} from '../src/McpResponse.js';import {replaceHtmlElementsWithUids} from '../src/McpResponse.js';-import type {JSONSchema7Definition} from '../src/third_party/index.js';+import type {+ Extension,+ JSONSchema7Definition,+} from '../src/third_party/index.js';import {closePage,listPages,@@ -955,22 +958,31 @@ describe('extensions', () => {response.resetResponseLineForTesting();// Testing with extensions- context.listExtensions = () => [- {- id: 'id1',- name: 'Extension 1',- version: '1.0',- isEnabled: true,- path: '/path/to/ext1',- },- {- id: 'id2',- name: 'Extension 2',- version: '2.0',- isEnabled: false,- path: '/path/to/ext2',- },- ];+ context.listExtensions = async () =>+ Promise.resolve(+ new Map<string, Extension>([+ [+ 'id1',+ {+ id: 'id1',+ name: 'Extension 1',+ version: '1.0',+ enabled: true,+ path: '/path/to/ext1',+ } as Extension,+ ],+ [+ 'id2',+ {+ id: 'id2',+ name: 'Extension 2',+ version: '2.0',+ enabled: false,+ path: '/path/to/ext2',+ } as Extension,+ ],+ ]),+ );response.setListExtensions();const {content, structuredContent} = await response.handle('test',diff --git a/tests/tools/extensions.test.ts b/tests/tools/extensions.test.tsindex 8f8b5a87..c7374ea2 100644--- a/tests/tools/extensions.test.ts+++ b/tests/tools/extensions.test.ts@@ -18,7 +18,11 @@ import {reloadExtension,triggerExtensionAction,} from '../../src/tools/extensions.js';-import {extractExtensionId, withMcpContext} from '../utils.js';+import {+ assertNoServiceWorkerReported,+ extractExtensionId,+ withMcpContext,+} from '../utils.js';const EXTENSION_WITH_SW_PATH = path.join(import.meta.dirname,@@ -91,38 +95,45 @@ describe('extension', () => {});});it('reloads an extension', async () => {- await withMcpContext(async (response, context) => {- await installExtension.handler(- {params: {path: EXTENSION_PATH}},- response,- context,- );+ await withMcpContext(+ async (response, context) => {+ await installExtension.handler(+ {params: {path: EXTENSION_PATH}},+ response,+ context,+ );- const extensionId = extractExtensionId(response);- const installSpy = sinon.spy(context, 'installExtension');- response.resetResponseLineForTesting();+ const extensionId = extractExtensionId(response);+ const installSpy = sinon.spy(context, 'installExtension');+ response.resetResponseLineForTesting();- await reloadExtension.handler(- {params: {id: extensionId!}},- response,- context,- );- assert.ok(- installSpy.calledOnceWithExactly(EXTENSION_PATH),- 'installExtension should be called with the extension path',- );+ await reloadExtension.handler(+ {params: {id: extensionId!}},+ response,+ context,+ );+ assert.ok(+ installSpy.calledOnceWithExactly(EXTENSION_PATH),+ 'installExtension should be called with the extension path',+ );- const reloadResponseLine = response.responseLines[0];- assert.ok(- reloadResponseLine.includes('Extension reloaded'),- 'Response should indicate reload',- );+ const reloadResponseLine = response.responseLines[0];+ assert.ok(+ reloadResponseLine.includes('Extension reloaded'),+ 'Response should indicate reload',+ );- const list = context.listExtensions();- assert.ok(list.length === 1, 'List should have only one extension');- const reinstalled = list.find(e => e.id === extensionId);- assert.ok(reinstalled, 'Extension should be present after reload');- });+ const list = Array.from((await context.listExtensions()).values());++ assert.ok(list.length === 1, 'List should have only one extension');+ const reinstalled = list.find(e => e.id === extensionId);+ assert.ok(reinstalled, 'Extension should be present after reload');+ },+ {},+ {+ categoryExtensions: true,+ } as ParsedArguments,+ );});it('triggers an extension action', async () => {await withMcpContext(@@ -147,10 +158,11 @@ describe('extension', () => {t => t.type() === 'page' && t.url().includes(extensionId),);assert.ok(pageTargetAfter, 'Page should exist after action');+ await context.uninstallExtension(extensionId);+ const targets = context.browser.targets();+ assertNoServiceWorkerReported(targets, extensionId);},- {- executablePath: process.env.CHROME_M146_EXECUTABLE_PATH,- },+ {},{categoryExtensions: true,} as ParsedArguments,diff --git a/tests/tools/pages.test.ts b/tests/tools/pages.test.tsindex 3fb5892b..1617f9f6 100644--- a/tests/tools/pages.test.ts+++ b/tests/tools/pages.test.ts@@ -22,7 +22,7 @@ import {handleDialog,getTabId,} from '../../src/tools/pages.js';-import {html, withMcpContext} from '../utils.js';+import {assertNoServiceWorkerReported, html, withMcpContext} from '../utils.js';const EXTENSION_SW_PATH = path.join(import.meta.dirname,@@ -94,10 +94,9 @@ describe('pages', () => {'<extension-id>',);t.assert.snapshot?.(text);+ await context.uninstallExtension(extensionId);},- {- executablePath: process.env.CHROME_M146_EXECUTABLE_PATH,- },+ {},{categoryExtensions: true,} as ParsedArguments,@@ -146,6 +145,9 @@ describe('pages', () => {'<extension-id>',);t.assert.snapshot?.(text);+ await context.uninstallExtension(extensionId);+ const targets = context.browser.targets();+ assertNoServiceWorkerReported(targets, extensionId);},{},{@@ -193,10 +195,11 @@ describe('pages', () => {'<extension-id>',);t.assert.snapshot?.(text);+ await context.uninstallExtension(extensionId);+ const targets = context.browser.targets();+ assertNoServiceWorkerReported(targets, extensionId);},- {- executablePath: process.env.CHROME_M146_EXECUTABLE_PATH,- },+ {},{categoryExtensions: true,} as ParsedArguments,diff --git a/tests/tools/script.test.ts b/tests/tools/script.test.tsindex 5057f8a0..b0d57678 100644--- a/tests/tools/script.test.ts+++ b/tests/tools/script.test.ts@@ -12,7 +12,12 @@ import type {ParsedArguments} from '../../src/bin/chrome-devtools-mcp-cli-optionimport {installExtension} from '../../src/tools/extensions.js';import {evaluateScript} from '../../src/tools/script.js';import {serverHooks} from '../server.js';-import {extractExtensionId, html, withMcpContext} from '../utils.js';+import {+ assertNoServiceWorkerReported,+ extractExtensionId,+ html,+ withMcpContext,+} from '../utils.js';const EXTENSION_PATH = path.join(import.meta.dirname,@@ -309,6 +314,9 @@ describe('script', () => {const lineEvaluation = response.responseLines.at(2)!;assert.strictEqual(JSON.parse(lineEvaluation), 'has-chrome');+ await context.uninstallExtension(extensionId);+ const targets = context.browser.targets();+ assertNoServiceWorkerReported(targets, extensionId);},{},{categoryExtensions: true} as ParsedArguments,diff --git a/tests/utils.ts b/tests/utils.tsindex 6d4668fb..6afa521d 100644--- a/tests/utils.ts+++ b/tests/utils.ts@@ -18,6 +18,7 @@ import type {HTTPResponse,LaunchOptions,Page,+ Target,} from 'puppeteer-core';import sinon from 'sinon';@@ -27,6 +28,13 @@ import {McpResponse} from '../src/McpResponse.js';import {stableIdSymbol} from '../src/PageCollector.js';import {DevTools} from '../src/third_party/index.js';+export function assertNoServiceWorkerReported(targets: Target[], id: string) {+ const target = targets.find(target => {+ return target.url().includes(id) && target.type() === 'service_worker';+ });+ assert(target === undefined);+}+export function getTextContent(content: CallToolResult['content'][number],): string {