Chrome DevTools for coding agents
feat: allow evaluate_script to skip the stable DOM wait (#2346)
Thomas Bachem781e2fb98c65
diff --git a/docs/tool-reference.md b/docs/tool-reference.mdindex 5c5a7398..7bfc30bc 100644--- a/docs/tool-reference.md+++ b/docs/tool-reference.md@@ -359,6 +359,7 @@- **args** (array) _(optional)_: An optional list of arguments to pass to the function.- **dialogAction** (string) _(optional)_: Handle dialogs while execution. "accept", "dismiss", or string for response of window.prompt. Defaults to accept.- **filePath** (string) _(optional)_: The absolute or relative path to a file to save the script output to. If omitted, the output is returned inline.+- **waitForStableDom** (boolean) _(optional)_: Whether to wait for the DOM to settle. Pass false if the script only reads data. Defaults to true.---diff --git a/src/McpPage.ts b/src/McpPage.tsindex 7695ff6a..095a6dbd 100644--- a/src/McpPage.ts+++ b/src/McpPage.ts@@ -417,6 +417,7 @@ export class McpPage implements ContextPage {action: () => Promise<unknown>,options?: {timeout?: number;+ waitForStableDom?: boolean;handleDialog?:DialogAction | Partial<Record<Protocol.Page.DialogType, DialogAction>>;},diff --git a/src/WaitForHelper.ts b/src/WaitForHelper.tsindex 7724b358..d06481d6 100644--- a/src/WaitForHelper.ts+++ b/src/WaitForHelper.ts@@ -145,6 +145,7 @@ export class WaitForHelper {action: () => Promise<unknown>,options?: {timeout?: number;+ waitForStableDom?: boolean;handleDialog?:DialogAction | Partial<Record<Protocol.Page.DialogType, DialogAction>>;},@@ -214,7 +215,9 @@ export class WaitForHelper {// Wait for stable dom after navigation so we execute in// the correct context- await this.waitForStableDom();+ if (options?.waitForStableDom !== false) {+ await this.waitForStableDom();+ }} catch (error) {logger?.(error);} finally {diff --git a/src/bin/chrome-devtools-cli-options.ts b/src/bin/chrome-devtools-cli-options.tsindex 4e01c776..d36252f2 100644--- a/src/bin/chrome-devtools-cli-options.ts+++ b/src/bin/chrome-devtools-cli-options.ts@@ -249,6 +249,13 @@ export const commands: Commands = {'Handle dialogs while execution. "accept", "dismiss", or string for response of window.prompt. Defaults to accept.',required: false,},+ waitForStableDom: {+ name: 'waitForStableDom',+ type: 'boolean',+ description:+ 'Whether to wait for the DOM to settle. Pass false if the script only reads data. Defaults to true.',+ required: false,+ },},},execute_3p_developer_tool: {diff --git a/src/telemetry/tool_call_metrics.json b/src/telemetry/tool_call_metrics.jsonindex 55675e14..f4fecd69 100644--- a/src/telemetry/tool_call_metrics.json+++ b/src/telemetry/tool_call_metrics.json@@ -119,6 +119,10 @@{"name": "file_path_length","argType": "number"+ },+ {+ "name": "wait_for_stable_dom",+ "argType": "boolean"}]},diff --git a/src/tools/ToolDefinition.ts b/src/tools/ToolDefinition.tsindex 52d34d6f..d35c6420 100644--- a/src/tools/ToolDefinition.ts+++ b/src/tools/ToolDefinition.ts@@ -315,6 +315,7 @@ export type ContextPage = Readonly<{action: () => Promise<unknown>,options?: {timeout?: number;+ waitForStableDom?: boolean;handleDialog?:DialogAction | Partial<Record<Protocol.Page.DialogType, DialogAction>>;},diff --git a/src/tools/script.ts b/src/tools/script.tsindex 8e58b3a1..ce1f806a 100644--- a/src/tools/script.ts+++ b/src/tools/script.ts@@ -52,6 +52,12 @@ Example with arguments: \`(el) => el.innerText\`.describe('Handle dialogs while execution. "accept", "dismiss", or string for response of window.prompt. Defaults to accept.',),+ waitForStableDom: zod+ .boolean()+ .optional()+ .describe(+ 'Whether to wait for the DOM to settle. Pass false if the script only reads data. Defaults to true.',+ ),...(cliArgs?.categoryExtensions? {serviceWorkerId: zod@@ -73,6 +79,7 @@ Example with arguments: \`(el) => el.innerText\`pageId,dialogAction,filePath,+ waitForStableDom,} = request.params;if (cliArgs?.categoryExtensions && serviceWorkerId) {@@ -95,7 +102,8 @@ Example with arguments: \`(el) => el.innerText\`context,});},- {handleDialog: dialogAction ?? 'accept'},+ // Service workers cannot interact with the DOM, so never wait for it.+ {handleDialog: dialogAction ?? 'accept', waitForStableDom: false},);if (result.dialogHandled) {context.getSelectedMcpPage().clearDialog();@@ -129,7 +137,7 @@ Example with arguments: \`(el) => el.innerText\`context,});},- {handleDialog: dialogAction ?? 'accept'},+ {handleDialog: dialogAction ?? 'accept', waitForStableDom},);response.attachWaitForResult(result);},diff --git a/tests/tools/script.test.ts b/tests/tools/script.test.tsindex c2883ab7..c590cca7 100644--- a/tests/tools/script.test.ts+++ b/tests/tools/script.test.ts@@ -8,14 +8,18 @@ import assert from 'node:assert';import path from 'node:path';import {describe, it} from 'node:test';+import sinon from 'sinon';+import type {ParsedArguments} from '../../src/bin/chrome-devtools-mcp-cli-options.js';import {TextSnapshot} from '../../src/TextSnapshot.js';import {installExtension} from '../../src/tools/extensions.js';import {evaluateScript} from '../../src/tools/script.js';+import {WaitForHelper} from '../../src/WaitForHelper.js';import {serverHooks} from '../server.js';import {assertNoServiceWorkerReported,extractExtensionId,+ getTextContent,html,withMcpContext,} from '../utils.js';@@ -42,6 +46,56 @@ describe('script', () => {assert.strictEqual(JSON.parse(lineEvaluation), 10);});});+ it('skips the stable DOM wait when waitForStableDom is false', async () => {+ await withMcpContext(async (response, context) => {+ const spy = sinon.spy(WaitForHelper.prototype, 'waitForStableDom');+ try {+ await evaluateScript().handler(+ {+ params: {function: String(() => 1), waitForStableDom: false},+ },+ response,+ context,+ );+ sinon.assert.notCalled(spy);++ await evaluateScript().handler(+ {+ params: {function: String(() => 1)},+ },+ response,+ context,+ );+ sinon.assert.calledOnce(spy);+ } finally {+ spy.restore();+ }+ });+ });+ it('still awaits a navigation when waitForStableDom is false', async () => {+ await withMcpContext(async (response, context) => {+ server.addHtmlRoute('/nav-target', html`<main>navigated</main>`);+ const url = server.getRoute('/nav-target');+ await evaluateScript().handler(+ {+ params: {+ function: `() => {+ location.href = '${url}';+ }`,+ waitForStableDom: false,+ },+ },+ response,+ context,+ );+ const result = await response.handle(context);+ const textContent = getTextContent(result.content[0]);+ assert.ok(+ textContent.includes(`Page navigated to ${url}`),+ `Expected the navigation to be awaited and reported, got: ${textContent}`,+ );+ });+ });it('runs in selected page', async () => {await withMcpContext(async (response, context) => {await evaluateScript().handler(