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 cli): strict args parsing (#39029)

Dmitry Gozman9fedc07f7c0e
diff --git a/packages/playwright/src/mcp/terminal/command.ts b/packages/playwright/src/mcp/terminal/command.ts
index af9dc59f1f..100d924f0d 100644
--- a/packages/playwright/src/mcp/terminal/command.ts
+++ b/packages/playwright/src/mcp/terminal/command.ts
@@ -14,6 +14,8 @@
* limitations under the License.
*/
+import { z } from 'playwright-core/lib/mcpBundle';
+
import type zodType from 'zod';
export type Category = 'core' | 'navigation' | 'keyboard' | 'mouse' | 'export' | 'storage' | 'tabs' | 'devtools' | 'session' | 'config';
@@ -34,30 +36,47 @@ export function declareCommand<Args extends zodType.ZodTypeAny, Options extends
return command;
}
+const kEmptyOptions = z.object({});
+const kEmptyArgs = z.object({});
+
export function parseCommand(command: AnyCommandSchema, args: Record<string, string> & { _: string[] }): { toolName: string, toolParams: any } {
- const shape = command.args ? (command.args as zodType.ZodObject<any>).shape : {};
- const argv = args['_'];
- const options = command.options?.parse({ ...args, _: undefined }) ?? {};
- const argsObject: Record<string, string> = {};
- let i = 0;
- for (const name of Object.keys(shape))
- argsObject[name] = argv[++i];
+ const optionsObject = { ...args } as Record<string, string>;
+ delete optionsObject['_'];
+ const optionsSchema = (command.options ?? kEmptyOptions).strict();
+ const options: Record<string, string> = zodParse(optionsSchema, optionsObject, 'option');
- let parsedArgsObject: Record<string, string> = {};
- try {
- parsedArgsObject = command.args?.parse(argsObject) ?? {};
- } catch (e) {
- throw new Error(formatZodError(e as zodType.ZodError));
- }
+ const argsSchema = (command.args ?? kEmptyArgs).strict();
+ const argNames = [...Object.keys(argsSchema.shape)];
+ const argv = args['_'].slice(1);
+ if (argv.length > argNames.length)
+ throw new Error(`error: too many arguments: expected ${argNames.length}, received ${argv.length}`);
+ const argsObject: Record<string, string> = {};
+ argNames.forEach((name, index) => argsObject[name] = argv[index]);
+ const parsedArgsObject: Record<string, string> = zodParse(argsSchema, argsObject, 'argument');
const toolName = typeof command.toolName === 'function' ? command.toolName({ ...parsedArgsObject, ...options }) : command.toolName;
const toolParams = command.toolParams({ ...parsedArgsObject, ...options });
return { toolName, toolParams };
}
-function formatZodError(error: zodType.ZodError): string {
- const issue = error.issues[0];
- if (issue.code === 'invalid_type')
- return `${issue.message} in <${issue.path.join('.')}>`;
- return error.issues.map(i => i.message).join('\n');
+function zodParse(schema: zodType.ZodAny, data: unknown, type: 'option' | 'argument'): any {
+ try {
+ return schema.parse(data);
+ } catch (e) {
+ throw new Error((e as zodType.ZodError).issues.map(issue => {
+ const keys: string[] = (issue as any).keys || [''];
+ const props = keys.map(key => [...issue.path, key].filter(Boolean).join('.'));
+ return props.map(prop => {
+ const label = type === 'option' ? `'--${prop}' option` : `'${prop}' argument`;
+ switch (issue.code) {
+ case 'invalid_type':
+ return 'error: ' + label + ': ' + issue.message.toLowerCase().replace(/invalid input:/, '').trim();
+ case 'unrecognized_keys':
+ return 'error: unknown ' + label;
+ default:
+ return 'error: ' + label + ': ' + issue.message.toLowerCase();
+ }
+ });
+ }).flat().join('\n'));
+ }
}
diff --git a/packages/playwright/src/mcp/terminal/commands.ts b/packages/playwright/src/mcp/terminal/commands.ts
index 781ddc8ece..ba6fdf634b 100644
--- a/packages/playwright/src/mcp/terminal/commands.ts
+++ b/packages/playwright/src/mcp/terminal/commands.ts
@@ -205,9 +205,6 @@ const drag = declareCommand({
startRef: z.string().describe('Exact source element reference from the page snapshot'),
endRef: z.string().describe('Exact target element reference from the page snapshot'),
}),
- options: z.object({
- headed: z.boolean().default(false).describe('Run browser in headed mode'),
- }),
toolName: 'browser_drag',
toolParams: ({ startRef, endRef }) => ({ startRef, endRef }),
});
@@ -536,10 +533,10 @@ const config = declareCommand({
description: 'Restart session with new config, defaults to `playwright-cli.json`',
category: 'config',
options: z.object({
- browser: z.string().optional().describe('browser or chrome channel to use, possible values: chrome, firefox, webkit, msedge.'),
+ browser: z.string().optional().describe('Browser or chrome channel to use, possible values: chrome, firefox, webkit, msedge.'),
config: z.string().optional().describe('Path to the configuration file'),
- isolated: z.boolean().optional().describe('keep the browser profile in memory, do not save it to disk.'),
- headed: z.boolean().optional().describe('run browser in headed mode'),
+ isolated: z.boolean().optional().describe('Keep the browser profile in memory, do not save it to disk.'),
+ headed: z.boolean().optional().describe('Run browser in headed mode'),
}),
toolName: '',
toolParams: () => ({}),
diff --git a/packages/playwright/src/mcp/terminal/helpGenerator.ts b/packages/playwright/src/mcp/terminal/helpGenerator.ts
index 288d02684d..72a4a762f6 100644
--- a/packages/playwright/src/mcp/terminal/helpGenerator.ts
+++ b/packages/playwright/src/mcp/terminal/helpGenerator.ts
@@ -96,10 +96,12 @@ export function generateHelp() {
}
lines.push('\nGlobal options:');
+ lines.push(formatWithGap(' --browser <browser>', 'browser or chrome channel to use, possible values: chrome, firefox, webkit, msedge'));
lines.push(formatWithGap(' --config <path>', 'create a session with custom config, defaults to `playwright-cli.json`'));
lines.push(formatWithGap(' --extension', 'connect to a running browser instance using Playwright MCP Bridge extension'));
lines.push(formatWithGap(' --headed', 'create a headed session'));
lines.push(formatWithGap(' --help [command]', 'print help'));
+ lines.push(formatWithGap(' --isolated', 'keep the browser profile in memory, do not save it to disk'));
lines.push(formatWithGap(' --session', 'run command in the scope of a specific session'));
lines.push(formatWithGap(' --version', 'print version'));
diff --git a/packages/playwright/src/mcp/terminal/program.ts b/packages/playwright/src/mcp/terminal/program.ts
index c2825cda66..8e37cb67fc 100644
--- a/packages/playwright/src/mcp/terminal/program.ts
+++ b/packages/playwright/src/mcp/terminal/program.ts
@@ -330,6 +330,8 @@ class SessionManager {
this.sessions.set(sessionName, session);
}
+ for (const globalOption of ['browser', 'config', 'daemonVersion', 'extension', 'headed', 'help', 'isolated', 'session', 'version'])
+ delete args[globalOption];
const result = await session.run(args);
console.log(result.text);
session.close();
diff --git a/tests/mcp/cli.spec.ts b/tests/mcp/cli.spec.ts
index 63fe965f18..5a327af81d 100644
--- a/tests/mcp/cli.spec.ts
+++ b/tests/mcp/cli.spec.ts
@@ -388,6 +388,13 @@ test.describe('devtools', () => {
const { output: videoStartOutput } = await cli('video-start');
expect(videoStartOutput).toContain('Video recording started.');
await cli('open', server.HELLO_WORLD);
+ await cli('eval', `
+ async () => {
+ document.body.style.backgroundColor = "red";
+ for (let i = 0; i < 100; i++)
+ await new Promise(f => requestAnimationFrame(() => requestAnimationFrame(f)));
+ }
+ `);
const { output: videoStopOutput } = await cli('video-stop', '--filename=video.webm');
expect(videoStopOutput).toContain(`### Result\n- [Video](.playwright-cli${path.sep}video.webm)`);
});
@@ -564,8 +571,10 @@ test.describe('versions', () => {
expect(error).toMatch(/Daemon is too old: daemon is 1.*, client is 2\.0\.0. Stopping it/);
}
{
- const { output } = await cli('open', server.PREFIX, '--daemonVersion=2.0.0');
+ const { output, exitCode } = await cli('open', server.PREFIX, '--daemonVersion=2.0.0');
+ expect(exitCode).toBe(0);
expect(output).toContain('Daemon for `default` session started with pid');
+ await cli('session-stop', '--daemonVersion=2.0.0');
}
});
@@ -583,6 +592,38 @@ test.describe('versions', () => {
});
});
+test.describe('parsing', () => {
+ test('unknown option', async ({ cli, server }) => {
+ const { error, exitCode } = await cli('open', '--some-option', 'value', 'about:blank');
+ expect(exitCode).toBe(1);
+ expect(error).toContain(`error: unknown '--some-option' option`);
+ });
+
+ test('too many arguments', async ({ cli, server }) => {
+ const { error, exitCode } = await cli('open', 'foo', 'bar');
+ expect(exitCode).toBe(1);
+ expect(error).toContain(`error: too many arguments: expected 1, received 2`);
+ });
+
+ test('wrong option type', async ({ cli, server }) => {
+ const { error, exitCode } = await cli('type', 'foo', '--submit=bar');
+ expect(exitCode).toBe(1);
+ expect(error).toContain(`error: '--submit' option: expected boolean, received string`);
+ });
+
+ test('missing argument', async ({ cli, server }) => {
+ const { error, exitCode } = await cli('open');
+ expect(exitCode).toBe(1);
+ expect(error).toContain(`error: 'url' argument: expected string, received undefined`);
+ });
+
+ test('wrong argument type', async ({ cli, server }) => {
+ const { error, exitCode } = await cli('mousemove', '12', 'foo');
+ expect(exitCode).toBe(1);
+ expect(error).toContain(`error: 'y' argument: expected number, received string`);
+ });
+});
+
test.describe('folders', () => {
test('snapshot', async ({ cli, server }, testInfo) => {
{