@playwright/mcp 0.0.31 → 0.0.32

package/lib/tab.js

@@ -13,18 +13,25 @@
  * 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';
+import { EventEmitter } from 'events';
+import { callOnPageNoTrace, waitForCompletion } from './tools/utils.js';
 import { logUnhandledError } from './log.js';
-export class Tab {
+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;
@@ -34,19 +41,56 @@ export class Tab {
         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;
@@ -81,36 +125,98 @@ 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;
     }
-    async captureSnapshot() {
-        this._snapshot = await PageSnapshot.create(this.page);
+    _takeRecentConsoleMarkdown() {
+        if (!this._recentConsoleMessages.length)
+            return [];
+        const result = this._recentConsoleMessages.map(message => {
+            return `- ${trim(message.toString(), 100)}`;
+        });
+        return [`### New console messages`, ...result, ''];
     }
-    takeRecentConsoleMessages() {
-        const result = this._recentConsoleMessages.slice();
-        this._recentConsoleMessages.length = 0;
+    _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() {
+        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 {
@@ -133,3 +239,8 @@ function pageErrorToConsoleMessage(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 = defineTool({
+const resize = defineTabTool({
     capability: 'core',
     schema: {
         name: 'browser_resize',
@@ -45,21 +42,12 @@ const resize = 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: true,
-            waitForNetwork: true
-        };
+        });
     },
 });
 export default [

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.toString()).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 = defineTool({
+import { defineTabTool } from './tool.js';
+const handleDialog = defineTabTool({
     capability: 'core',
     schema: {
         name: 'browser_handle_dialog',
@@ -27,23 +27,18 @@ const handleDialog = 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: true,
-            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',
 });

package/lib/tools/evaluate.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 { generateLocator } from './utils.js';
 const evaluateSchema = z.object({
@@ -22,7 +22,7 @@ const evaluateSchema = z.object({
     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 = defineTool({
+const evaluate = defineTabTool({
     capability: 'core',
     schema: {
         name: 'browser_evaluate',
@@ -31,30 +31,21 @@ const evaluate = defineTool({
         inputSchema: evaluateSchema,
         type: 'destructive',
     },
-    handle: async (context, params) => {
-        const tab = context.currentTabOrDie();
-        const code = [];
+    handle: async (tab, params, response) => {
+        response.setIncludeSnapshot();
         let locator;
         if (params.ref && params.element) {
-            const snapshot = tab.snapshotOrDie();
-            locator = snapshot.refLocator({ ref: params.ref, element: params.element });
-            code.push(`await page.${await generateLocator(locator)}.evaluate(${javascript.quote(params.function)});`);
+            locator = await tab.refLocator({ ref: params.ref, element: params.element });
+            response.addCode(`await page.${await generateLocator(locator)}.evaluate(${javascript.quote(params.function)});`);
         }
         else {
-            code.push(`await page.evaluate(${javascript.quote(params.function)});`);
+            response.addCode(`await page.evaluate(${javascript.quote(params.function)});`);
         }
-        return {
-            code,
-            action: async () => {
-                const receiver = locator ?? tab.page;
-                const result = await receiver._evaluateFunction(params.function);
-                return {
-                    content: [{ type: 'text', text: '- Result: ' + (JSON.stringify(result, null, 2) || 'undefined') }],
-                };
-            },
-            captureSnapshot: false,
-            waitForNetwork: false,
-        };
+        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 [

package/lib/tools/files.js

@@ -14,8 +14,8 @@
  * limitations under the License.
  */
 import { z } from 'zod';
-import { defineTool } from './tool.js';
-const uploadFile = defineTool({
+import { defineTabTool } from './tool.js';
+const uploadFile = defineTabTool({
     capability: 'core',
     schema: {
         name: 'browser_file_upload',
@@ -26,23 +26,17 @@ const uploadFile = 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: true,
-            waitForNetwork: true,
-        };
+        });
     },
     clearsModalState: 'fileChooser',
 });

package/lib/tools/install.js

@@ -15,9 +15,9 @@
  */
 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: 'core-install',
     schema: {
@@ -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,11 +14,11 @@
  * limitations under the License.
  */
 import { z } from 'zod';
-import { defineTool } from './tool.js';
+import { defineTabTool } from './tool.js';
 import { elementSchema } from './snapshot.js';
 import { generateLocator } from './utils.js';
 import * as javascript from '../javascript.js';
-const pressKey = defineTool({
+const pressKey = defineTabTool({
     capability: 'core',
     schema: {
         name: 'browser_press_key',
@@ -29,19 +29,13 @@ const pressKey = 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: true,
-            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);
+        });
     },
 });
 const typeSchema = elementSchema.extend({
@@ -49,7 +43,7 @@ const typeSchema = elementSchema.extend({
     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({
+const type = defineTabTool({
     capability: 'core',
     schema: {
         name: 'browser_type',
@@ -58,32 +52,26 @@ const type = defineTool({
         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) => {
+        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 [