chore(mcp): introduce snapshot-mode full/incremental/none

Author: pavelfeldman

packages/playwright/src/mcp/browser/config.ts

@@ -59,6 +59,7 @@ export type CLIOptions = {
   saveVideo?: ViewportSize;
   secrets?: Record<string, string>;
   sharedBrowserContext?: boolean;
+  snapshotMode?: 'incremental' | 'full' | 'none';
   storageState?: string;
   testIdAttribute?: string;
   timeoutAction?: number;
@@ -86,6 +87,9 @@ export const defaultConfig: FullConfig = {
   },
   server: {},
   saveTrace: false,
+  snapshot: {
+    mode: 'incremental',
+  },
   timeouts: {
     action: 5000,
     navigation: 60000,
@@ -103,6 +107,9 @@ export type FullConfig = Config & {
   network: NonNullable<Config['network']>,
   saveTrace: boolean;
   server: NonNullable<Config['server']>,
+  snapshot: {
+    mode: 'incremental' | 'full' | 'none';
+  },
   timeouts: {
     action: number;
     navigation: number;
@@ -243,6 +250,7 @@ export function configFromCLIOptions(cliOptions: CLIOptions): Config {
     saveVideo: cliOptions.saveVideo,
     secrets: cliOptions.secrets,
     sharedBrowserContext: cliOptions.sharedBrowserContext,
+    snapshot: cliOptions.snapshotMode ? { mode: cliOptions.snapshotMode } : undefined,
     outputDir: cliOptions.outputDir,
     imageResponses: cliOptions.imageResponses,
     testIdAttribute: cliOptions.testIdAttribute,
@@ -385,6 +393,10 @@ function mergeConfig(base: FullConfig, overrides: Config): FullConfig {
       ...pickDefined(base.server),
       ...pickDefined(overrides.server),
     },
+    snapshot: {
+      ...pickDefined(base.snapshot),
+      ...pickDefined(overrides.snapshot),
+    },
     timeouts: {
       ...pickDefined(base.timeouts),
       ...pickDefined(overrides.timeouts),

packages/playwright/src/mcp/browser/response.ts

@@ -75,8 +75,12 @@ export class Response {
     return this._images;
   }
 
-  setIncludeSnapshot(full?: 'full') {
-    this._includeSnapshot = full ?? 'incremental';
+  setIncludeSnapshot() {
+    this._includeSnapshot = this._context.config.snapshot.mode;
+  }
+
+  setIncludeFullSnapshot() {
+    this._includeSnapshot = 'full';
   }
 
   setIncludeTabs() {

packages/playwright/src/mcp/browser/tools/snapshot.ts

@@ -30,7 +30,7 @@ const snapshot = defineTool({
 
   handle: async (context, params, response) => {
     await context.ensureTab();
-    response.setIncludeSnapshot('full');
+    response.setIncludeFullSnapshot();
   },
 });
 

packages/playwright/src/mcp/browser/tools/tabs.ts

@@ -45,14 +45,14 @@ const browserTabs = defineTool({
       }
       case 'close': {
         await context.closeTab(params.index);
-        response.setIncludeSnapshot('full');
+        response.setIncludeFullSnapshot();
         return;
       }
       case 'select': {
         if (params.index === undefined)
           throw new Error('Tab index is required');
         await context.selectTab(params.index);
-        response.setIncludeSnapshot('full');
+        response.setIncludeFullSnapshot();
         return;
       }
     }

packages/playwright/src/mcp/config.d.ts

@@ -175,5 +175,11 @@ export type Config = {
    * Whether to send image responses to the client. Can be "allow", "omit", or "auto". Defaults to "auto", which sends images if the client can display them.
    */
   imageResponses?: 'allow' | 'omit';
-};
 
+  snapshot?: {
+    /**
+     * When taking snapshots for responses, specifies the mode to use.
+     */
+    mode?: 'incremental' | 'full' | 'none';
+  }
+};

packages/playwright/src/mcp/program.ts

@@ -64,6 +64,7 @@ export function decorateCommand(command: Command, version: string) {
       .option('--save-video <size>', 'Whether to save the video of the session into the output directory. For example "--save-video=800x600"', resolutionParser.bind(null, '--save-video'))
       .option('--secrets <path>', 'path to a file containing secrets in the dotenv format', dotenvFileLoader)
       .option('--shared-browser-context', 'reuse the same browser context between all connected HTTP clients.')
+      .option('--snapshot-mode <mode>', 'when taking snapshots for responses, specifies the mode to use. Can be "incremental", "full", or "none". Default is incremental.')
       .option('--storage-state <path>', 'path to the storage state file for isolated sessions.')
       .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)

tests/mcp/snapshot-mode.spec.ts

@@ -0,0 +1,101 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { test, expect } from './fixtures';
+
+test('should respect --snapshot-mode=full', async ({ startClient, server }) => {
+  server.setContent('/', `<button>Button 1</button>`, 'text/html');
+
+  const { client } = await startClient({
+    args: ['--snapshot-mode=full'],
+  });
+
+  expect(await client.callTool({
+    name: 'browser_navigate',
+    arguments: {
+      url: server.PREFIX,
+    },
+  })).toHaveResponse({
+    pageState: expect.stringContaining(`
+- button "Button 1" [ref=e2]`),
+  });
+
+  expect(await client.callTool({
+    name: 'browser_evaluate',
+    arguments: {
+      function: `async () => {
+        const button2 = document.createElement('button');
+        button2.textContent = 'Button 2';
+        document.body.appendChild(button2);
+      }`,
+    },
+  })).toHaveResponse({
+    pageState: expect.stringContaining(`
+  - button "Button 1" [ref=e2]
+  - button "Button 2" [ref=e3]`),
+  });
+});
+
+test('should respect --snapshot-mode=incremental', async ({ startClient, server }) => {
+  server.setContent('/', `<button>Button 1</button>`, 'text/html');
+
+  const { client } = await startClient({
+    args: ['--snapshot-mode=incremental'],
+  });
+
+  expect(await client.callTool({
+    name: 'browser_navigate',
+    arguments: {
+      url: server.PREFIX,
+    },
+  })).toHaveResponse({
+    pageState: expect.stringContaining(`
+- button "Button 1" [ref=e2]`),
+  });
+
+  expect(await client.callTool({
+    name: 'browser_evaluate',
+    arguments: {
+      function: `async () => {
+        const button2 = document.createElement('button');
+        button2.textContent = 'Button 2';
+        document.body.appendChild(button2);
+      }`,
+    },
+  })).toHaveResponse({
+    pageState: expect.stringContaining(`
+- <changed> generic [active] [ref=e1]:
+  - ref=e2 [unchanged]
+  - button \"Button 2\" [ref=e3]`),
+  });
+});
+
+test('should respect --snapshot-mode=none', async ({ startClient, server }) => {
+  server.setContent('/', `<button>Button 1</button>`, 'text/html');
+
+  const { client } = await startClient({
+    args: ['--snapshot-mode=none'],
+  });
+
+  expect(await client.callTool({
+    name: 'browser_navigate',
+    arguments: {
+      url: server.PREFIX,
+    },
+  })).toHaveResponse({
+    pageState: undefined
+  });
+});