@playwright/mcp 0.0.30 → 0.0.32

package/lib/tab.js

@@ -13,41 +13,93 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { PageSnapshot } from './pageSnapshot.js';
-import { callOnPageNoTrace } from './tools/utils.js';
-export class Tab {
+import { EventEmitter } from 'events';
+import { callOnPageNoTrace, waitForCompletion } from './tools/utils.js';
+import { logUnhandledError } from './log.js';
+import { ManualPromise } from './manualPromise.js';
+import { outputFile } from './config.js';
+export const TabEvents = {
+    modalState: 'modalState'
+};
+export class Tab extends EventEmitter {
     context;
     page;
     _consoleMessages = [];
+    _recentConsoleMessages = [];
     _requests = new Map();
-    _snapshot;
     _onPageClose;
+    _modalStates = [];
+    _downloads = [];
     constructor(context, page, onPageClose) {
+        super();
         this.context = context;
         this.page = page;
         this._onPageClose = onPageClose;
-        page.on('console', event => this._consoleMessages.push(event));
+        page.on('console', event => this._handleConsoleMessage(messageToConsoleMessage(event)));
+        page.on('pageerror', error => this._handleConsoleMessage(pageErrorToConsoleMessage(error)));
         page.on('request', request => this._requests.set(request, null));
         page.on('response', response => this._requests.set(response.request(), response));
         page.on('close', () => this._onClose());
         page.on('filechooser', chooser => {
-            this.context.setModalState({
+            this.setModalState({
                 type: 'fileChooser',
                 description: 'File chooser',
                 fileChooser: chooser,
-            }, this);
+            });
         });
-        page.on('dialog', dialog => this.context.dialogShown(this, dialog));
+        page.on('dialog', dialog => this._dialogShown(dialog));
         page.on('download', download => {
-            void this.context.downloadStarted(this, download);
+            void this._downloadStarted(download);
         });
         page.setDefaultNavigationTimeout(60000);
         page.setDefaultTimeout(5000);
     }
+    modalStates() {
+        return this._modalStates;
+    }
+    setModalState(modalState) {
+        this._modalStates.push(modalState);
+        this.emit(TabEvents.modalState, modalState);
+    }
+    clearModalState(modalState) {
+        this._modalStates = this._modalStates.filter(state => state !== modalState);
+    }
+    modalStatesMarkdown() {
+        const result = ['### Modal state'];
+        if (this._modalStates.length === 0)
+            result.push('- There is no modal state present');
+        for (const state of this._modalStates) {
+            const tool = this.context.tools.filter(tool => 'clearsModalState' in tool).find(tool => tool.clearsModalState === state.type);
+            result.push(`- [${state.description}]: can be handled by the "${tool?.schema.name}" tool`);
+        }
+        return result;
+    }
+    _dialogShown(dialog) {
+        this.setModalState({
+            type: 'dialog',
+            description: `"${dialog.type()}" dialog with message "${dialog.message()}"`,
+            dialog,
+        });
+    }
+    async _downloadStarted(download) {
+        const entry = {
+            download,
+            finished: false,
+            outputFile: await outputFile(this.context.config, download.suggestedFilename())
+        };
+        this._downloads.push(entry);
+        await download.saveAs(entry.outputFile);
+        entry.finished = true;
+    }
     _clearCollectedArtifacts() {
         this._consoleMessages.length = 0;
+        this._recentConsoleMessages.length = 0;
         this._requests.clear();
     }
+    _handleConsoleMessage(message) {
+        this._consoleMessages.push(message);
+        this._recentConsoleMessages.push(message);
+    }
     _onClose() {
         this._clearCollectedArtifacts();
         this._onPageClose(this);
@@ -56,11 +108,11 @@ export class Tab {
         return await callOnPageNoTrace(this.page, page => page.title());
     }
     async waitForLoadState(state, options) {
-        await callOnPageNoTrace(this.page, page => page.waitForLoadState(state, options).catch(() => { }));
+        await callOnPageNoTrace(this.page, page => page.waitForLoadState(state, options).catch(logUnhandledError));
     }
     async navigate(url) {
         this._clearCollectedArtifacts();
-        const downloadEvent = callOnPageNoTrace(this.page, page => page.waitForEvent('download').catch(() => { }));
+        const downloadEvent = callOnPageNoTrace(this.page, page => page.waitForEvent('download').catch(logUnhandledError));
         try {
             await this.page.goto(url, { waitUntil: 'domcontentloaded' });
         }
@@ -73,29 +125,122 @@ export class Tab {
             // on chromium, the download event is fired *after* page.goto rejects, so we wait a lil bit
             const download = await Promise.race([
                 downloadEvent,
-                new Promise(resolve => setTimeout(resolve, 1000)),
+                new Promise(resolve => setTimeout(resolve, 3000)),
             ]);
             if (!download)
                 throw e;
+            // Make sure other "download" listeners are notified first.
+            await new Promise(resolve => setTimeout(resolve, 500));
+            return;
         }
         // Cap load event to 5 seconds, the page is operational at this point.
         await this.waitForLoadState('load', { timeout: 5000 });
     }
-    hasSnapshot() {
-        return !!this._snapshot;
-    }
-    snapshotOrDie() {
-        if (!this._snapshot)
-            throw new Error('No snapshot available');
-        return this._snapshot;
-    }
     consoleMessages() {
         return this._consoleMessages;
     }
     requests() {
         return this._requests;
     }
+    _takeRecentConsoleMarkdown() {
+        if (!this._recentConsoleMessages.length)
+            return [];
+        const result = this._recentConsoleMessages.map(message => {
+            return `- ${trim(message.toString(), 100)}`;
+        });
+        return [`### New console messages`, ...result, ''];
+    }
+    _listDownloadsMarkdown() {
+        if (!this._downloads.length)
+            return [];
+        const result = ['### Downloads'];
+        for (const entry of this._downloads) {
+            if (entry.finished)
+                result.push(`- Downloaded file ${entry.download.suggestedFilename()} to ${entry.outputFile}`);
+            else
+                result.push(`- Downloading file ${entry.download.suggestedFilename()} ...`);
+        }
+        result.push('');
+        return result;
+    }
     async captureSnapshot() {
-        this._snapshot = await PageSnapshot.create(this.page);
+        const result = [];
+        if (this.modalStates().length) {
+            result.push(...this.modalStatesMarkdown());
+            return result.join('\n');
+        }
+        result.push(...this._takeRecentConsoleMarkdown());
+        result.push(...this._listDownloadsMarkdown());
+        await this._raceAgainstModalStates(async () => {
+            const snapshot = await this.page._snapshotForAI();
+            result.push(`### Page state`, `- Page URL: ${this.page.url()}`, `- Page Title: ${await this.page.title()}`, `- Page Snapshot:`, '```yaml', snapshot, '```');
+        });
+        return result.join('\n');
+    }
+    _javaScriptBlocked() {
+        return this._modalStates.some(state => state.type === 'dialog');
+    }
+    async _raceAgainstModalStates(action) {
+        if (this.modalStates().length)
+            return this.modalStates()[0];
+        const promise = new ManualPromise();
+        const listener = (modalState) => promise.resolve(modalState);
+        this.once(TabEvents.modalState, listener);
+        return await Promise.race([
+            action().then(() => {
+                this.off(TabEvents.modalState, listener);
+                return undefined;
+            }),
+            promise,
+        ]);
+    }
+    async waitForCompletion(callback) {
+        await this._raceAgainstModalStates(() => waitForCompletion(this, callback));
+    }
+    async refLocator(params) {
+        return (await this.refLocators([params]))[0];
+    }
+    async refLocators(params) {
+        const snapshot = await this.page._snapshotForAI();
+        return params.map(param => {
+            if (!snapshot.includes(`[ref=${param.ref}]`))
+                throw new Error(`Ref ${param.ref} not found in the current page snapshot. Try capturing new snapshot.`);
+            return this.page.locator(`aria-ref=${param.ref}`).describe(param.element);
+        });
     }
+    async waitForTimeout(time) {
+        if (this._javaScriptBlocked()) {
+            await new Promise(f => setTimeout(f, time));
+            return;
+        }
+        await callOnPageNoTrace(this.page, page => {
+            return page.evaluate(() => new Promise(f => setTimeout(f, 1000)));
+        });
+    }
+}
+function messageToConsoleMessage(message) {
+    return {
+        type: message.type(),
+        text: message.text(),
+        toString: () => `[${message.type().toUpperCase()}] ${message.text()} @ ${message.location().url}:${message.location().lineNumber}`,
+    };
+}
+function pageErrorToConsoleMessage(errorOrValue) {
+    if (errorOrValue instanceof Error) {
+        return {
+            type: undefined,
+            text: errorOrValue.message,
+            toString: () => errorOrValue.stack || errorOrValue.message,
+        };
+    }
+    return {
+        type: undefined,
+        text: String(errorOrValue),
+        toString: () => String(errorOrValue),
+    };
+}
+function trim(text, maxLength) {
+    if (text.length <= maxLength)
+        return text;
+    return text.slice(0, maxLength) + '...';
 }

package/lib/tools/common.js

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 import { z } from 'zod';
-import { defineTool } from './tool.js';
+import { defineTabTool, defineTool } from './tool.js';
 const close = defineTool({
     capability: 'core',
     schema: {
@@ -24,16 +24,13 @@ const close = defineTool({
         inputSchema: z.object({}),
         type: 'readOnly',
     },
-    handle: async (context) => {
-        await context.close();
-        return {
-            code: [`await page.close()`],
-            captureSnapshot: false,
-            waitForNetwork: false,
-        };
+    handle: async (context, params, response) => {
+        await context.closeBrowserContext();
+        response.setIncludeTabs();
+        response.addCode(`await page.close()`);
     },
 });
-const resize = captureSnapshot => defineTool({
+const resize = defineTabTool({
     capability: 'core',
     schema: {
         name: 'browser_resize',
@@ -45,24 +42,15 @@ const resize = captureSnapshot => defineTool({
         }),
         type: 'readOnly',
     },
-    handle: async (context, params) => {
-        const tab = context.currentTabOrDie();
-        const code = [
-            `// Resize browser window to ${params.width}x${params.height}`,
-            `await page.setViewportSize({ width: ${params.width}, height: ${params.height} });`
-        ];
-        const action = async () => {
+    handle: async (tab, params, response) => {
+        response.addCode(`// Resize browser window to ${params.width}x${params.height}`);
+        response.addCode(`await page.setViewportSize({ width: ${params.width}, height: ${params.height} });`);
+        await tab.waitForCompletion(async () => {
             await tab.page.setViewportSize({ width: params.width, height: params.height });
-        };
-        return {
-            code,
-            action,
-            captureSnapshot,
-            waitForNetwork: true
-        };
+        });
     },
 });
-export default (captureSnapshot) => [
+export default [
     close,
-    resize(captureSnapshot)
+    resize
 ];

package/lib/tools/console.js

@@ -14,8 +14,8 @@
  * limitations under the License.
  */
 import { z } from 'zod';
-import { defineTool } from './tool.js';
-const console = defineTool({
+import { defineTabTool } from './tool.js';
+const console = defineTabTool({
     capability: 'core',
     schema: {
         name: 'browser_console_messages',
@@ -24,19 +24,8 @@ const console = defineTool({
         inputSchema: z.object({}),
         type: 'readOnly',
     },
-    handle: async (context) => {
-        const messages = context.currentTabOrDie().consoleMessages();
-        const log = messages.map(message => `[${message.type().toUpperCase()}] ${message.text()}`).join('\n');
-        return {
-            code: [`// <internal code to get console messages>`],
-            action: async () => {
-                return {
-                    content: [{ type: 'text', text: log }]
-                };
-            },
-            captureSnapshot: false,
-            waitForNetwork: false,
-        };
+    handle: async (tab, params, response) => {
+        tab.consoleMessages().map(message => response.addResult(message.toString()));
     },
 });
 export default [

package/lib/tools/dialogs.js

@@ -14,8 +14,8 @@
  * limitations under the License.
  */
 import { z } from 'zod';
-import { defineTool } from './tool.js';
-const handleDialog = captureSnapshot => defineTool({
+import { defineTabTool } from './tool.js';
+const handleDialog = defineTabTool({
     capability: 'core',
     schema: {
         name: 'browser_handle_dialog',
@@ -27,26 +27,21 @@ const handleDialog = captureSnapshot => defineTool({
         }),
         type: 'destructive',
     },
-    handle: async (context, params) => {
-        const dialogState = context.modalStates().find(state => state.type === 'dialog');
+    handle: async (tab, params, response) => {
+        response.setIncludeSnapshot();
+        const dialogState = tab.modalStates().find(state => state.type === 'dialog');
         if (!dialogState)
             throw new Error('No dialog visible');
-        if (params.accept)
-            await dialogState.dialog.accept(params.promptText);
-        else
-            await dialogState.dialog.dismiss();
-        context.clearModalState(dialogState);
-        const code = [
-            `// <internal code to handle "${dialogState.dialog.type()}" dialog>`,
-        ];
-        return {
-            code,
-            captureSnapshot,
-            waitForNetwork: false,
-        };
+        tab.clearModalState(dialogState);
+        await tab.waitForCompletion(async () => {
+            if (params.accept)
+                await dialogState.dialog.accept(params.promptText);
+            else
+                await dialogState.dialog.dismiss();
+        });
     },
     clearsModalState: 'dialog',
 });
-export default (captureSnapshot) => [
-    handleDialog(captureSnapshot),
+export default [
+    handleDialog,
 ];

package/lib/tools/evaluate.js

@@ -0,0 +1,53 @@
+/**
+ * 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';
+import * as javascript from '../javascript.js';
+import { generateLocator } from './utils.js';
+const evaluateSchema = z.object({
+    function: z.string().describe('() => { /* code */ } or (element) => { /* code */ } when element is provided'),
+    element: z.string().optional().describe('Human-readable element description used to obtain permission to interact with the element'),
+    ref: z.string().optional().describe('Exact target element reference from the page snapshot'),
+});
+const evaluate = defineTabTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_evaluate',
+        title: 'Evaluate JavaScript',
+        description: 'Evaluate JavaScript expression on page or element',
+        inputSchema: evaluateSchema,
+        type: 'destructive',
+    },
+    handle: async (tab, params, response) => {
+        response.setIncludeSnapshot();
+        let locator;
+        if (params.ref && params.element) {
+            locator = await tab.refLocator({ ref: params.ref, element: params.element });
+            response.addCode(`await page.${await generateLocator(locator)}.evaluate(${javascript.quote(params.function)});`);
+        }
+        else {
+            response.addCode(`await page.evaluate(${javascript.quote(params.function)});`);
+        }
+        await tab.waitForCompletion(async () => {
+            const receiver = locator ?? tab.page;
+            const result = await receiver._evaluateFunction(params.function);
+            response.addResult(JSON.stringify(result, null, 2) || 'undefined');
+        });
+    },
+});
+export default [
+    evaluate,
+];

package/lib/tools/files.js

@@ -14,9 +14,9 @@
  * limitations under the License.
  */
 import { z } from 'zod';
-import { defineTool } from './tool.js';
-const uploadFile = captureSnapshot => defineTool({
-    capability: 'files',
+import { defineTabTool } from './tool.js';
+const uploadFile = defineTabTool({
+    capability: 'core',
     schema: {
         name: 'browser_file_upload',
         title: 'Upload files',
@@ -26,26 +26,20 @@ const uploadFile = captureSnapshot => defineTool({
         }),
         type: 'destructive',
     },
-    handle: async (context, params) => {
-        const modalState = context.modalStates().find(state => state.type === 'fileChooser');
+    handle: async (tab, params, response) => {
+        response.setIncludeSnapshot();
+        const modalState = tab.modalStates().find(state => state.type === 'fileChooser');
         if (!modalState)
             throw new Error('No file chooser visible');
-        const code = [
-            `// <internal code to chose files ${params.paths.join(', ')}`,
-        ];
-        const action = async () => {
+        response.addCode(`// Select files for upload`);
+        response.addCode(`await fileChooser.setFiles(${JSON.stringify(params.paths)})`);
+        tab.clearModalState(modalState);
+        await tab.waitForCompletion(async () => {
             await modalState.fileChooser.setFiles(params.paths);
-            context.clearModalState(modalState);
-        };
-        return {
-            code,
-            action,
-            captureSnapshot,
-            waitForNetwork: true,
-        };
+        });
     },
     clearsModalState: 'fileChooser',
 });
-export default (captureSnapshot) => [
-    uploadFile(captureSnapshot),
+export default [
+    uploadFile,
 ];

package/lib/tools/install.js

@@ -15,11 +15,11 @@
  */
 import { fork } from 'child_process';
 import path from 'path';
+import { fileURLToPath } from 'url';
 import { z } from 'zod';
 import { defineTool } from './tool.js';
-import { fileURLToPath } from 'node:url';
 const install = defineTool({
-    capability: 'install',
+    capability: 'core-install',
     schema: {
         name: 'browser_install',
         title: 'Install the browser specified in the config',
@@ -27,7 +27,7 @@ const install = defineTool({
         inputSchema: z.object({}),
         type: 'destructive',
     },
-    handle: async (context) => {
+    handle: async (context, params, response) => {
         const channel = context.config.browser?.launchOptions?.channel ?? context.config.browser?.browserName ?? 'chrome';
         const cliUrl = import.meta.resolve('playwright/package.json');
         const cliPath = path.join(fileURLToPath(cliUrl), '..', 'cli.js');
@@ -45,11 +45,7 @@ const install = defineTool({
                     reject(new Error(`Failed to install browser: ${output.join('')}`));
             });
         });
-        return {
-            code: [`// Browser ${channel} installed`],
-            captureSnapshot: false,
-            waitForNetwork: false,
-        };
+        response.setIncludeTabs();
     },
 });
 export default [

package/lib/tools/keyboard.js

@@ -14,8 +14,11 @@
  * limitations under the License.
  */
 import { z } from 'zod';
-import { defineTool } from './tool.js';
-const pressKey = captureSnapshot => defineTool({
+import { defineTabTool } from './tool.js';
+import { elementSchema } from './snapshot.js';
+import { generateLocator } from './utils.js';
+import * as javascript from '../javascript.js';
+const pressKey = defineTabTool({
     capability: 'core',
     schema: {
         name: 'browser_press_key',
@@ -26,21 +29,52 @@ const pressKey = captureSnapshot => defineTool({
         }),
         type: 'destructive',
     },
-    handle: async (context, params) => {
-        const tab = context.currentTabOrDie();
-        const code = [
-            `// Press ${params.key}`,
-            `await page.keyboard.press('${params.key}');`,
-        ];
-        const action = () => tab.page.keyboard.press(params.key);
-        return {
-            code,
-            action,
-            captureSnapshot,
-            waitForNetwork: true
-        };
+    handle: async (tab, params, response) => {
+        response.setIncludeSnapshot();
+        response.addCode(`// Press ${params.key}`);
+        response.addCode(`await page.keyboard.press('${params.key}');`);
+        await tab.waitForCompletion(async () => {
+            await tab.page.keyboard.press(params.key);
+        });
     },
 });
-export default (captureSnapshot) => [
-    pressKey(captureSnapshot),
+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 = defineTabTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_type',
+        title: 'Type text',
+        description: 'Type text into editable element',
+        inputSchema: typeSchema,
+        type: 'destructive',
+    },
+    handle: async (tab, params, response) => {
+        const locator = await tab.refLocator(params);
+        await tab.waitForCompletion(async () => {
+            if (params.slowly) {
+                response.setIncludeSnapshot();
+                response.addCode(`// Press "${params.text}" sequentially into "${params.element}"`);
+                response.addCode(`await page.${await generateLocator(locator)}.pressSequentially(${javascript.quote(params.text)});`);
+                await locator.pressSequentially(params.text);
+            }
+            else {
+                response.addCode(`// Fill "${params.text}" into "${params.element}"`);
+                response.addCode(`await page.${await generateLocator(locator)}.fill(${javascript.quote(params.text)});`);
+                await locator.fill(params.text);
+            }
+            if (params.submit) {
+                response.setIncludeSnapshot();
+                response.addCode(`await page.${await generateLocator(locator)}.press('Enter');`);
+                await locator.press('Enter');
+            }
+        });
+    },
+});
+export default [
+    pressKey,
+    type,
 ];