fix(cli): accept multiple files in upload command (#42057)

Author: dgozman

docs/src/getting-started-cli.md

@@ -101,7 +101,7 @@ playwright-cli check <ref>              # check a checkbox or radio button
 playwright-cli uncheck <ref>            # uncheck a checkbox
 playwright-cli hover <ref>              # hover over element
 playwright-cli drag <startRef> <endRef> # drag and drop between elements
-playwright-cli upload <file>            # upload files
+playwright-cli upload <files...>        # upload one or multiple files
 playwright-cli close                    # close the page
 ```
 

packages/playwright-core/src/tools/cli-client/program.ts

@@ -445,9 +445,9 @@ function validateFlags(args: MinimistArgs, command: { flags: Record<string, 'boo
     output.errorUnknownOption(unknownFlags, command.help);
 }
 
-function validateArgs(args: MinimistArgs, command: { args: string[], help: string }, output: Output) {
+function validateArgs(args: MinimistArgs, command: { args: string[], variadicArg?: boolean, help: string }, output: Output) {
   const positional = args._.slice(1);
-  if (positional.length > command.args.length)
+  if (positional.length > command.args.length && !command.variadicArg)
     output.errorTooManyArguments(command.args.length, positional.length, command.help);
 }
 

packages/playwright-core/src/tools/cli-daemon/command.ts

@@ -40,6 +40,19 @@ export function declareCommand<Args extends zodType.ZodTypeAny, Options extends
 const kEmptyOptions = z.object({});
 const kEmptyArgs = z.object({});
 
+// The last positional argument absorbs the remaining argv when its schema accepts an array.
+export function isVariadicArg(schema: zodType.ZodTypeAny): boolean {
+  if (schema instanceof z.ZodArray)
+    return true;
+  if (schema instanceof z.ZodUnion)
+    return schema.options.some(option => isVariadicArg(option as zodType.ZodTypeAny));
+  if (schema instanceof z.ZodOptional)
+    return isVariadicArg(schema.unwrap() as zodType.ZodTypeAny);
+  if (schema instanceof z.ZodPipe)
+    return isVariadicArg(schema.in as zodType.ZodTypeAny);
+  return false;
+}
+
 export function parseCommand(command: AnyCommandSchema, args: Record<string, string> & { _: string[] }): { toolName: string, toolParams: any } {
   const optionsObject = { ...args } as Record<string, string>;
   delete optionsObject['_'];
@@ -49,11 +62,17 @@ export function parseCommand(command: AnyCommandSchema, args: Record<string, str
   const argsSchema = (command.args ?? kEmptyArgs).strict();
   const argNames = [...Object.keys(argsSchema.shape)];
   const argv = args['_'].slice(1);
-  if (argv.length > argNames.length)
+  const variadic = argNames.length > 0 && isVariadicArg(argsSchema.shape[argNames[argNames.length - 1]]);
+  if (argv.length > argNames.length && !variadic)
     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 argsObject: Record<string, string | string[] | undefined> = {};
+  argNames.forEach((name, index) => {
+    if (variadic && index === argNames.length - 1)
+      argsObject[name] = index < argv.length ? argv.slice(index) : undefined;
+    else
+      argsObject[name] = argv[index];
+  });
+  const parsedArgsObject: Record<string, string | string[]> = zodParse(argsSchema, argsObject, 'argument');
 
   const toolName = typeof command.toolName === 'function' ? command.toolName({ ...parsedArgsObject, ...options }) : command.toolName;
   const toolParams = command.toolParams({ ...parsedArgsObject, ...options });
@@ -72,6 +91,10 @@ function zodParse(schema: zodType.ZodAny, data: unknown, type: 'option' | 'argum
         switch (issue.code) {
           case 'invalid_type':
             return 'error: ' + label + ': ' + issue.message.replace(/Invalid input:/, '').trim();
+          case 'invalid_union': {
+            const message = issue.errors[0]?.[0]?.message ?? issue.message;
+            return 'error: ' + label + ': ' + message.replace(/Invalid input:/, '').trim();
+          }
           case 'unrecognized_keys':
             return 'error: unknown ' + label;
           default:

packages/playwright-core/src/tools/cli-daemon/commands.ts

@@ -343,10 +343,10 @@ const fileUpload = declareCommand({
   description: 'Upload one or multiple files',
   category: 'core',
   args: z.object({
-    file: z.string().describe('The absolute paths to the files to upload'),
+    files: stringArrayArg.describe('The absolute paths to the files to upload'),
   }),
   toolName: 'browser_file_upload',
-  toolParams: ({ file }) => ({ paths: [file] }),
+  toolParams: ({ files }) => ({ paths: files }),
 });
 
 const check = declareCommand({

packages/playwright-core/src/tools/cli-daemon/helpGenerator.ts

@@ -16,25 +16,33 @@
 
 import * as z from 'zod';
 import { commands } from './commands';
+import { isVariadicArg } from './command';
 
 import type zodType from 'zod';
 import type { AnyCommandSchema, Category } from './command';
 
-type CommandArg = { name: string, description: string, optional: boolean };
+type CommandArg = { name: string, description: string, optional: boolean, variadic: boolean };
 
 function commandArgs(command: AnyCommandSchema): CommandArg[] {
   const args: CommandArg[] = [];
   const shape = command.args ? (command.args as zodType.ZodObject<any>).shape : {};
+  const names = Object.keys(shape);
   for (const [name, schema] of Object.entries(shape)) {
     const zodSchema = schema as zodType.ZodTypeAny;
     const description = zodSchema.description ?? '';
-    args.push({ name, description, optional: zodSchema.safeParse(undefined).success });
+    const variadic = name === names[names.length - 1] && isVariadicArg(zodSchema);
+    args.push({ name, description, optional: zodSchema.safeParse(undefined).success, variadic });
   }
   return args;
 }
 
+function commandArgText(a: CommandArg) {
+  const name = a.variadic ? `${a.name}...` : a.name;
+  return a.optional ? `[${name}]` : `<${name}>`;
+}
+
 function commandArgsText(args: CommandArg[]) {
-  return args.map(a => a.optional ? `[${a.name}]` : `<${a.name}>`).join(' ');
+  return args.map(commandArgText).join(' ');
 }
 
 function generateCommandHelp(command: AnyCommandSchema) {
@@ -48,7 +56,7 @@ function generateCommandHelp(command: AnyCommandSchema) {
 
   if (args.length) {
     lines.push('Arguments:');
-    lines.push(...args.map(a => formatWithGap(`  ${a.optional ? `[${a.name}]` : `<${a.name}>`}`, a.description.toLowerCase())));
+    lines.push(...args.map(a => formatWithGap(`  ${commandArgText(a)}`, a.description.toLowerCase())));
   }
 
   if (command.options) {
@@ -165,7 +173,7 @@ function isBooleanSchema(schema: zodType.ZodTypeAny): boolean {
 export function generateHelpJSON() {
   const booleanOptions = new Set<string>();
 
-  const commandEntries: Record<string, { help: string, flags: Record<string, 'boolean' | 'string'>, args: string[], raw?: boolean }> = {};
+  const commandEntries: Record<string, { help: string, flags: Record<string, 'boolean' | 'string'>, args: string[], variadicArg?: boolean, raw?: boolean }> = {};
   for (const [name, command] of Object.entries(commands)) {
     const flags: Record<string, 'boolean' | 'string'> = {};
     if (command.options) {
@@ -177,8 +185,10 @@ export function generateHelpJSON() {
           booleanOptions.add(flagName);
       }
     }
-    const args: string[] = command.args ? Object.keys((command.args as zodType.ZodObject<any>).shape) : [];
-    commandEntries[name] = { help: generateCommandHelp(command), flags, args };
+    const args = commandArgs(command);
+    commandEntries[name] = { help: generateCommandHelp(command), flags, args: args.map(a => a.name) };
+    if (args.some(a => a.variadic))
+      commandEntries[name].variadicArg = true;
     if (command.raw)
       commandEntries[name].raw = true;
   }

packages/playwright-core/src/tools/index.ts

@@ -30,7 +30,7 @@ export { compareSemver } from './utils/socketConnection';
 export { extractTrace, DirTraceLoaderBackend } from './trace/traceParser';
 export { decorateMCPCommand } from './mcp/program';
 export { program as cliProgram } from './cli-client/program';
-export { generateHelp, generateHelpJSON } from './cli-daemon/helpGenerator';
+export { generateHelp, generateHelpJSON, generateReadme } from './cli-daemon/helpGenerator';
 export { decorateProgram as decorateCliDaemonProgram, initWorkspace } from './cli-daemon/program';
 export { allSkills, installSkills } from './utils/installSkills';
 export { openDashboardApp, openDashboardForContext } from './dashboard/dashboardApp';

tests/mcp/cli-core.spec.ts

@@ -146,6 +146,33 @@ test('uncheck', async ({ cli, server, mcpBrowser }) => {
   expect(inlineSnapshot).toContain(`- checkbox ${active}[ref=e2]`);
 });
 
+test('upload multiple files', { annotation: { type: 'issue', description: 'https://github.com/microsoft/playwright/issues/42047' } }, async ({ cli, server }, testInfo) => {
+  server.setContent('/', `
+    <input type="file" multiple>
+    <div id="result"></div>
+    <script>
+      document.querySelector('input').addEventListener('change', event => {
+        document.getElementById('result').textContent = 'Received: ' + [...event.target.files].map(f => f.name).join(', ');
+      });
+    </script>
+  `, 'text/html');
+
+  const front = testInfo.outputPath('front.txt');
+  const back = testInfo.outputPath('back.txt');
+  await fs.promises.writeFile(front, 'front');
+  await fs.promises.writeFile(back, 'back');
+
+  await cli('open', server.PREFIX);
+  await cli('click', 'e2');
+  const { output, snapshot } = await cli('upload', front, back);
+  expect(output).toContain('await fileChooser.setFiles(');
+  expect(snapshot).toContain('Received: front.txt, back.txt');
+
+  await cli('click', 'e2');
+  const single = await cli('upload', back);
+  expect(single.snapshot).toContain('Received: back.txt');
+});
+
 test('eval', async ({ cli, server }) => {
   await cli('open', server.HELLO_WORLD);
   const { output } = await cli('eval', '() => document.title');

tests/mcp/cli-help.spec.ts

@@ -31,6 +31,11 @@ test('prints command help', async ({ cli }) => {
   expect(output).toContain('playwright-cli click <target> [button]');
 });
 
+test('prints variadic command help', { annotation: { type: 'issue', description: 'https://github.com/microsoft/playwright/issues/42047' } }, async ({ cli }) => {
+  const { output } = await cli('upload', '--help');
+  expect(output).toContain('playwright-cli upload <files...>');
+});
+
 test('prints agent skill path when running under a coding agent', async ({ cli }) => {
   const { output } = await cli('--help', { env: { CLAUDECODE: '1' } });
   expect(output).toContain('Agent skill:');

tests/mcp/cli-parsing.spec.ts

@@ -57,6 +57,13 @@ test('missing argument', async ({ cli, server }) => {
   expect(error).toContain(`error: 'key' argument: expected string, received undefined`);
 });
 
+test('missing variadic argument', { annotation: { type: 'issue', description: 'https://github.com/microsoft/playwright/issues/42047' } }, async ({ cli, server }) => {
+  await cli('open', server.HELLO_WORLD);
+  const { error, exitCode } = await cli('upload');
+  expect(exitCode).toBe(1);
+  expect(error).toContain(`error: 'files' argument: expected string, received undefined`);
+});
+
 test('wrong argument type', async ({ cli, server }) => {
   await cli('open', server.HELLO_WORLD);
   const { error, exitCode } = await cli('mousemove', '12', 'foo');

utils/build/build.js

@@ -946,6 +946,7 @@ steps.push(new ProgramStep({
 // Generate CLI help.
 onChanges.push({
   inputs: [
+    'packages/playwright-core/src/tools/cli-daemon/command.ts',
     'packages/playwright-core/src/tools/cli-daemon/commands.ts',
     'packages/playwright-core/src/tools/cli-daemon/helpGenerator.ts',
     'utils/generate_cli_help.js',