Skip to content

Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.

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

Pavel Feldman0e881eb3ed36
diff --git a/packages/playwright/src/mcp/browser/config.ts b/packages/playwright/src/mcp/browser/config.ts
index 72c3937bc8..dc83efa9f0 100644
--- a/packages/playwright/src/mcp/browser/config.ts
+++ b/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),
diff --git a/packages/playwright/src/mcp/browser/response.ts b/packages/playwright/src/mcp/browser/response.ts
index 97feb4336c..1f6be9473b 100644
--- a/packages/playwright/src/mcp/browser/response.ts
+++ b/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() {
diff --git a/packages/playwright/src/mcp/browser/tools/snapshot.ts b/packages/playwright/src/mcp/browser/tools/snapshot.ts
index 33abe39621..a947195206 100644
--- a/packages/playwright/src/mcp/browser/tools/snapshot.ts
+++ b/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();
},
});
diff --git a/packages/playwright/src/mcp/browser/tools/tabs.ts b/packages/playwright/src/mcp/browser/tools/tabs.ts
index 6eec59d5ac..f1821e597e 100644
--- a/packages/playwright/src/mcp/browser/tools/tabs.ts
+++ b/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;
}
}
diff --git a/packages/playwright/src/mcp/config.d.ts b/packages/playwright/src/mcp/config.d.ts
index 93d0bc03a6..9a04795ccf 100644
--- a/packages/playwright/src/mcp/config.d.ts
+++ b/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';
+ }
+};
diff --git a/packages/playwright/src/mcp/program.ts b/packages/playwright/src/mcp/program.ts
index 5f1d98514b..4635b7e1b3 100644
--- a/packages/playwright/src/mcp/program.ts
+++ b/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)
diff --git a/tests/mcp/snapshot-mode.spec.ts b/tests/mcp/snapshot-mode.spec.ts
new file mode 100644
index 0000000000..d9d68e3b5b
--- /dev/null
+++ b/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
+ });
+});