@playwright/mcp 0.0.30 → 0.0.32

package/lib/tools/mouse.js

@@ -0,0 +1,99 @@
+/**
+ * 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 'zod';
+import { defineTabTool } from './tool.js';
+const elementSchema = z.object({
+    element: z.string().describe('Human-readable element description used to obtain permission to interact with the element'),
+});
+const mouseMove = defineTabTool({
+    capability: 'vision',
+    schema: {
+        name: 'browser_mouse_move_xy',
+        title: 'Move mouse',
+        description: 'Move mouse to a given position',
+        inputSchema: elementSchema.extend({
+            x: z.number().describe('X coordinate'),
+            y: z.number().describe('Y coordinate'),
+        }),
+        type: 'readOnly',
+    },
+    handle: async (tab, params, response) => {
+        response.addCode(`// Move mouse to (${params.x}, ${params.y})`);
+        response.addCode(`await page.mouse.move(${params.x}, ${params.y});`);
+        await tab.waitForCompletion(async () => {
+            await tab.page.mouse.move(params.x, params.y);
+        });
+    },
+});
+const mouseClick = defineTabTool({
+    capability: 'vision',
+    schema: {
+        name: 'browser_mouse_click_xy',
+        title: 'Click',
+        description: 'Click left mouse button at a given position',
+        inputSchema: elementSchema.extend({
+            x: z.number().describe('X coordinate'),
+            y: z.number().describe('Y coordinate'),
+        }),
+        type: 'destructive',
+    },
+    handle: async (tab, params, response) => {
+        response.setIncludeSnapshot();
+        response.addCode(`// Click mouse at coordinates (${params.x}, ${params.y})`);
+        response.addCode(`await page.mouse.move(${params.x}, ${params.y});`);
+        response.addCode(`await page.mouse.down();`);
+        response.addCode(`await page.mouse.up();`);
+        await tab.waitForCompletion(async () => {
+            await tab.page.mouse.move(params.x, params.y);
+            await tab.page.mouse.down();
+            await tab.page.mouse.up();
+        });
+    },
+});
+const mouseDrag = defineTabTool({
+    capability: 'vision',
+    schema: {
+        name: 'browser_mouse_drag_xy',
+        title: 'Drag mouse',
+        description: 'Drag left mouse button to a given position',
+        inputSchema: elementSchema.extend({
+            startX: z.number().describe('Start X coordinate'),
+            startY: z.number().describe('Start Y coordinate'),
+            endX: z.number().describe('End X coordinate'),
+            endY: z.number().describe('End Y coordinate'),
+        }),
+        type: 'destructive',
+    },
+    handle: async (tab, params, response) => {
+        response.setIncludeSnapshot();
+        response.addCode(`// Drag mouse from (${params.startX}, ${params.startY}) to (${params.endX}, ${params.endY})`);
+        response.addCode(`await page.mouse.move(${params.startX}, ${params.startY});`);
+        response.addCode(`await page.mouse.down();`);
+        response.addCode(`await page.mouse.move(${params.endX}, ${params.endY});`);
+        response.addCode(`await page.mouse.up();`);
+        await tab.waitForCompletion(async () => {
+            await tab.page.mouse.move(params.startX, params.startY);
+            await tab.page.mouse.down();
+            await tab.page.mouse.move(params.endX, params.endY);
+            await tab.page.mouse.up();
+        });
+    },
+});
+export default [
+    mouseMove,
+    mouseClick,
+    mouseDrag,
+];

package/lib/tools/navigate.js

@@ -14,8 +14,8 @@
  * limitations under the License.
  */
 import { z } from 'zod';
