feat(mcp): make post-action settle delay configurable (#41924)

Author: m4ttheweric

packages/playwright-core/src/tools/backend/context.ts

@@ -56,6 +56,7 @@ export type ContextConfig = {
     action?: number;
     navigation?: number;
     expect?: number;
+    settle?: number;
   };
   browser?: {
     initScript?: string[];

packages/playwright-core/src/tools/backend/utils.ts

@@ -18,6 +18,7 @@ import type * as playwright from '../../..';
 import type { Tab } from './tab';
 
 export async function waitForCompletion<R>(tab: Tab, callback: () => Promise<R>): Promise<R> {
+  const settleMs = tab.context.config.timeouts?.settle ?? 500;
   const requests: playwright.Request[] = [];
 
   const requestListener = (request: playwright.Request) => requests.push(request);
@@ -29,7 +30,7 @@ export async function waitForCompletion<R>(tab: Tab, callback: () => Promise<R>)
   let result: R;
   try {
     result = await callback();
-    await tab.waitForTimeout(500);
+    await tab.waitForTimeout(settleMs);
   } finally {
     disposeListeners();
   }
@@ -50,7 +51,7 @@ export async function waitForCompletion<R>(tab: Tab, callback: () => Promise<R>)
   const timeout = new Promise<void>(resolve => setTimeout(resolve, 5000));
   await Promise.race([Promise.all(promises), timeout]);
   if (requests.length)
-    await tab.waitForTimeout(500);
+    await tab.waitForTimeout(settleMs);
 
   return result;
 }

packages/playwright-core/src/tools/mcp/config.d.ts

@@ -210,6 +210,11 @@ export type Config = {
      * Configures default expect timeout: https://playwright.dev/docs/test-timeouts#expect-timeout. Defaults to 5000ms.
      */
     expect?: number;
+
+    /**
+     * How long to wait after each action for triggered work (navigations, requests) to settle before responding. Defaults to 500ms.
+     */
+    settle?: number;
   };
 
   /**

packages/playwright-core/src/tools/mcp/config.ts

@@ -74,6 +74,7 @@ export type CLIOptions = {
   testIdAttribute?: string;
   timeoutAction?: number;
   timeoutNavigation?: number;
+  timeoutSettle?: number;
   userAgent?: string;
   userDataDir?: string;
   viewportSize?: ViewportSize;
@@ -88,6 +89,7 @@ const defaultConfig: MergedConfig = {
     action: 5000,
     navigation: 60000,
     expect: 5000,
+    settle: 500,
   },
 };
 
@@ -378,6 +380,7 @@ function configFromCLIOptions(cliOptions: CLIOptions): Config & { configFile?: s
     timeouts: {
       action: cliOptions.timeoutAction,
       navigation: cliOptions.timeoutNavigation,
+      settle: cliOptions.timeoutSettle,
     },
   };
 
@@ -434,6 +437,7 @@ export function configFromEnv(env?: NodeJS.ProcessEnv): Config & { configFile?:
   options.testIdAttribute = envToString(e.PLAYWRIGHT_MCP_TEST_ID_ATTRIBUTE);
   options.timeoutAction = numberParser(e.PLAYWRIGHT_MCP_TIMEOUT_ACTION);
   options.timeoutNavigation = numberParser(e.PLAYWRIGHT_MCP_TIMEOUT_NAVIGATION);
+  options.timeoutSettle = numberParser(e.PLAYWRIGHT_MCP_TIMEOUT_SETTLE);
   options.userAgent = envToString(e.PLAYWRIGHT_MCP_USER_AGENT);
   options.userDataDir = envToString(e.PLAYWRIGHT_MCP_USER_DATA_DIR);
   options.viewportSize = resolutionParser('--viewport-size', e.PLAYWRIGHT_MCP_VIEWPORT_SIZE);

packages/playwright-core/src/tools/mcp/configIni.ts

@@ -181,6 +181,7 @@ const longhandTypes: Record<string, LonghandType> = {
   // timeouts
   'timeouts.action': 'number',
   'timeouts.navigation': 'number',
+  'timeouts.settle': 'number',
 
   // snapshot
   'snapshot.mode': 'string',

packages/playwright-core/src/tools/mcp/program.ts

@@ -74,6 +74,7 @@ export function decorateMCPCommand(command: Command) {
       .option('--test-id-attribute <attribute>', 'specify the attribute to use for test ids, defaults to "data-testid"')
       .option('--timeout-action <timeout>', 'specify action timeout in milliseconds, defaults to 5000ms', numberParser)
       .option('--timeout-navigation <timeout>', 'specify navigation timeout in milliseconds, defaults to 60000ms', numberParser)
+      .option('--timeout-settle <timeout>', 'how long to wait after each action for triggered work to settle, in milliseconds, defaults to 500ms', numberParser)
       .option('--user-agent <ua string>', 'specify user agent string')
       .option('--user-data-dir <path>', 'path to the user data directory. If not specified, a temporary directory will be created.')
       .option('--viewport-size <size>', 'specify browser viewport size in pixels, for example "1280x720"', resolutionParser.bind(null, '--viewport-size'))