Skip to content

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.md
index 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.ts
index 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.ts
index 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.ts
index 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.json
index 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.ts
index 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.ts
index 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.ts
index 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(