-import { defineTool } from './tool.js';
-const navigate = captureSnapshot => defineTool({
+import { defineTool, defineTabTool } from './tool.js';
+const navigate = defineTool({
     capability: 'core',
     schema: {
         name: 'browser_navigate',
@@ -26,22 +26,16 @@ const navigate = captureSnapshot => defineTool({
         }),
         type: 'destructive',
     },
-    handle: async (context, params) => {
+    handle: async (context, params, response) => {
         const tab = await context.ensureTab();
         await tab.navigate(params.url);
-        const code = [
-            `// Navigate to ${params.url}`,
-            `await page.goto('${params.url}');`,
-        ];
-        return {
-            code,
-            captureSnapshot,
-            waitForNetwork: false,
-        };
+        response.setIncludeSnapshot();
+        response.addCode(`// Navigate to ${params.url}`);
+        response.addCode(`await page.goto('${params.url}');`);
     },
 });
-const goBack = captureSnapshot => defineTool({
-    capability: 'history',
+const goBack = defineTabTool({
+    capability: 'core',
     schema: {
         name: 'browser_navigate_back',
         title: 'Go back',
@@ -49,22 +43,15 @@ const goBack = captureSnapshot => defineTool({
         inputSchema: z.object({}),
         type: 'readOnly',
     },
-    handle: async (context) => {
-        const tab = await context.ensureTab();
+    handle: async (tab, params, response) => {
         await tab.page.goBack();
-        const code = [
-            `// Navigate back`,
-            `await page.goBack();`,
-        ];
-        return {
-            code,
-            captureSnapshot,
-            waitForNetwork: false,
-        };
+        response.setIncludeSnapshot();
+        response.addCode(`// Navigate back`);
+        response.addCode(`await page.goBack();`);
     },
 });
-const goForward = captureSnapshot => defineTool({
-    capability: 'history',
+const goForward = defineTabTool({
+    capability: 'core',
     schema: {
         name: 'browser_navigate_forward',
         title: 'Go forward',
@@ -72,22 +59,15 @@ const goForward = captureSnapshot => defineTool({
         inputSchema: z.object({}),
         type: 'readOnly',
     },
-    handle: async (context) => {
-        const tab = context.currentTabOrDie();
+    handle: async (tab, params, response) => {
         await tab.page.goForward();
-        const code = [
-            `// Navigate forward`,
-            `await page.goForward();`,
-        ];
-        return {
-            code,
-            captureSnapshot,
-            waitForNetwork: false,
-        };
+        response.setIncludeSnapshot();
+        response.addCode(`// Navigate forward`);
+        response.addCode(`await page.goForward();`);
     },
 });
-export default (captureSnapshot) => [
-    navigate(captureSnapshot),
-    goBack(captureSnapshot),
-    goForward(captureSnapshot),
+export default [
+    navigate,
+    goBack,
+    goForward,
 ];

package/lib/tools/network.js

@@ -14,8 +14,8 @@
  * limitations under the License.
  */
 import { z } from 'zod';
-import { defineTool } from './tool.js';
-const requests = defineTool({
+import { defineTabTool } from './tool.js';
+const requests = defineTabTool({
     capability: 'core',
     schema: {
         name: 'browser_network_requests',
@@ -24,19 +24,9 @@ const requests = defineTool({
         inputSchema: z.object({}),
         type: 'readOnly',
     },
-    handle: async (context) => {
-        const requests = context.currentTabOrDie().requests();
-        const log = [...requests.entries()].map(([request, response]) => renderRequest(request, response)).join('\n');
-        return {
-            code: [`// <internal code to list network requests>`],
-            action: async () => {
-                return {
-                    content: [{ type: 'text', text: log }]
-                };
-            },
-            captureSnapshot: false,
-            waitForNetwork: false,
-        };
+    handle: async (tab, params, response) => {
+        const requests = tab.requests();
+        [...requests.entries()].forEach(([req, res]) => response.addResult(renderRequest(req, res)));
     },
 });
 function renderRequest(request, response) {

package/lib/tools/pdf.js

@@ -14,13 +14,13 @@
  * limitations under the License.
  */
 import { z } from 'zod';
-import { defineTool } from './tool.js';
+import { defineTabTool } from './tool.js';
 import * as javascript from '../javascript.js';
 import { outputFile } from '../config.js';
 const pdfSchema = z.object({
     filename: z.string().optional().describe('File name to save the pdf to. Defaults to `page-{timestamp}.pdf` if not specified.'),
 });
-const pdf = defineTool({
+const pdf = defineTabTool({
     capability: 'pdf',
     schema: {
         name: 'browser_pdf_save',
@@ -29,19 +29,12 @@ const pdf = defineTool({
         inputSchema: pdfSchema,
         type: 'readOnly',
     },
-    handle: async (context, params) => {
-        const tab = context.currentTabOrDie();
-        const fileName = await outputFile(context.config, params.filename ?? `page-${new Date().toISOString()}.pdf`);
-        const code = [
-            `// Save page as ${fileName}`,
-            `await page.pdf(${javascript.formatObject({ path: fileName })});`,
-        ];
-        return {
-            code,
-            action: async () => tab.page.pdf({ path: fileName }).then(() => { }),
-            captureSnapshot: false,
-            waitForNetwork: false,
-        };
+    handle: async (tab, params, response) => {
+        const fileName = await outputFile(tab.context.config, params.filename ?? `page-${new Date().toISOString()}.pdf`);
+        response.addCode(`// Save page as ${fileName}`);
+        response.addCode(`await page.pdf(${javascript.formatObject({ path: fileName })});`);
+        response.addResult(`Saved page as ${fileName}`);
+        await tab.page.pdf({ path: fileName });
     },
 });
 export default [

package/lib/tools/screenshot.js

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 import { z } from 'zod';
-import { defineTool } from './tool.js';
+import { defineTabTool } from './tool.js';
 import * as javascript from '../javascript.js';
 import { outputFile } from '../config.js';
 import { generateLocator } from './utils.js';
@@ -23,13 +23,19 @@ const screenshotSchema = z.object({
     filename: z.string().optional().describe('File name to save the screenshot to. Defaults to `page-{timestamp}.{png|jpeg}` if not specified.'),
     element: z.string().optional().describe('Human-readable element description used to obtain permission to screenshot the element. If not provided, the screenshot will be taken of viewport. If element is provided, ref must be provided too.'),
     ref: z.string().optional().describe('Exact target element reference from the page snapshot. If not provided, the screenshot will be taken of viewport. If ref is provided, element must be provided too.'),
+    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.'),
 }).refine(data => {
     return !!data.element === !!data.ref;
 }, {
     message: 'Both element and ref must be provided or neither.',
     path: ['ref', 'element']
+}).refine(data => {
+    return !(data.fullPage && (data.element || data.ref));
+}, {
+    message: 'fullPage cannot be used with element screenshots.',
+    path: ['fullPage']
 });
-const screenshot = defineTool({
+const screenshot = defineTabTool({
     capability: 'core',
     schema: {
         name: 'browser_take_screenshot',
@@ -38,38 +44,31 @@ const screenshot = defineTool({
         inputSchema: screenshotSchema,
         type: 'readOnly',
     },
-    handle: async (context, params) => {
-        const tab = context.currentTabOrDie();
-        const snapshot = tab.snapshotOrDie();
+    handle: async (tab, params, response) => {
         const fileType = params.raw ? 'png' : 'jpeg';
-        const fileName = await outputFile(context.config, params.filename ?? `page-${new Date().toISOString()}.${fileType}`);
-        const options = { type: fileType, quality: fileType === 'png' ? undefined : 50, scale: 'css', path: fileName };
+        const fileName = await outputFile(tab.context.config, params.filename ?? `page-${new Date().toISOString()}.${fileType}`);
+        const options = {
+            type: fileType,
+            quality: fileType === 'png' ? undefined : 50,
+            scale: 'css',
+            path: fileName,
+            ...(params.fullPage !== undefined && { fullPage: params.fullPage })
+        };
         const isElementScreenshot = params.element && params.ref;
-        const code = [
-            `// Screenshot ${isElementScreenshot ? params.element : 'viewport'} and save it as ${fileName}`,
-        ];
-        const locator = params.ref ? snapshot.refLocator({ element: params.element || '', ref: params.ref }) : null;
+        const screenshotTarget = isElementScreenshot ? params.element : (params.fullPage ? 'full page' : 'viewport');
+        response.addCode(`// Screenshot ${screenshotTarget} and save it as ${fileName}`);
+        // Only get snapshot when element screenshot is needed
+        const locator = params.ref ? await tab.refLocator({ element: params.element || '', ref: params.ref }) : null;
         if (locator)
-            code.push(`await page.${await generateLocator(locator)}.screenshot(${javascript.formatObject(options)});`);
+            response.addCode(`await page.${await generateLocator(locator)}.screenshot(${javascript.formatObject(options)});`);
         else
-            code.push(`await page.screenshot(${javascript.formatObject(options)});`);
-        const includeBase64 = context.clientSupportsImages();
-        const action = async () => {
-            const screenshot = locator ? await locator.screenshot(options) : await tab.page.screenshot(options);
-            return {
-                content: includeBase64 ? [{
-                        type: 'image',
-                        data: screenshot.toString('base64'),
-                        mimeType: fileType === 'png' ? 'image/png' : 'image/jpeg',
-                    }] : []
-            };
-        };
-        return {
-            code,
-            action,
-            captureSnapshot: true,
-            waitForNetwork: false,
-        };
+            response.addCode(`await page.screenshot(${javascript.formatObject(options)});`);
+        const buffer = locator ? await locator.screenshot(options) : await tab.page.screenshot(options);
+        response.addResult(`Took the ${screenshotTarget} screenshot and saved it as ${fileName}`);
+        response.addImage({
+            contentType: fileType === 'png' ? 'image/png' : 'image/jpeg',
+            data: buffer
+        });
     }
 });
 export default [

package/lib/tools/snapshot.js

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 import { z } from 'zod';
-import { defineTool } from './tool.js';
+import { defineTabTool, defineTool } from './tool.js';
 import * as javascript from '../javascript.js';
 import { generateLocator } from './utils.js';
 const snapshot = defineTool({
@@ -26,23 +26,20 @@ const snapshot = defineTool({
         inputSchema: z.object({}),
         type: 'readOnly',
     },
-    handle: async (context) => {
+    handle: async (context, params, response) => {
         await context.ensureTab();
-        return {
-            code: [`// <internal code to capture accessibility snapshot>`],
-            captureSnapshot: true,
-            waitForNetwork: false,
-        };
+        response.setIncludeSnapshot();
     },
 });
-const elementSchema = z.object({
+export const elementSchema = z.object({
     element: z.string().describe('Human-readable element description used to obtain permission to interact with the element'),
     ref: z.string().describe('Exact target element reference from the page snapshot'),
 });
 const clickSchema = elementSchema.extend({
     doubleClick: z.boolean().optional().describe('Whether to perform a double click instead of a single click'),
+    button: z.enum(['left', 'right', 'middle']).optional().describe('Button to click, defaults to left'),
 });
-const click = defineTool({
+const click = defineTabTool({
     capability: 'core',
     schema: {
         name: 'browser_click',
@@ -51,27 +48,28 @@ const click = defineTool({
         inputSchema: clickSchema,
         type: 'destructive',
     },
-    handle: async (context, params) => {
-        const tab = context.currentTabOrDie();
-        const locator = tab.snapshotOrDie().refLocator(params);
-        const code = [];
+    handle: async (tab, params, response) => {
+        response.setIncludeSnapshot();
+        const locator = await tab.refLocator(params);
+        const button = params.button;
+        const buttonAttr = button ? `{ button: '${button}' }` : '';
         if (params.doubleClick) {
-            code.push(`// Double click ${params.element}`);
-            code.push(`await page.${await generateLocator(locator)}.dblclick();`);
+            response.addCode(`// Double click ${params.element}`);
+            response.addCode(`await page.${await generateLocator(locator)}.dblclick(${buttonAttr});`);
         }
         else {
-            code.push(`// Click ${params.element}`);
-            code.push(`await page.${await generateLocator(locator)}.click();`);
+            response.addCode(`// Click ${params.element}`);
+            response.addCode(`await page.${await generateLocator(locator)}.click(${buttonAttr});`);
         }
-        return {
-            code,
-            action: () => params.doubleClick ? locator.dblclick() : locator.click(),
-            captureSnapshot: true,
-            waitForNetwork: true,
-        };
+        await tab.waitForCompletion(async () => {
+            if (params.doubleClick)
+                await locator.dblclick({ button });
+            else
+                await locator.click({ button });
+        });
     },
 });
-const drag = defineTool({
+const drag = defineTabTool({
     capability: 'core',
     schema: {
         name: 'browser_drag',
@@ -85,23 +83,19 @@ const drag = defineTool({
         }),
         type: 'destructive',
     },
-    handle: async (context, params) => {
-        const snapshot = context.currentTabOrDie().snapshotOrDie();
-        const startLocator = snapshot.refLocator({ ref: params.startRef, element: params.startElement });
-        const endLocator = snapshot.refLocator({ ref: params.endRef, element: params.endElement });
-        const code = [
-            `// Drag ${params.startElement} to ${params.endElement}`,
-            `await page.${await generateLocator(startLocator)}.dragTo(page.${await generateLocator(endLocator)});`
-        ];
-        return {
-            code,
-            action: () => startLocator.dragTo(endLocator),
-            captureSnapshot: true,
-            waitForNetwork: true,
-        };
+    handle: async (tab, params, response) => {
+        response.setIncludeSnapshot();
+        const [startLocator, endLocator] = await tab.refLocators([
+            { ref: params.startRef, element: params.startElement },
+            { ref: params.endRef, element: params.endElement },
+        ]);
+        await tab.waitForCompletion(async () => {
+            await startLocator.dragTo(endLocator);
+        });
+        response.addCode(`await page.${await generateLocator(startLocator)}.dragTo(page.${await generateLocator(endLocator)});`);
     },
 });
-const hover = defineTool({
+const hover = defineTabTool({
     capability: 'core',
     schema: {
         name: 'browser_hover',
@@ -110,67 +104,19 @@ const hover = defineTool({
         inputSchema: elementSchema,
         type: 'readOnly',
     },
-    handle: async (context, params) => {
-        const snapshot = context.currentTabOrDie().snapshotOrDie();
-        const locator = snapshot.refLocator(params);
-        const code = [
-            `// Hover over ${params.element}`,
-            `await page.${await generateLocator(locator)}.hover();`
-        ];
-        return {
-            code,
-            action: () => locator.hover(),
-            captureSnapshot: true,
-            waitForNetwork: true,
-        };
-    },
-});
-const typeSchema = elementSchema.extend({
-    text: z.string().describe('Text to type into the element'),
-    submit: z.boolean().optional().describe('Whether to submit entered text (press Enter after)'),
-    slowly: z.boolean().optional().describe('Whether to type one character at a time. Useful for triggering key handlers in the page. By default entire text is filled in at once.'),
-});
-const type = defineTool({
-    capability: 'core',
-    schema: {
-        name: 'browser_type',
-        title: 'Type text',
-        description: 'Type text into editable element',
-        inputSchema: typeSchema,
-        type: 'destructive',
-    },
-    handle: async (context, params) => {
-        const snapshot = context.currentTabOrDie().snapshotOrDie();
-        const locator = snapshot.refLocator(params);
-        const code = [];
-        const steps = [];
-        if (params.slowly) {
-            code.push(`// Press "${params.text}" sequentially into "${params.element}"`);
-            code.push(`await page.${await generateLocator(locator)}.pressSequentially(${javascript.quote(params.text)});`);
-            steps.push(() => locator.pressSequentially(params.text));
-        }
-        else {
-            code.push(`// Fill "${params.text}" into "${params.element}"`);
-            code.push(`await page.${await generateLocator(locator)}.fill(${javascript.quote(params.text)});`);
-            steps.push(() => locator.fill(params.text));
-        }
-        if (params.submit) {
-            code.push(`// Submit text`);
-            code.push(`await page.${await generateLocator(locator)}.press('Enter');`);
-            steps.push(() => locator.press('Enter'));
-        }
-        return {
-            code,
-            action: () => steps.reduce((acc, step) => acc.then(step), Promise.resolve()),
-            captureSnapshot: true,
-            waitForNetwork: true,
-        };
+    handle: async (tab, params, response) => {
+        response.setIncludeSnapshot();
+        const locator = await tab.refLocator(params);
+        response.addCode(`await page.${await generateLocator(locator)}.hover();`);
+        await tab.waitForCompletion(async () => {
+            await locator.hover();
+        });
     },
 });
 const selectOptionSchema = elementSchema.extend({
     values: z.array(z.string()).describe('Array of values to select in the dropdown. This can be a single value or multiple values.'),
 });
-const selectOption = defineTool({
+const selectOption = defineTabTool({
     capability: 'core',
     schema: {
         name: 'browser_select_option',
@@ -179,19 +125,14 @@ const selectOption = defineTool({
         inputSchema: selectOptionSchema,
         type: 'destructive',
     },
-    handle: async (context, params) => {
-        const snapshot = context.currentTabOrDie().snapshotOrDie();
-        const locator = snapshot.refLocator(params);
-        const code = [
-            `// Select options [${params.values.join(', ')}] in ${params.element}`,
-            `await page.${await generateLocator(locator)}.selectOption(${javascript.formatObject(params.values)});`
-        ];
-        return {
-            code,
-            action: () => locator.selectOption(params.values).then(() => { }),
-            captureSnapshot: true,
-            waitForNetwork: true,
-        };
+    handle: async (tab, params, response) => {
+        response.setIncludeSnapshot();
+        const locator = await tab.refLocator(params);
+        response.addCode(`// Select options [${params.values.join(', ')}] in ${params.element}`);
+        response.addCode(`await page.${await generateLocator(locator)}.selectOption(${javascript.formatObject(params.values)});`);
+        await tab.waitForCompletion(async () => {
+            await locator.selectOption(params.values);
+        });
     },
 });
 export default [
@@ -199,6 +140,5 @@ export default [
     click,
     drag,
     hover,
-    type,
     selectOption,
 ];