feat: allow evaluate_script to skip the stable DOM wait

docs/tool-reference.md

@@ -358,6 +358,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 after the script ran. Pass false when the script only reads state and does not change the page, for a faster response. Navigations triggered by the script are still awaited. Defaults to true.
 
 ---
 

src/McpPage.ts

@@ -237,6 +237,7 @@ export class McpPage implements ContextPage {
     action: () => Promise<unknown>,
     options?: {
       timeout?: number;
+      waitForStableDom?: boolean;
       handleDialog?:
         DialogAction | Partial<Record<Protocol.Page.DialogType, DialogAction>>;
     },

src/WaitForHelper.ts

@@ -134,6 +134,7 @@ export class WaitForHelper {
     action: () => Promise<unknown>,
     options?: {
       timeout?: number;
+      waitForStableDom?: boolean;
       handleDialog?:
         DialogAction | Partial<Record<Protocol.Page.DialogType, DialogAction>>;
     },
@@ -199,7 +200,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 {

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 after the script ran. Pass false when the script only reads state and does not change the page, for a faster response. Navigations triggered by the script are still awaited. Defaults to true.',
+        required: false,
+      },
     },
   },
   execute_3p_developer_tool: {

src/telemetry/tool_call_metrics.json

@@ -119,6 +119,10 @@
       {
         "name": "file_path_length",
         "argType": "number"
+      },
+      {
+        "name": "wait_for_stable_dom",
+        "argType": "boolean"
       }
     ]
   },

src/tools/ToolDefinition.ts

@@ -301,6 +301,7 @@ export type ContextPage = Readonly<{
     action: () => Promise<unknown>,
     options?: {
       timeout?: number;
+      waitForStableDom?: boolean;
       handleDialog?:
         DialogAction | Partial<Record<Protocol.Page.DialogType, DialogAction>>;
     },

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 after the script ran. Pass false when the script only reads state and does not change the page, for a faster response. Navigations triggered by the script are still awaited. 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,7 @@ Example with arguments: \`(el) => el.innerText\`
                 context,
               });
             },
-            {handleDialog: dialogAction ?? 'accept'},
+            {handleDialog: dialogAction ?? 'accept', waitForStableDom},
           );
         if (result.dialogHandled) {
           context.getSelectedMcpPage().clearDialog();
@@ -127,7 +134,7 @@ Example with arguments: \`(el) => el.innerText\`
               context,
             });
           },
-          {handleDialog: dialogAction ?? 'accept'},
+          {handleDialog: dialogAction ?? 'accept', waitForStableDom},
         );
         response.attachWaitForResult(result);
       } finally {

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('test', 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(