Skip to content

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

feat(mcp): add storage state tools (#39007)

Yury Semikhatsky2307bf370b81
diff --git a/packages/playwright/src/mcp/browser/response.ts b/packages/playwright/src/mcp/browser/response.ts
index 55b2225507..3ec8263850 100644
--- a/packages/playwright/src/mcp/browser/response.ts
+++ b/packages/playwright/src/mcp/browser/response.ts
@@ -74,7 +74,7 @@ export class Response {
this._results.push({ title: '', text });
}
- async addResult(title: string, data: string | Buffer, file: Result['file']) {
+ addResult(title: string, data: string | Buffer, file: Result['file']) {
this._results.push({
text: typeof data === 'string' ? data : undefined,
data: typeof data === 'string' ? undefined : data,
diff --git a/packages/playwright/src/mcp/browser/tools.ts b/packages/playwright/src/mcp/browser/tools.ts
index 1b00ffc826..6432206fdc 100644
--- a/packages/playwright/src/mcp/browser/tools.ts
+++ b/packages/playwright/src/mcp/browser/tools.ts
@@ -29,6 +29,7 @@ import pdf from './tools/pdf';
import runCode from './tools/runCode';
import snapshot from './tools/snapshot';
import screenshot from './tools/screenshot';
+import storage from './tools/storage';
import tabs from './tools/tabs';
import tracing from './tools/tracing';
import wait from './tools/wait';
@@ -53,6 +54,7 @@ export const browserTools: Tool<any>[] = [
...runCode,
...screenshot,
...snapshot,
+ ...storage,
...tabs,
...tracing,
...wait,
diff --git a/packages/playwright/src/mcp/browser/tools/console.ts b/packages/playwright/src/mcp/browser/tools/console.ts
index e5e121978c..f9d3b80fcd 100644
--- a/packages/playwright/src/mcp/browser/tools/console.ts
+++ b/packages/playwright/src/mcp/browser/tools/console.ts
@@ -32,7 +32,7 @@ const console = defineTabTool({
handle: async (tab, params, response) => {
const messages = await tab.consoleMessages(params.level);
const text = messages.map(message => message.toString()).join('\n');
- await response.addResult('Console', text, { prefix: 'console', ext: 'log', suggestedFilename: params.filename });
+ response.addResult('Console', text, { prefix: 'console', ext: 'log', suggestedFilename: params.filename });
},
});
diff --git a/packages/playwright/src/mcp/browser/tools/network.ts b/packages/playwright/src/mcp/browser/tools/network.ts
index 4038732e83..dc16a164e6 100644
--- a/packages/playwright/src/mcp/browser/tools/network.ts
+++ b/packages/playwright/src/mcp/browser/tools/network.ts
@@ -42,7 +42,7 @@ const requests = defineTabTool({
if (rendered)
text.push(rendered);
}
- await response.addResult('Network', text.join('\n'), { prefix: 'network', ext: 'log', suggestedFilename: params.filename });
+ response.addResult('Network', text.join('\n'), { prefix: 'network', ext: 'log', suggestedFilename: params.filename });
},
});
diff --git a/packages/playwright/src/mcp/browser/tools/pdf.ts b/packages/playwright/src/mcp/browser/tools/pdf.ts
index 0de0405f87..c4b876d785 100644
--- a/packages/playwright/src/mcp/browser/tools/pdf.ts
+++ b/packages/playwright/src/mcp/browser/tools/pdf.ts
@@ -38,7 +38,7 @@ const pdf = defineTabTool({
handle: async (tab, params, response) => {
const data = await tab.page.pdf();
const suggestedFilename = params.filename ?? dateAsFileName('page', 'pdf');
- await response.addResult('Page as pdf', data, { prefix: 'page', ext: 'pdf', suggestedFilename: suggestedFilename });
+ response.addResult('Page as pdf', data, { prefix: 'page', ext: 'pdf', suggestedFilename });
response.addCode(`await page.pdf(${formatObject({ path: suggestedFilename })});`);
},
});
diff --git a/packages/playwright/src/mcp/browser/tools/screenshot.ts b/packages/playwright/src/mcp/browser/tools/screenshot.ts
index 898b05473b..22f13f12f7 100644
--- a/packages/playwright/src/mcp/browser/tools/screenshot.ts
+++ b/packages/playwright/src/mcp/browser/tools/screenshot.ts
@@ -67,7 +67,7 @@ const screenshot = defineTabTool({
response.addCode(`await page.screenshot(${formatObject({ ...options, path: suggestedFilename })});`);
const contentType = fileType === 'png' ? 'image/png' : 'image/jpeg';
- await response.addResult(`Screenshot of ${screenshotTarget}`, data, { prefix: ref ? 'element' : 'page', ext: fileType, suggestedFilename, contentType });
+ response.addResult(`Screenshot of ${screenshotTarget}`, data, { prefix: ref ? 'element' : 'page', ext: fileType, suggestedFilename, contentType });
}
});
diff --git a/packages/playwright/src/mcp/browser/tools/storage.ts b/packages/playwright/src/mcp/browser/tools/storage.ts
new file mode 100644
index 0000000000..66591099b1
--- /dev/null
+++ b/packages/playwright/src/mcp/browser/tools/storage.ts
@@ -0,0 +1,68 @@
+/**
+ * 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 { z } from 'playwright-core/lib/mcpBundle';
+import { defineTool } from './tool';
+import { dateAsFileName } from './utils';
+
+const storageState = defineTool({
+ capability: 'storage',
+
+ schema: {
+ name: 'browser_storage_state',
+ title: 'Save storage state',
+ description: 'Save storage state (cookies, local storage) to a file for later reuse',
+ inputSchema: z.object({
+ filename: z.string().optional().describe('File name to save the storage state to. Defaults to `storage-state-{timestamp}.json` if not specified.'),
+ }),
+ type: 'readOnly',
+ },
+
+ handle: async (context, params, response) => {
+ const browserContext = await context.ensureBrowserContext();
+ const state = await browserContext.storageState();
+ const suggestedFilename = params.filename || dateAsFileName('storage-state', 'json');
+ const serializedState = JSON.stringify(state, null, 2);
+ response.addResult('Storage state', serializedState, { prefix: 'storage-state', ext: 'json', suggestedFilename });
+ response.addCode(`await page.context().storageState({ path: '${suggestedFilename}' });`);
+ },
+});
+
+const setStorageState = defineTool({
+ capability: 'storage',
+
+ schema: {
+ name: 'browser_set_storage_state',
+ title: 'Restore storage state',
+ description: 'Restore storage state (cookies, local storage) from a file. This clears existing cookies and local storage before restoring.',
+ inputSchema: z.object({
+ filename: z.string().describe('Path to the storage state file to restore from'),
+ }),
+ type: 'action',
+ },
+
+ handle: async (context, params, response) => {
+ const browserContext = await context.ensureBrowserContext();
+ await browserContext.setStorageState(params.filename);
+ response.addTextResult(`Storage state restored from ${params.filename}`);
+ response.addCode(`await page.context().setStorageState('${params.filename}');`);
+ },
+});
+
+export default [
+ storageState,
+ setStorageState,
+];
diff --git a/packages/playwright/src/mcp/config.d.ts b/packages/playwright/src/mcp/config.d.ts
index c47cae41e2..62f3073ccf 100644
--- a/packages/playwright/src/mcp/config.d.ts
+++ b/packages/playwright/src/mcp/config.d.ts
@@ -18,15 +18,15 @@ import type * as playwright from 'playwright-core';
export type ToolCapability =
'core' |
- 'core-input' |
'core-navigation' |
'core-tabs' |
- 'core-install' |
'core-input' |
- 'vision' |
+ 'core-install' |
'pdf' |
+ 'storage' |
'testing' |
- 'tracing';
+ 'tracing' |
+ 'vision';
export type Config = {
/**
diff --git a/tests/mcp/storage.spec.ts b/tests/mcp/storage.spec.ts
new file mode 100644
index 0000000000..2df4c59415
--- /dev/null
+++ b/tests/mcp/storage.spec.ts
@@ -0,0 +1,239 @@
+/**
+ * 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 fs from 'fs';
+import path from 'path';
+import { test, expect } from './fixtures';
+
+test('browser_storage_state unavailable', async ({ startClient, server }) => {
+ const { client } = await startClient();
+ await client.callTool({
+ name: 'browser_navigate',
+ arguments: { url: server.HELLO_WORLD },
+ });
+
+ expect(await client.callTool({
+ name: 'browser_storage_state',
+ })).toHaveResponse({
+ error: 'Tool "browser_storage_state" not found',
+ isError: true,
+ });
+
+ expect(await client.callTool({
+ name: 'browser_set_storage_state',
+ })).toHaveResponse({
+ error: 'Tool "browser_set_storage_state" not found',
+ isError: true,
+ });
+});
+
+test('browser_storage_state saves storage state to file', async ({ startClient, server }, testInfo) => {
+ const outputDir = testInfo.outputPath('output');
+
+ const { client } = await startClient({
+ config: { outputDir, capabilities: ['storage'] },
+ });
+
+ // Navigate and set some cookies
+ await client.callTool({
+ name: 'browser_navigate',
+ arguments: { url: server.EMPTY_PAGE },
+ });
+
+ await client.callTool({
+ name: 'browser_evaluate',
+ arguments: { function: '() => { document.cookie = "testCookie=testValue"; localStorage.setItem("testKey", "testValue"); }' },
+ });
+
+ // Save storage state
+ const result = await client.callTool({
+ name: 'browser_storage_state',
+ arguments: {},
+ });
+
+ expect(result).toHaveResponse({
+ result: expect.stringMatching(/- \[Storage state\]\(output.storage-state-.*.json/),
+ code: expect.stringContaining('page.context().storageState'),
+ });
+
+ // Verify the file was created and contains the cookie
+ const files = await fs.promises.readdir(outputDir);
+ const storageStateFile = files.find(f => f.startsWith('storage-state-'));
+ expect(storageStateFile).toBeDefined();
+
+ const content = JSON.parse(await fs.promises.readFile(path.join(outputDir, storageStateFile!), 'utf-8'));
+ expect(content.cookies).toContainEqual(expect.objectContaining({
+ name: 'testCookie',
+ value: 'testValue',
+ }));
+});
+
+test('browser_storage_state saves to custom filename', async ({ startClient, server }, testInfo) => {
+ const outputDir = testInfo.outputPath('output');
+
+ const { client } = await startClient({
+ config: { outputDir, capabilities: ['storage'] },
+ });
+
+ await client.callTool({
+ name: 'browser_navigate',
+ arguments: { url: server.EMPTY_PAGE },
+ });
+
+ const result = await client.callTool({
+ name: 'browser_storage_state',
+ arguments: { filename: 'my-state.json' },
+ });
+
+ expect(result).toHaveResponse({
+ result: expect.stringContaining('my-state.json'),
+ });
+
+ const stateFile = path.join(outputDir, 'my-state.json');
+ expect(await fs.promises.stat(stateFile).catch(() => null)).not.toBeNull();
+});
+
+test('browser_set_storage_state restores storage state from file', async ({ startClient, server, mcpBrowser }, testInfo) => {
+ test.fixme(mcpBrowser === 'webkit', 'setStorageState is failing');
+
+ const outputDir = testInfo.outputPath('output');
+ await fs.promises.mkdir(outputDir, { recursive: true });
+
+ // Create a storage state file
+ const storageState = {
+ cookies: [{
+ name: 'restoredCookie',
+ value: 'restoredValue',
+ domain: 'localhost',
+ path: '/',
+ }],
+ origins: [{
+ origin: server.PREFIX,
+ localStorage: [{
+ name: 'restoredKey',
+ value: 'restoredValue',
+ }],
+ }],
+ };
+
+ const stateFile = path.join(outputDir, 'state.json');
+ await fs.promises.writeFile(stateFile, JSON.stringify(storageState));
+
+ const { client } = await startClient({
+ config: { outputDir, capabilities: ['storage'] },
+ });
+
+ await client.callTool({
+ name: 'browser_navigate',
+ arguments: { url: server.EMPTY_PAGE },
+ });
+
+ // Restore storage state
+ const result = await client.callTool({
+ name: 'browser_set_storage_state',
+ arguments: { filename: stateFile },
+ });
+
+ expect(result).toHaveResponse({
+ result: expect.stringContaining('Storage state restored'),
+ code: expect.stringContaining('page.context().setStorageState'),
+ });
+
+ // Verify the cookie was restored
+ const cookieResult = await client.callTool({
+ name: 'browser_evaluate',
+ arguments: { function: '() => document.cookie' },
+ });
+
+ expect(cookieResult).toHaveResponse({
+ result: expect.stringContaining('restoredCookie=restoredValue'),
+ });
+
+ // Verify localStorage was restored
+ const localStorageResult = await client.callTool({
+ name: 'browser_evaluate',
+ arguments: { function: '() => localStorage.getItem("restoredKey")' },
+ });
+
+ expect(localStorageResult).toHaveResponse({
+ result: expect.stringContaining('restoredValue'),
+ });
+});
+
+test('browser_storage_state and browser_set_storage_state roundtrip', async ({ startClient, server, mcpBrowser }, testInfo) => {
+ test.fixme(mcpBrowser === 'webkit', 'setStorageState is failing');
+
+ const outputDir = testInfo.outputPath('output');
+
+ const { client } = await startClient({
+ config: { outputDir, capabilities: ['storage'] },
+ });
+
+ // Navigate and set data
+ await client.callTool({
+ name: 'browser_navigate',
+ arguments: { url: server.EMPTY_PAGE },
+ });
+
+ await client.callTool({
+ name: 'browser_evaluate',
+ arguments: { function: '() => { document.cookie = "roundtripCookie=roundtripValue"; localStorage.setItem("roundtripKey", "roundtripValue"); }' },
+ });
+
+ // Save storage state
+ await client.callTool({
+ name: 'browser_storage_state',
+ arguments: { filename: 'roundtrip-state.json' },
+ });
+
+ // Clear storage
+ await client.callTool({
+ name: 'browser_evaluate',
+ arguments: { function: '() => { document.cookie = "roundtripCookie=; expires=Thu, 01 Jan 1970 00:00:00 GMT"; localStorage.clear(); }' },
+ });
+
+ // Verify storage is cleared
+ const clearedResult = await client.callTool({
+ name: 'browser_evaluate',
+ arguments: { function: '() => document.cookie + "|" + localStorage.getItem("roundtripKey")' },
+ });
+
+ expect(clearedResult).toHaveResponse({
+ result: expect.stringContaining('|null'),
+ });
+
+ // Restore storage state
+ await client.callTool({
+ name: 'browser_set_storage_state',
+ arguments: { filename: path.join(outputDir, 'roundtrip-state.json') },
+ });
+
+ // Reload to pick up cookies
+ await client.callTool({
+ name: 'browser_navigate',
+ arguments: { url: server.EMPTY_PAGE },
+ });
+
+ // Verify storage was restored
+ const restoredResult = await client.callTool({
+ name: 'browser_evaluate',
+ arguments: { function: '() => document.cookie + "|" + localStorage.getItem("roundtripKey")' },
+ });
+
+ expect(restoredResult).toHaveResponse({
+ result: expect.stringContaining('roundtripCookie=roundtripValue'),
+ });
+});