@playwright/mcp 0.0.34 → 0.0.35-alpha-2025-08-28

package/lib/tools/verify.js

@@ -0,0 +1,137 @@
+/**
+ * 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 '../utils/codegen.js';
+import { generateLocator } from './utils.js';
+const verifyElement = defineTabTool({
+    capability: 'verify',
+    schema: {
+        name: 'browser_verify_element_visible',
+        title: 'Verify element visible',
+        description: 'Verify element is visible on the page',
+        inputSchema: z.object({
+            role: z.string().describe('ROLE of the element. Can be found in the snapshot like this: \`- {ROLE} "Accessible Name":\`'),
+            accessibleName: z.string().describe('ACCESSIBLE_NAME of the element. Can be found in the snapshot like this: \`- role "{ACCESSIBLE_NAME}"\`'),
+        }),
+        type: 'readOnly',
+    },
+    handle: async (tab, params, response) => {
+        const locator = tab.page.getByRole(params.role, { name: params.accessibleName });
+        if (await locator.count() === 0) {
+            response.addError(`Element with role "${params.role}" and accessible name "${params.accessibleName}" not found`);
+            return;
+        }
+        response.addCode(`await expect(page.getByRole(${javascript.escapeWithQuotes(params.role)}, { name: ${javascript.escapeWithQuotes(params.accessibleName)} })).toBeVisible();`);
+        response.addResult('Done');
+    },
+});
+const verifyText = defineTabTool({
+    capability: 'verify',
+    schema: {
+        name: 'browser_verify_text_visible',
+        title: 'Verify text visible',
+        description: `Verify text is visible on the page. Prefer ${verifyElement.schema.name} if possible.`,
+        inputSchema: z.object({
+            text: z.string().describe('TEXT to verify. Can be found in the snapshot like this: \`- role "Accessible Name": {TEXT}\` or like this: \`- text: {TEXT}\`'),
+        }),
+        type: 'readOnly',
+    },
+    handle: async (tab, params, response) => {
+        const locator = tab.page.getByText(params.text).filter({ visible: true });
+        if (await locator.count() === 0) {
+            response.addError('Text not found');
+            return;
+        }
+        response.addCode(`await expect(page.getByText(${javascript.escapeWithQuotes(params.text)})).toBeVisible();`);
+        response.addResult('Done');
+    },
+});
+const verifyList = defineTabTool({
+    capability: 'verify',
+    schema: {
+        name: 'browser_verify_list_visible',
+        title: 'Verify list visible',
+        description: 'Verify list is visible on the page',
+        inputSchema: z.object({
+            element: z.string().describe('Human-readable list description'),
+            ref: z.string().describe('Exact target element reference that points to the list'),
+            items: z.array(z.string()).describe('Items to verify'),
+        }),
+        type: 'readOnly',
+    },
+    handle: async (tab, params, response) => {
+        const locator = await tab.refLocator({ ref: params.ref, element: params.element });
+        const itemTexts = [];
+        for (const item of params.items) {
+            const itemLocator = locator.getByText(item);
+            if (await itemLocator.count() === 0) {
+                response.addError(`Item "${item}" not found`);
+                return;
+            }
+            itemTexts.push((await itemLocator.textContent()));
+        }
+        const ariaSnapshot = `\`
+- list:
+${itemTexts.map(t => `  - text: ${javascript.escapeWithQuotes(t, '"')}`).join('\n')}
+\``;
+        response.addCode(`await expect(page.locator('body')).toMatchAriaSnapshot(${ariaSnapshot});`);
+        response.addResult('Done');
+    },
+});
+const verifyValue = defineTabTool({
+    capability: 'verify',
+    schema: {
+        name: 'browser_verify_value',
+        title: 'Verify value',
+        description: 'Verify element value',
+        inputSchema: z.object({
+            type: z.enum(['textbox', 'checkbox', 'radio', 'combobox', 'slider']).describe('Type of the element'),
+            element: z.string().describe('Human-readable element description'),
+            ref: z.string().describe('Exact target element reference that points to the element'),
+            value: z.string().describe('Value to verify. For checkbox, use "true" or "false".'),
+        }),
+        type: 'readOnly',
+    },
+    handle: async (tab, params, response) => {
+        const locator = await tab.refLocator({ ref: params.ref, element: params.element });
+        const locatorSource = `page.${await generateLocator(locator)}`;
+        if (params.type === 'textbox' || params.type === 'slider' || params.type === 'combobox') {
+            const value = await locator.inputValue();
+            if (value !== params.value) {
+                response.addError(`Expected value "${params.value}", but got "${value}"`);
+                return;
+            }
+            response.addCode(`await expect(${locatorSource}).toHaveValue(${javascript.quote(params.value)});`);
+        }
+        else if (params.type === 'checkbox' || params.type === 'radio') {
+            const value = await locator.isChecked();
+            if (value !== (params.value === 'true')) {
+                response.addError(`Expected value "${params.value}", but got "${value}"`);
+                return;
+            }
+            const matcher = value ? 'toBeChecked' : 'not.toBeChecked';
+            response.addCode(`await expect(${locatorSource}).${matcher}();`);
+        }
+        response.addResult('Done');
+    },
+});
+export default [
+    verifyElement,
+    verifyText,
+    verifyList,
+    verifyValue,
+];

package/lib/tools.js

@@ -18,8 +18,10 @@ import console from './tools/console.js';
 import dialogs from './tools/dialogs.js';
 import evaluate from './tools/evaluate.js';
 import files from './tools/files.js';
+import form from './tools/form.js';
 import install from './tools/install.js';
 import keyboard from './tools/keyboard.js';
+import mouse from './tools/mouse.js';
 import navigate from './tools/navigate.js';
 import network from './tools/network.js';
 import pdf from './tools/pdf.js';
@@ -27,13 +29,14 @@ import snapshot from './tools/snapshot.js';
 import tabs from './tools/tabs.js';
 import screenshot from './tools/screenshot.js';
 import wait from './tools/wait.js';
-import mouse from './tools/mouse.js';
+import verify from './tools/verify.js';
 export const allTools = [
     ...common,
     ...console,
     ...dialogs,
     ...evaluate,
     ...files,
+    ...form,
     ...install,
     ...keyboard,
     ...navigate,
@@ -44,6 +47,7 @@ export const allTools = [
     ...snapshot,
     ...tabs,
     ...wait,
+    ...verify,
 ];
 export function filteredTools(config) {
     return allTools.filter(tool => tool.capability.startsWith('core') || config.capabilities?.includes(tool.capability));

package/lib/vscode/host.js

@@ -0,0 +1,128 @@
+/**
+ * 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 { fileURLToPath } from 'url';
+import path from 'path';
+import { z } from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { ListRootsRequestSchema, PingRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import * as mcpServer from '../mcp/server.js';
+import { logUnhandledError } from '../utils/log.js';
+import { packageJSON } from '../utils/package.js';
+import { BrowserServerBackend } from '../browserServerBackend.js';
+import { contextFactory } from '../browserContextFactory.js';
+const contextSwitchOptions = z.object({
+    connectionString: z.string().optional().describe('The connection string to use to connect to the browser'),
+    lib: z.string().optional().describe('The library to use for the connection'),
+});
+class VSCodeProxyBackend {
+    _config;
+    _defaultTransportFactory;
+    name = 'Playwright MCP Client Switcher';
+    version = packageJSON.version;
+    _currentClient;
+    _contextSwitchTool;
+    _roots = [];
+    _clientVersion;
+    constructor(_config, _defaultTransportFactory) {
+        this._config = _config;
+        this._defaultTransportFactory = _defaultTransportFactory;
+        this._contextSwitchTool = this._defineContextSwitchTool();
+    }
+    async initialize(server, clientVersion, roots) {
+        this._clientVersion = clientVersion;
+        this._roots = roots;
+        const transport = await this._defaultTransportFactory();
+        await this._setCurrentClient(transport);
+    }
+    async listTools() {
+        const response = await this._currentClient.listTools();
+        return [
+            ...response.tools,
+            this._contextSwitchTool,
+        ];
+    }
+    async callTool(name, args) {
+        if (name === this._contextSwitchTool.name)
+            return this._callContextSwitchTool(args);
+        return await this._currentClient.callTool({
+            name,
+            arguments: args,
+        });
+    }
+    serverClosed(server) {
+        void this._currentClient?.close().catch(logUnhandledError);
+    }
+    async _callContextSwitchTool(params) {
+        if (!params.connectionString || !params.lib) {
+            const transport = await this._defaultTransportFactory();
+            await this._setCurrentClient(transport);
+            return {
+                content: [{ type: 'text', text: '### Result\nSuccessfully disconnected.\n' }],
+            };
+        }
+        await this._setCurrentClient(new StdioClientTransport({
+            command: process.execPath,
+            cwd: process.cwd(),
+            args: [
+                path.join(fileURLToPath(import.meta.url), '..', 'main.js'),
+                JSON.stringify(this._config),
+                params.connectionString,
+                params.lib,
+            ],
+        }));
+        return {
+            content: [{ type: 'text', text: '### Result\nSuccessfully connected.\n' }],
+        };
+    }
+    _defineContextSwitchTool() {
+        return {
+            name: 'browser_connect',
+            description: 'Do not call, this tool is used in the integration with the Playwright VS Code Extension and meant for programmatic usage only.',
+            inputSchema: zodToJsonSchema(contextSwitchOptions, { strictUnions: true }),
+            annotations: {
+                title: 'Connect to a browser running in VS Code.',
+                readOnlyHint: true,
+                openWorldHint: false,
+            },
+        };
+    }
+    async _setCurrentClient(transport) {
+        await this._currentClient?.close();
+        this._currentClient = undefined;
+        const client = new Client(this._clientVersion);
+        client.registerCapabilities({
+            roots: {
+                listRoots: true,
+            },
+        });
+        client.setRequestHandler(ListRootsRequestSchema, () => ({ roots: this._roots }));
+        client.setRequestHandler(PingRequestSchema, () => ({}));
+        await client.connect(transport);
+        this._currentClient = client;
+    }
+}
+export async function runVSCodeTools(config) {
+    const serverBackendFactory = {
+        name: 'Playwright w/ vscode',
+        nameInConfig: 'playwright-vscode',
+        version: packageJSON.version,
+        create: () => new VSCodeProxyBackend(config, () => mcpServer.wrapInProcess(new BrowserServerBackend(config, contextFactory(config))))
+    };
+    await mcpServer.start(serverBackendFactory, config.server);
+    return;
+}

package/lib/vscode/main.js

@@ -0,0 +1,62 @@
+/**
+ * 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 { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import * as mcpServer from '../mcp/server.js';
+import { BrowserServerBackend } from '../browserServerBackend.js';
+class VSCodeBrowserContextFactory {
+    _config;
+    _playwright;
+    _connectionString;
+    name = 'vscode';
+    description = 'Connect to a browser running in the Playwright VS Code extension';
+    constructor(_config, _playwright, _connectionString) {
+        this._config = _config;
+        this._playwright = _playwright;
+        this._connectionString = _connectionString;
+    }
+    async createContext(clientInfo, abortSignal) {
+        let launchOptions = this._config.browser.launchOptions;
+        if (this._config.browser.userDataDir) {
+            launchOptions = {
+                ...launchOptions,
+                ...this._config.browser.contextOptions,
+                userDataDir: this._config.browser.userDataDir,
+            };
+        }
+        const connectionString = new URL(this._connectionString);
+        connectionString.searchParams.set('launch-options', JSON.stringify(launchOptions));
+        const browserType = this._playwright.chromium; // it could also be firefox or webkit, we just need some browser type to call `connect` on
+        const browser = await browserType.connect(connectionString.toString());
+        const context = browser.contexts()[0] ?? await browser.newContext(this._config.browser.contextOptions);
+        return {
+            browserContext: context,
+            close: async () => {
+                await browser.close();
+            }
+        };
+    }
+}
+async function main(config, connectionString, lib) {
+    const playwright = await import(lib).then(mod => mod.default ?? mod);
+    const factory = new VSCodeBrowserContextFactory(config, playwright, connectionString);
+    await mcpServer.connect({
+        name: 'Playwright MCP',
+        nameInConfig: 'playwright-vscode',
+        create: () => new BrowserServerBackend(config, factory),
+        version: 'unused'
+    }, new StdioServerTransport(), false);
+}
+await main(JSON.parse(process.argv[2]), process.argv[3], process.argv[4]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playwright/mcp",
-  "version": "0.0.34",
+  "version": "0.0.35-alpha-2025-08-28",
   "description": "Playwright Tools for MCP",
   "type": "module",
   "repository": {

package/lib/utils/httpServer.js

@@ -1,39 +0,0 @@
-/**
- * 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 assert from 'assert';
-import http from 'http';
-export async function startHttpServer(config) {
-    const { host, port } = config;
-    const httpServer = http.createServer();
-    await new Promise((resolve, reject) => {
-        httpServer.on('error', reject);
-        httpServer.listen(port, host, () => {
-            resolve();
-            httpServer.removeListener('error', reject);
-        });
-    });
-    return httpServer;
-}
-export function httpAddressToString(address) {
-    assert(address, 'Could not bind server socket');
-    if (typeof address === 'string')
-        return address;
-    const resolvedPort = address.port;
-    let resolvedHost = address.family === 'IPv4' ? address.address : `[${address.address}]`;
-    if (resolvedHost === '0.0.0.0' || resolvedHost === '[::]')
-        resolvedHost = 'localhost';
-    return `http://${resolvedHost}:${resolvedPort}`;
-}