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): expose Locator.drop as MCP tool and CLI command (#40367)

Pavel Feldmanf9f8fff0e092
diff --git a/packages/playwright-core/src/tools/backend/files.ts b/packages/playwright-core/src/tools/backend/files.ts
index e1918ebffb..b7e965af6e 100644
--- a/packages/playwright-core/src/tools/backend/files.ts
+++ b/packages/playwright-core/src/tools/backend/files.ts
@@ -15,7 +15,9 @@
*/
import * as z from 'zod';
+import { formatObject } from '@isomorphic/stringUtils';
import { defineTabTool } from './tool';
+import { elementSchema } from './snapshot';
export const uploadFile = defineTabTool({
capability: 'core',
@@ -52,6 +54,45 @@ export const uploadFile = defineTabTool({
clearsModalState: 'fileChooser',
});
+export const drop = defineTabTool({
+ capability: 'core',
+
+ schema: {
+ name: 'browser_drop',
+ title: 'Drop files or data onto an element',
+ description: 'Drop files or MIME-typed data onto an element, as if dragged from outside the page. At least one of "paths" or "data" must be provided.',
+ inputSchema: elementSchema.extend({
+ paths: z.array(z.string()).optional().describe('Absolute paths to files to drop onto the element.'),
+ data: z.record(z.string(), z.string()).optional().describe('Data to drop, as a map of MIME type to string value (e.g. {"text/plain": "hello", "text/uri-list": "https://example.com"}).'),
+ }),
+ type: 'action',
+ },
+
+ handle: async (tab, params, response) => {
+ if (!params.paths?.length && !params.data)
+ throw new Error('At least one of "paths" or "data" must be provided.');
+
+ response.setIncludeSnapshot();
+ const { locator, resolved } = await tab.targetLocator(params);
+
+ if (params.paths)
+ await Promise.all(params.paths.map(p => response.resolveClientFilename(p)));
+
+ const payload: { files?: string | string[], data?: Record<string, string> } = {};
+ if (params.paths?.length)
+ payload.files = params.paths.length === 1 ? params.paths[0] : params.paths;
+ if (params.data)
+ payload.data = params.data;
+
+ await tab.waitForCompletion(async () => {
+ await locator.drop(payload, tab.actionTimeoutOptions);
+ });
+
+ response.addCode(`await page.${resolved}.drop(${formatObject(payload)});`);
+ },
+});
+
export default [
uploadFile,
+ drop,
];
diff --git a/packages/playwright-core/src/tools/cli-client/skill/SKILL.md b/packages/playwright-core/src/tools/cli-client/skill/SKILL.md
index eb30e05b6b..66b5ad4acd 100644
--- a/packages/playwright-core/src/tools/cli-client/skill/SKILL.md
+++ b/packages/playwright-core/src/tools/cli-client/skill/SKILL.md
@@ -38,6 +38,9 @@ playwright-cli dblclick e7
# --submit presses Enter after filling the element
playwright-cli fill e5 "[email protected]" --submit
playwright-cli drag e2 e8
+# drop files or data onto an element (from outside the page)
+playwright-cli drop e4 --path=./image.png
+playwright-cli drop e4 --data="text/plain=hello world"
playwright-cli hover e4
playwright-cli select e9 "option-value"
playwright-cli upload ./document.pdf
diff --git a/packages/playwright-core/src/tools/cli-daemon/commands.ts b/packages/playwright-core/src/tools/cli-daemon/commands.ts
index f2b9d5091b..d703773e87 100644
--- a/packages/playwright-core/src/tools/cli-daemon/commands.ts
+++ b/packages/playwright-core/src/tools/cli-daemon/commands.ts
@@ -259,6 +259,33 @@ const drag = declareCommand({
toolParams: ({ startTarget, endTarget }) => ({ startTarget, endTarget }),
});
+const drop = declareCommand({
+ name: 'drop',
+ description: 'Drop files or data onto an element',
+ category: 'core',
+ args: z.object({
+ target: z.string().describe(elementTargetDescription),
+ }),
+ options: z.object({
+ path: z.union([z.string(), z.array(z.string())]).optional().transform(v => v ? (Array.isArray(v) ? v : [v]) : undefined).describe('Absolute path to a file to drop onto the element (repeatable)'),
+ data: z.union([z.string(), z.array(z.string())]).optional().transform(v => v ? (Array.isArray(v) ? v : [v]) : undefined).describe('Data to drop in "mime/type=value" format, e.g. --data "text/plain=hello" (repeatable)'),
+ }),
+ toolName: 'browser_drop',
+ toolParams: ({ target, path, data }) => {
+ let dataMap: Record<string, string> | undefined;
+ if (data) {
+ dataMap = {};
+ for (const entry of data) {
+ const idx = entry.indexOf('=');
+ if (idx === -1)
+ throw new Error(`--data must be in "mime/type=value" format, got: ${entry}`);
+ dataMap[entry.slice(0, idx)] = entry.slice(idx + 1);
+ }
+ }
+ return { target, paths: path, data: dataMap };
+ },
+});
+
const fill = declareCommand({
name: 'fill',
description: 'Fill text into editable element',
@@ -993,6 +1020,7 @@ const commandsArray: AnyCommandSchema[] = [
doubleClick,
fill,
drag,
+ drop,
hover,
select,
fileUpload,
diff --git a/tests/mcp/capabilities.spec.ts b/tests/mcp/capabilities.spec.ts
index 2ab5c44af6..6f5442bb61 100644
--- a/tests/mcp/capabilities.spec.ts
+++ b/tests/mcp/capabilities.spec.ts
@@ -22,6 +22,7 @@ test('test snapshot tool list', async ({ client }) => {
'browser_click',
'browser_console_messages',
'browser_drag',
+ 'browser_drop',
'browser_evaluate',
'browser_file_upload',
'browser_fill_form',
diff --git a/tests/mcp/cli-drag.spec.ts b/tests/mcp/cli-drag.spec.ts
index 7d1a010b4c..a4706e6108 100644
--- a/tests/mcp/cli-drag.spec.ts
+++ b/tests/mcp/cli-drag.spec.ts
@@ -49,3 +49,51 @@ test('drag between elements', async ({ cli, server }) => {
expect(error).not.toMatch(/invalid_type|Zod validation error/i);
expect(output).toContain('dragTo');
});
+
+test('drop files and data onto an element', async ({ cli, server }, testInfo) => {
+ server.setContent('/', `
+<!DOCTYPE html>
+<html>
+<body>
+ <div id="zone" aria-label="dropzone" style="width:200px;height:100px;border:1px solid"></div>
+ <script>
+ window.__dropInfo = null;
+ const zone = document.getElementById('zone');
+ zone.addEventListener('dragenter', e => e.preventDefault());
+ zone.addEventListener('dragover', e => e.preventDefault());
+ zone.addEventListener('drop', async e => {
+ e.preventDefault();
+ const data = {};
+ for (const t of e.dataTransfer.types) {
+ if (t !== 'Files')
+ data[t] = e.dataTransfer.getData(t);
+ }
+ window.__dropInfo = { fileCount: e.dataTransfer.files.length, data };
+ });
+ </script>
+</body>
+</html>`, 'text/html');
+
+ const { snapshot } = await cli('open', server.PREFIX);
+ const refLine = snapshot!.split('\n').find(l => l.includes('"dropzone"') && l.includes('[ref='));
+ const ref = refLine?.match(/\[ref=(e\d+)\]/)?.[1];
+ expect(ref, 'snapshot should list the dropzone element with a ref').toBeTruthy();
+
+ const fs = await import('fs/promises');
+ const filePath = testInfo.outputPath('drop.txt');
+ await fs.writeFile(filePath, 'hi');
+
+ {
+ const { output, error, exitCode } = await cli('drop', ref!, `--path=${filePath}`);
+ expect(error).not.toMatch(/invalid_type|Zod validation error/i);
+ expect(exitCode).toBe(0);
+ expect(output).toContain('drop');
+ }
+
+ {
+ const { output, error, exitCode } = await cli('drop', ref!, '--data=text/plain=hello world');
+ expect(error).not.toMatch(/invalid_type|Zod validation error/i);
+ expect(exitCode).toBe(0);
+ expect(output).toContain('drop');
+ }
+});
diff --git a/tests/mcp/files.spec.ts b/tests/mcp/files.spec.ts
index 8ab29670c2..3ed6693140 100644
--- a/tests/mcp/files.spec.ts
+++ b/tests/mcp/files.spec.ts
@@ -336,3 +336,102 @@ test('file upload unrestricted when flag is set', async ({ startClient, server }
code: expect.stringContaining(`await fileChooser.setFiles(`),
});
});
+
+const dropzoneHtml = `
+ <div id="dropzone" aria-label="dropzone" style="width:300px;height:200px;border:2px dashed #888"></div>
+ <script>
+ window.__dropInfo = null;
+ const zone = document.getElementById('dropzone');
+ zone.addEventListener('dragenter', e => e.preventDefault());
+ zone.addEventListener('dragover', e => e.preventDefault());
+ zone.addEventListener('drop', async e => {
+ e.preventDefault();
+ const files = [];
+ for (const f of e.dataTransfer.files)
+ files.push({ name: f.name, size: f.size, text: await f.text() });
+ const data = {};
+ for (const t of e.dataTransfer.types) {
+ if (t !== 'Files')
+ data[t] = e.dataTransfer.getData(t);
+ }
+ window.__dropInfo = { files, data };
+ });
+ </script>
+`;
+
+test('browser_drop files', async ({ client, server }, testInfo) => {
+ server.setContent('/', dropzoneHtml, 'text/html');
+
+ await client.callTool({
+ name: 'browser_navigate',
+ arguments: { url: server.PREFIX },
+ });
+
+ const filePath = testInfo.outputPath('drop-me.txt');
+ await fs.writeFile(filePath, 'hello');
+
+ expect(await client.callTool({
+ name: 'browser_drop',
+ arguments: {
+ element: 'dropzone',
+ target: 'e2',
+ paths: [filePath],
+ },
+ })).toHaveResponse({
+ code: expect.stringContaining(`.drop(`),
+ });
+
+ expect(await client.callTool({
+ name: 'browser_evaluate',
+ arguments: { function: '() => window.__dropInfo' },
+ })).toHaveResponse({
+ result: expect.stringContaining(`"text": "hello"`),
+ });
+});
+
+test('browser_drop data', async ({ client, server }) => {
+ server.setContent('/', dropzoneHtml, 'text/html');
+
+ await client.callTool({
+ name: 'browser_navigate',
+ arguments: { url: server.PREFIX },
+ });
+
+ expect(await client.callTool({
+ name: 'browser_drop',
+ arguments: {
+ element: 'dropzone',
+ target: 'e2',
+ data: { 'text/plain': 'hello world' },
+ },
+ })).toHaveResponse({
+ code: expect.stringContaining(`.drop(`),
+ });
+
+ expect(await client.callTool({
+ name: 'browser_evaluate',
+ arguments: { function: '() => window.__dropInfo.data["text/plain"]' },
+ })).toHaveResponse({
+ result: `"hello world"`,
+ });
+});
+
+test('browser_drop requires paths or data', async ({ client, server }) => {
+ server.setContent('/', dropzoneHtml, 'text/html');
+
+ await client.callTool({
+ name: 'browser_navigate',
+ arguments: { url: server.PREFIX },
+ });
+
+ expect(await client.callTool({
+ name: 'browser_drop',
+ arguments: {
+ element: 'dropzone',
+ target: 'e2',
+ },
+ })).toHaveResponse({
+ isError: true,
+ error: expect.stringContaining(`At least one of "paths" or "data" must be provided.`),
+ });
+});