Skip to content

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

docs(mcp): clarify how tool file names are resolved (#42538)

Dmitry Gozman7894f5653e7f
diff --git a/packages/playwright-core/src/tools/backend/console.ts b/packages/playwright-core/src/tools/backend/console.ts
index 60c19c25bf..59a1cf274d 100644
--- a/packages/playwright-core/src/tools/backend/console.ts
+++ b/packages/playwright-core/src/tools/backend/console.ts
@@ -26,7 +26,7 @@ const console = defineTabTool({
inputSchema: z.object({
level: z.enum(['error', 'warning', 'info', 'debug']).default('info').describe('Level of the console messages to return. Each level includes the messages of more severe levels. Defaults to "info".'),
all: z.boolean().optional().describe('Return all console messages since the beginning of the session, not just since the last navigation. Defaults to false.'),
- filename: z.string().optional().describe('Filename to save the console messages to. If not provided, messages are returned as text.'),
+ filename: z.string().optional().describe('File name to save the console messages to. Relative file names are resolved against the workspace root. If not provided, messages are returned as text.'),
}),
type: 'readOnly',
},
diff --git a/packages/playwright-core/src/tools/backend/evaluate.ts b/packages/playwright-core/src/tools/backend/evaluate.ts
index df797b8b75..eaaa784377 100644
--- a/packages/playwright-core/src/tools/backend/evaluate.ts
+++ b/packages/playwright-core/src/tools/backend/evaluate.ts
@@ -24,7 +24,7 @@ import type { Tab } from './tab';
const evaluateSchema = optionalElementSchema.extend({
function: z.string().describe('() => { /* code */ } or (element) => { /* code */ } when element is provided'),
- filename: z.string().optional().describe('Filename to save the result to. If not provided, result is returned as text.'),
+ filename: z.string().optional().describe('File name to save the result to. Relative file names are resolved against the workspace root. If not provided, result is returned as text.'),
});
const evaluate = defineTabTool({
diff --git a/packages/playwright-core/src/tools/backend/network.ts b/packages/playwright-core/src/tools/backend/network.ts
index ded33eb582..006420b378 100644
--- a/packages/playwright-core/src/tools/backend/network.ts
+++ b/packages/playwright-core/src/tools/backend/network.ts
@@ -37,7 +37,7 @@ const requests = defineTabTool({
inputSchema: z.object({
static: z.boolean().default(false).describe('Whether to include successful static resources like images, fonts, scripts, etc. Defaults to false.'),
filter: z.string().optional().refine(v => !v || isRegexString(v), { message: 'Invalid regular expression' }).describe('Only return requests whose URL matches this regexp (e.g. "/api/.*user").'),
- filename: z.string().optional().describe('Filename to save the network requests to. If not provided, requests are returned as text.'),
+ filename: z.string().optional().describe('File name to save the network requests to. Relative file names are resolved against the workspace root. If not provided, requests are returned as text.'),
}),
type: 'readOnly',
},
@@ -81,7 +81,7 @@ const request = defineTabTool({
inputSchema: z.object({
index: z.number().int().min(1).describe('1-based index of the request, as printed by browser_network_requests.'),
part: z.enum(REQUEST_PARTS).optional().describe('Return only this part of the request. Omit to return full details.'),
- filename: z.string().optional().describe('Filename to save the result to. If not provided, output is returned as text.'),
+ filename: z.string().optional().describe('File name to save the result to. Relative file names are resolved against the workspace root. If not provided, output is returned as text.'),
}),
type: 'readOnly',
},
diff --git a/packages/playwright-core/src/tools/backend/pdf.ts b/packages/playwright-core/src/tools/backend/pdf.ts
index a31a3569fd..c2fb1628aa 100644
--- a/packages/playwright-core/src/tools/backend/pdf.ts
+++ b/packages/playwright-core/src/tools/backend/pdf.ts
@@ -20,7 +20,7 @@ import { formatObject } from '@isomorphic/stringUtils';
import { defineTabTool } from './tool';
const pdfSchema = z.object({
- filename: z.string().optional().describe('File name to save the pdf to. Defaults to `page-{timestamp}.pdf` if not specified. Prefer relative file names to stay within the output directory.'),
+ filename: z.string().optional().describe('File name to save the pdf to. Relative file names are resolved against the workspace root. If not specified, the pdf is saved into the output directory as `page-{timestamp}.pdf`.'),
});
const pdf = defineTabTool({
diff --git a/packages/playwright-core/src/tools/backend/runCode.ts b/packages/playwright-core/src/tools/backend/runCode.ts
index ecada28e95..62905a7b0c 100644
--- a/packages/playwright-core/src/tools/backend/runCode.ts
+++ b/packages/playwright-core/src/tools/backend/runCode.ts
@@ -24,7 +24,7 @@ import { defineTabTool } from './tool';
const codeSchema = z.object({
code: z.string().optional().describe(`A JavaScript function containing Playwright code to execute. It will be invoked with a single argument, page, which you can use for any page interaction. For example: \`async (page) => { await page.getByRole('button', { name: 'Submit' }).click(); return await page.title(); }\``),
- filename: z.string().optional().describe('Load code from the specified file. If both code and filename are provided, code will be ignored.'),
+ filename: z.string().optional().describe('Load code from the specified file. Relative file names are resolved against the workspace root. If both code and filename are provided, code will be ignored.'),
});
const runCode = defineTabTool({
diff --git a/packages/playwright-core/src/tools/backend/screenshot.ts b/packages/playwright-core/src/tools/backend/screenshot.ts
index af0cf5e0cf..2da35c8b16 100644
--- a/packages/playwright-core/src/tools/backend/screenshot.ts
+++ b/packages/playwright-core/src/tools/backend/screenshot.ts
@@ -28,7 +28,7 @@ type ImageFormat = 'png' | 'jpeg' | 'webp';
const screenshotSchema = optionalElementSchema.extend({
type: z.enum(['png', 'jpeg', 'webp']).optional().describe('Image format for the screenshot. If unset, inferred from the filename extension, otherwise png.'),
- filename: z.string().optional().describe('File name to save the screenshot to. Defaults to `page-{timestamp}.{png|jpeg|webp}` if not specified. Prefer relative file names to stay within the output directory.'),
+ filename: z.string().optional().describe('File name to save the screenshot to. Relative file names are resolved against the workspace root. If not specified, the screenshot is saved into the output directory as `page-{timestamp}.{png|jpeg|webp}`.'),
fullPage: z.boolean().optional().describe('When true, takes a screenshot of the full scrollable page, instead of the currently visible viewport. Cannot be used with element screenshots.'),
scale: z.enum(['css', 'device']).default('css').describe('Image resolution scale. "css" produces a screenshot sized in CSS pixels (smaller, consistent across devices). "device" produces a high-resolution screenshot using device pixels (larger, accounts for the device pixel ratio). Default is css.'),
});
diff --git a/packages/playwright-core/src/tools/backend/snapshot.ts b/packages/playwright-core/src/tools/backend/snapshot.ts
index 2df46b433e..cda3d0fa6c 100644
--- a/packages/playwright-core/src/tools/backend/snapshot.ts
+++ b/packages/playwright-core/src/tools/backend/snapshot.ts
@@ -40,7 +40,7 @@ const snapshot = defineTabTool({
description: 'Capture accessibility snapshot of the current page, this is better than screenshot',
inputSchema: z.object({
target: z.string().optional().describe(elementTargetDescription),
- filename: z.string().optional().describe('Save snapshot to markdown file instead of returning it in the response.'),
+ filename: z.string().optional().describe('Save snapshot to a file instead of returning it in the response. Relative file names are resolved against the workspace root.'),
depth: z.number().optional().describe('Limit the depth of the snapshot tree'),
boxes: z.boolean().optional().describe('Include each element\'s bounding box as [box=x,y,width,height] in the snapshot. Coordinates are viewport-relative, in CSS pixels (Element.getBoundingClientRect)'),
}),
diff --git a/packages/playwright-core/src/tools/backend/storage.ts b/packages/playwright-core/src/tools/backend/storage.ts
index 0308496cc8..30685e3011 100644
--- a/packages/playwright-core/src/tools/backend/storage.ts
+++ b/packages/playwright-core/src/tools/backend/storage.ts
@@ -26,7 +26,7 @@ const storageState = defineTool({
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.'),
+ filename: z.string().optional().describe('File name to save the storage state to. Relative file names are resolved against the workspace root. If not specified, the storage state is saved into the output directory as `storage-state-{timestamp}.json`.'),
}),
type: 'readOnly',
},
@@ -49,7 +49,7 @@ const setStorageState = defineTool({
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'),
+ filename: z.string().describe('Path to the storage state file to restore from. Relative file names are resolved against the workspace root.'),
}),
type: 'action',
},
diff --git a/packages/playwright-core/src/tools/backend/video.ts b/packages/playwright-core/src/tools/backend/video.ts
index ad49b09bc2..924b7e5362 100644
--- a/packages/playwright-core/src/tools/backend/video.ts
+++ b/packages/playwright-core/src/tools/backend/video.ts
@@ -25,7 +25,7 @@ const videoStart = defineTool({
title: 'Start video',
description: 'Start video recording',
inputSchema: z.object({
- filename: z.string().optional().describe('Filename to save the video.'),
+ filename: z.string().optional().describe('File name to save the video to. Relative file names are resolved against the workspace root. If not specified, the video is saved into the output directory as `video-{timestamp}.webm`.'),
size: z.object({
width: z.number().describe('Video width'),
height: z.number().describe('Video height'),
diff --git a/packages/playwright-core/src/tools/mcp/config.d.ts b/packages/playwright-core/src/tools/mcp/config.d.ts
index 08863db5ee..d27f92fe1c 100644
--- a/packages/playwright-core/src/tools/mcp/config.d.ts
+++ b/packages/playwright-core/src/tools/mcp/config.d.ts
@@ -154,7 +154,9 @@ export type Config = {
secrets?: Record<string, string>;
/**
- * The directory to save output files.
+ * The directory for automatically named output files, for example a screenshot taken without an
+ * explicit file name. Files with an explicit name are resolved against the workspace root instead
+ * and are not affected by this option.
*/
outputDir?: string;
diff --git a/packages/playwright-core/src/tools/mcp/program.ts b/packages/playwright-core/src/tools/mcp/program.ts
index 9203c9abdc..8b59d778f5 100644
--- a/packages/playwright-core/src/tools/mcp/program.ts
+++ b/packages/playwright-core/src/tools/mcp/program.ts
@@ -59,7 +59,7 @@ export function decorateMCPCommand(command: Command) {
.option('--isolated', 'keep the browser profile in memory, do not save it to disk.')
.option('--image-responses <mode>', 'whether to send image responses to the client. Can be "allow" or "omit", Defaults to "allow".', enumParser.bind(null, '--image-responses', ['allow', 'omit']))
.option('--no-sandbox', 'disable the sandbox for all process types that are normally sandboxed.')
- .option('--output-dir <path>', 'path to the directory for output files.')
+ .option('--output-dir <path>', 'path to the directory for automatically named output files, for example a screenshot taken without an explicit file name. Files with an explicit name are resolved against the workspace root instead and are not affected by this option.')
.option('--output-max-size <bytes>', 'Threshold for evicting old output files, in bytes.', numberParser)
.option('--port <port>', 'port to listen on for SSE transport.')
.option('--profile-dir-name <name>', 'name of the profile directory in the user data dir to connect to with --extension, for example "Profile 1". Defaults to the last used profile that has the extension installed.')