Skip to content

Chrome DevTools for coding agents

chore: evaluate script on service workers (#1052)

Nicholas Roscino505089c28844
diff --git a/src/McpContext.ts b/src/McpContext.ts
index 7e6aa23d..0d8b6d76 100644
--- a/src/McpContext.ts
+++ b/src/McpContext.ts
@@ -41,6 +41,7 @@ import type {
GeolocationOptions,
TextSnapshot,
TextSnapshotNode,
+ ExtensionServiceWorker,
} from './types.js';
import {
ExtensionRegistry,
@@ -55,12 +56,6 @@ export type {
TextSnapshotNode,
} from './types.js';
-export interface ExtensionServiceWorker {
- url: string;
- target: Target;
- id: string;
-}
-
interface McpContextOptions {
// Whether the DevTools windows are exposed as pages for debugging of DevTools.
experimentalDevToolsDebugging: boolean;
diff --git a/src/tools/ToolDefinition.ts b/src/tools/ToolDefinition.ts
index da308570..543b202d 100644
--- a/src/tools/ToolDefinition.ts
+++ b/src/tools/ToolDefinition.ts
@@ -5,6 +5,7 @@
*/
import type {ParsedArguments} from '../cli.js';
+import type {McpPage} from '../McpPage.js';
import {zod} from '../third_party/index.js';
import type {
Dialog,
@@ -14,7 +15,11 @@ import type {
Viewport,
} from '../third_party/index.js';
import type {InsightName, TraceResult} from '../trace-processing/parse.js';
-import type {TextSnapshotNode, GeolocationOptions} from '../types.js';
+import type {
+ TextSnapshotNode,
+ GeolocationOptions,
+ ExtensionServiceWorker,
+} from '../types.js';
import type {InstalledExtension} from '../utils/ExtensionRegistry.js';
import type {PaginationOptions} from '../utils/types.js';
@@ -187,6 +192,11 @@ export type Context = Readonly<{
uninstallExtension(id: string): Promise<void>;
listExtensions(): InstalledExtension[];
getExtension(id: string): InstalledExtension | undefined;
+ getSelectedMcpPage(): McpPage;
+ getExtensionServiceWorkers(): ExtensionServiceWorker[];
+ getExtensionServiceWorkerId(
+ extensionServiceWorker: ExtensionServiceWorker,
+ ): string | undefined;
}>;
export type ContextPage = Readonly<{
diff --git a/src/tools/script.ts b/src/tools/script.ts
index d7352b79..fa2d18c1 100644
--- a/src/tools/script.ts
+++ b/src/tools/script.ts
@@ -5,22 +5,27 @@
*/
import {zod} from '../third_party/index.js';
-import type {Frame, JSHandle, Page} from '../third_party/index.js';
+import type {Frame, JSHandle, Page, WebWorker} from '../third_party/index.js';
+import type {ExtensionServiceWorker} from '../types.js';
import {ToolCategory} from './categories.js';
-import {definePageTool} from './ToolDefinition.js';
+import type {Context, Response} from './ToolDefinition.js';
+import {defineTool, pageIdSchema} from './ToolDefinition.js';
-export const evaluateScript = definePageTool({
- name: 'evaluate_script',
- description: `Evaluate a JavaScript function inside the currently selected page. Returns the response as JSON,
+export type Evaluatable = Page | Frame | WebWorker;
+
+export const evaluateScript = defineTool(cliArgs => {
+ return {
+ name: 'evaluate_script',
+ description: `Evaluate a JavaScript function inside the currently selected page. Returns the response as JSON,
so returned values have to be JSON-serializable.`,
- annotations: {
- category: ToolCategory.DEBUGGING,
- readOnlyHint: false,
- },
- schema: {
- function: zod.string().describe(
- `A JavaScript function declaration to be executed by the tool in the currently selected page.
+ annotations: {
+ category: ToolCategory.DEBUGGING,
+ readOnlyHint: false,
+ },
+ schema: {
+ function: zod.string().describe(
+ `A JavaScript function declaration to be executed by the tool in the currently selected page.
Example without arguments: \`() => {
return document.title
}\` or \`async () => {
@@ -30,57 +35,143 @@ Example with arguments: \`(el) => {
return el.innerText;
}\`
`,
- ),
- args: zod
- .array(
- zod.object({
- uid: zod
- .string()
- .describe(
- 'The uid of an element on the page from the page content snapshot',
- ),
- }),
- )
- .optional()
- .describe(`An optional list of arguments to pass to the function.`),
- },
- handler: async (request, response, context) => {
- const args: Array<JSHandle<unknown>> = [];
- try {
- const frames = new Set<Frame>();
- for (const el of request.params.args ?? []) {
- const handle = await request.page.getElementByUid(el.uid);
- frames.add(handle.frame);
- args.push(handle);
+ ),
+ args: zod
+ .array(
+ zod.object({
+ uid: zod
+ .string()
+ .describe(
+ 'The uid of an element on the page from the page content snapshot',
+ ),
+ }),
+ )
+ .optional()
+ .describe(`An optional list of arguments to pass to the function.`),
+ ...(cliArgs?.experimentalPageIdRouting ? pageIdSchema : {}),
+ ...(cliArgs?.categoryExtensions
+ ? {
+ serviceWorkerId: zod
+ .string()
+ .optional()
+ .describe(
+ `An optional service worker id to evaluate the script in.`,
+ ),
+ }
+ : {}),
+ },
+ handler: async (request, response, context) => {
+ const {
+ serviceWorkerId,
+ args: uidArgs,
+ function: fnString,
+ pageId,
+ } = request.params;
+
+ if (cliArgs?.categoryExtensions && serviceWorkerId) {
+ if (uidArgs && uidArgs.length > 0) {
+ throw new Error(
+ 'args (element uids) cannot be used when evaluating in a service worker.',
+ );
+ }
+ if (pageId) {
+ throw new Error('specify either a pageId or a serviceWorkerId.');
+ }
+
+ const worker = await getWebWorker(context, serviceWorkerId);
+ await performEvaluation(worker, fnString, [], response, context);
+ return;
}
- let pageOrFrame: Page | Frame;
- // We can't evaluate the element handle across frames
- if (frames.size > 1) {
- throw new Error(
- "Elements from different frames can't be evaluated together.",
- );
- } else {
- pageOrFrame = [...frames.values()][0] ?? request.page.pptrPage;
+
+ const mcpPage = cliArgs?.experimentalPageIdRouting
+ ? context.getPageById(request.params.pageId)
+ : context.getSelectedMcpPage();
+ const page: Page = mcpPage.pptrPage;
+
+ const args: Array<JSHandle<unknown>> = [];
+ try {
+ const frames = new Set<Frame>();
+ for (const el of uidArgs ?? []) {
+ const handle = await mcpPage.getElementByUid(el.uid);
+ frames.add(handle.frame);
+ args.push(handle);
+ }
+
+ const evaluatable = await getPageOrFrame(page, frames);
+
+ await performEvaluation(evaluatable, fnString, args, response, context);
+ } finally {
+ void Promise.allSettled(args.map(arg => arg.dispose()));
}
- const fn = await pageOrFrame.evaluateHandle(
- `(${request.params.function})`,
+ },
+ };
+});
+
+const performEvaluation = async (
+ evaluatable: Evaluatable,
+ fnString: string,
+ args: Array<JSHandle<unknown>>,
+ response: Response,
+ context: Context,
+) => {
+ const fn = await evaluatable.evaluateHandle(`(${fnString})`);
+ try {
+ await context.waitForEventsAfterAction(async () => {
+ const result = await evaluatable.evaluate(
+ async (fn, ...args) => {
+ // @ts-expect-error no types for function fn
+ return JSON.stringify(await fn(...args));
+ },
+ fn,
+ ...args,
);
- args.unshift(fn);
- await context.waitForEventsAfterAction(async () => {
- const result = await pageOrFrame.evaluate(
- async (fn, ...args) => {
- // @ts-expect-error no types.
- return JSON.stringify(await fn(...args));
- },
- ...args,
- );
- response.appendResponseLine('Script ran on page and returned:');
- response.appendResponseLine('```json');
- response.appendResponseLine(`${result}`);
- response.appendResponseLine('```');
- });
- } finally {
- void Promise.allSettled(args.map(arg => arg.dispose()));
+ response.appendResponseLine('Script ran on page and returned:');
+ response.appendResponseLine('```json');
+ response.appendResponseLine(`${result}`);
+ response.appendResponseLine('```');
+ });
+ } finally {
+ void fn.dispose();
+ }
+};
+
+const getPageOrFrame = async (
+ page: Page,
+ frames: Set<Frame>,
+): Promise<Page | Frame> => {
+ let pageOrFrame: Page | Frame;
+ // We can't evaluate the element handle across frames
+ if (frames.size > 1) {
+ throw new Error(
+ "Elements from different frames can't be evaluated together.",
+ );
+ } else {
+ pageOrFrame = [...frames.values()][0] ?? page;
+ }
+
+ return pageOrFrame;
+};
+
+const getWebWorker = async (
+ context: Context,
+ serviceWorkerId: string,
+): Promise<WebWorker> => {
+ const serviceWorkers = context.getExtensionServiceWorkers();
+
+ const serviceWorker = serviceWorkers.find(
+ (sw: ExtensionServiceWorker) =>
+ context.getExtensionServiceWorkerId(sw) === serviceWorkerId,
+ );
+
+ if (serviceWorker && serviceWorker.target) {
+ const worker = await serviceWorker.target.worker();
+
+ if (!worker) {
+ throw new Error('Service worker target not found.');
}
- },
-});
+
+ return worker;
+ } else {
+ throw new Error('Service worker not found.');
+ }
+};
diff --git a/src/tools/tools.ts b/src/tools/tools.ts
index 27d20ced..4672516b 100644
--- a/src/tools/tools.ts
+++ b/src/tools/tools.ts
@@ -44,7 +44,7 @@ export const createTools = (args: ParsedArguments) => {
const tools = [];
for (const tool of rawTools) {
if (typeof tool === 'function') {
- tools.push(tool(args));
+ tools.push(tool(args) as unknown as ToolDefinition);
} else {
tools.push(tool as ToolDefinition);
}
diff --git a/src/types.ts b/src/types.ts
index 69dddd2a..a85796ed 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -4,7 +4,13 @@
* SPDX-License-Identifier: Apache-2.0
*/
-import type {SerializedAXNode, Viewport} from './third_party/index.js';
+import type {SerializedAXNode, Viewport, Target} from './third_party/index.js';
+
+export interface ExtensionServiceWorker {
+ url: string;
+ target: Target;
+ id: string;
+}
export interface TextSnapshotNode extends SerializedAXNode {
id: string;
diff --git a/tests/tools/extensions.test.ts b/tests/tools/extensions.test.ts
index 2fbf62a0..58fa0a40 100644
--- a/tests/tools/extensions.test.ts
+++ b/tests/tools/extensions.test.ts
@@ -24,7 +24,7 @@ const EXTENSION_PATH = path.join(
'../../../tests/tools/fixtures/extension',
);
-function extractId(response: McpResponse) {
+export function extractId(response: McpResponse) {
const responseLine = response.responseLines[0];
assert.ok(responseLine, 'Response should not be empty');
const match = responseLine.match(/Extension installed\. Id: (.+)/);
diff --git a/tests/tools/script.test.ts b/tests/tools/script.test.ts
index 1ddaea4c..78736726 100644
--- a/tests/tools/script.test.ts
+++ b/tests/tools/script.test.ts
@@ -5,22 +5,31 @@
*/
import assert from 'node:assert';
+import path from 'node:path';
import {describe, it} from 'node:test';
+import type {ParsedArguments} from '../../src/cli.js';
+import {installExtension} from '../../src/tools/extensions.js';
import {evaluateScript} from '../../src/tools/script.js';
import {serverHooks} from '../server.js';
import {html, withMcpContext} from '../utils.js';
+import {extractId} from './extensions.test.js';
+
+const EXTENSION_PATH = path.join(
+ import.meta.dirname,
+ '../../../tests/tools/fixtures/extension-sw',
+);
+
describe('script', () => {
const server = serverHooks();
describe('browser_evaluate_script', () => {
it('evaluates', async () => {
await withMcpContext(async (response, context) => {
- await evaluateScript.handler(
+ await evaluateScript().handler(
{
params: {function: String(() => 2 * 5)},
- page: context.getSelectedMcpPage(),
},
response,
context,
@@ -31,10 +40,9 @@ describe('script', () => {
});
it('runs in selected page', async () => {
await withMcpContext(async (response, context) => {
- await evaluateScript.handler(
+ await evaluateScript().handler(
{
params: {function: String(() => document.title)},
- page: context.getSelectedMcpPage(),
},
response,
context,
@@ -51,10 +59,9 @@ describe('script', () => {
`);
response.resetResponseLineForTesting();
- await evaluateScript.handler(
+ await evaluateScript().handler(
{
params: {function: String(() => document.title)},
- page: context.getSelectedMcpPage(),
},
response,
context,
@@ -71,7 +78,7 @@ describe('script', () => {
await page.setContent(html`<script src="./scripts.js"></script> `);
- await evaluateScript.handler(
+ await evaluateScript().handler(
{
params: {
function: String(() => {
@@ -82,7 +89,6 @@ describe('script', () => {
return {scripts};
}),
},
- page: context.getSelectedMcpPage(),
},
response,
context,
@@ -100,7 +106,7 @@ describe('script', () => {
await page.setContent(html`<script src="./scripts.js"></script> `);
- await evaluateScript.handler(
+ await evaluateScript().handler(
{
params: {
function: String(async () => {
@@ -108,7 +114,6 @@ describe('script', () => {
return 'Works';
}),
},
- page: context.getSelectedMcpPage(),
},
response,
context,
@@ -126,7 +131,7 @@ describe('script', () => {
await context.createTextSnapshot(context.getSelectedMcpPage());
- await evaluateScript.handler(
+ await evaluateScript().handler(
{
params: {
function: String(async (el: Element) => {
@@ -134,7 +139,6 @@ describe('script', () => {
}),
args: [{uid: '1_1'}],
},
- page: context.getSelectedMcpPage(),
},
response,
context,
@@ -152,7 +156,7 @@ describe('script', () => {
await context.createTextSnapshot(context.getSelectedMcpPage());
- await evaluateScript.handler(
+ await evaluateScript().handler(
{
params: {
function: String((container: Element, child: Element) => {
@@ -160,7 +164,6 @@ describe('script', () => {
}),
args: [{uid: '1_0'}, {uid: '1_1'}],
},
- page: context.getSelectedMcpPage(),
},
response,
context,
@@ -181,7 +184,7 @@ describe('script', () => {
const page = context.getSelectedPptrPage();
await page.goto(server.getRoute('/main'));
await context.createTextSnapshot(context.getSelectedMcpPage());
- await evaluateScript.handler(
+ await evaluateScript().handler(
{
params: {
function: String((element: Element) => {
@@ -189,7 +192,6 @@ describe('script', () => {
}),
args: [{uid: '1_3'}],
},
- page: context.getSelectedMcpPage(),
},
response,
context,
@@ -198,5 +200,107 @@ describe('script', () => {
assert.strictEqual(JSON.parse(lineEvaluation), 'I am iframe button');
});
});
+ it('evaluates inside extension service worker', async () => {
+ await withMcpContext(
+ async (response, context) => {
+ await installExtension.handler(
+ {params: {path: EXTENSION_PATH}},
+ response,
+ context,
+ );
+
+ const extensionId = extractId(response);
+ const swTarget = await context.browser.waitForTarget(
+ t => t.type() === 'service_worker' && t.url().includes(extensionId),
+ );
+
+ await context.createExtensionServiceWorkersSnapshot();
+ const swList = context.getExtensionServiceWorkers();
+ const sw = swList.find(s => s.target === swTarget);
+
+ if (!sw) {
+ assert.fail('Service worker not found in context list');
+ }
+
+ const swId = context.getExtensionServiceWorkerId(sw);
+
+ response.resetResponseLineForTesting();
+ await evaluateScript({
+ categoryExtensions: true,
+ } as ParsedArguments).handler(
+ {
+ params: {
+ function: String(() => {
+ return 'chrome' in globalThis ? 'has-chrome' : 'no-chrome';
+ }),
+ serviceWorkerId: swId,
+ },
+ },
+ response,
+ context,
+ );
+
+ const lineEvaluation = response.responseLines.at(2)!;
+ assert.strictEqual(JSON.parse(lineEvaluation), 'has-chrome');
+ },
+ {},
+ {categoryExtensions: true} as ParsedArguments,
+ );
+ });
+
+ it('throws error when both pageId and serviceWorkerId are provided', async () => {
+ await withMcpContext(
+ async (response, context) => {
+ await assert.rejects(
+ evaluateScript({
+ categoryExtensions: true,
+ } as ParsedArguments).handler(
+ {
+ params: {
+ function: String(() => 'test'),
+ serviceWorkerId: 'example_service_worker',
+ pageId: '1',
+ },
+ },
+ response,
+ context,
+ ),
+ {
+ message: 'specify either a pageId or a serviceWorkerId.',
+ },
+ );
+ },
+ {},
+ {categoryExtensions: true} as ParsedArguments,
+ );
+ });
+
+ it('throws error when args are provided with serviceWorkerId', async () => {
+ await withMcpContext(
+ async (response, context) => {
+ await assert.rejects(
+ evaluateScript({
+ categoryExtensions: true,
+ } as ParsedArguments).handler(
+ {
+ params: {
+ function: String(() => 'test'),
+ serviceWorkerId: 'example_service_worker',
+ args: [{uid: '1_1'}],
+ },
+ },
+ response,
+ context,
+ ),
+ {
+ message:
+ 'args (element uids) cannot be used when evaluating in a service worker.',
+ },
+ );
+ },
+ {},
+ {categoryExtensions: true} as ParsedArguments,
+ );
+ });
});
});