Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.
TypeScript automationchromechromiume2e-testingelectronend-to-end-testingfirefoxjavascriptplaywrighttesttest-automationtestingtesting-toolswebwebkit
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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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'),+ });+});