Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.
TypeScript automationchromechromiume2e-testingelectronend-to-end-testingfirefoxjavascriptplaywrighttesttest-automationtestingtesting-toolswebwebkit
chore(mcp): run commands from terminal (#38820)
Yury Semikhatsky37d58bd440ea
diff --git a/packages/playwright/src/mcp/DEPS.list b/packages/playwright/src/mcp/DEPS.listindex 37011f7172..8a846e976e 100644--- a/packages/playwright/src/mcp/DEPS.list+++ b/packages/playwright/src/mcp/DEPS.list@@ -2,6 +2,7 @@./sdk/./browser/./extension/+./terminal/daemon.ts[index.ts]./sdk/diff --git a/packages/playwright/src/mcp/browser/tab.ts b/packages/playwright/src/mcp/browser/tab.tsindex 98dca4165a..29a053c207 100644--- a/packages/playwright/src/mcp/browser/tab.ts+++ b/packages/playwright/src/mcp/browser/tab.ts@@ -284,16 +284,18 @@ export class Tab extends EventEmitter<TabEventsInterface> {await this._raceAgainstModalStates(() => waitForCompletion(this, callback));}- async refLocator(params: { element: string, ref: string }): Promise<{ locator: Locator, resolved: string }> {+ async refLocator(params: { element?: string, ref: string }): Promise<{ locator: Locator, resolved: string }> {await this._initializedPromise;return (await this.refLocators([params]))[0];}- async refLocators(params: { element: string, ref: string }[]): Promise<{ locator: Locator, resolved: string }[]> {+ async refLocators(params: { element?: string, ref: string }[]): Promise<{ locator: Locator, resolved: string }[]> {await this._initializedPromise;return Promise.all(params.map(async param => {try {- const locator = this.page.locator(`aria-ref=${param.ref}`).describe(param.element) as Locator;+ let locator = this.page.locator(`aria-ref=${param.ref}`);+ if (param.element)+ locator = locator.describe(param.element);const { resolvedSelector } = await locator._resolveSelector();return { locator, resolved: asLocator('javascript', resolvedSelector) };} catch (e) {diff --git a/packages/playwright/src/mcp/browser/tools/snapshot.ts b/packages/playwright/src/mcp/browser/tools/snapshot.tsindex c0500347b3..ffed6cd20a 100644--- a/packages/playwright/src/mcp/browser/tools/snapshot.ts+++ b/packages/playwright/src/mcp/browser/tools/snapshot.ts@@ -47,7 +47,7 @@ const snapshot = defineTool({});export const elementSchema = z.object({- element: z.string().describe('Human-readable element description used to obtain permission to interact with the element'),+ element: z.string().optional().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'),});diff --git a/packages/playwright/src/mcp/program.ts b/packages/playwright/src/mcp/program.tsindex 7495dd9af5..02ed0e443c 100644--- a/packages/playwright/src/mcp/program.ts+++ b/packages/playwright/src/mcp/program.ts@@ -22,6 +22,7 @@ import { colors, ProgramOption } from 'playwright-core/lib/utilsBundle';import { registry } from 'playwright-core/lib/server';import * as mcpServer from './sdk/server';+import { startMcpDaemonServer } from './terminal/daemon';import { commaSeparatedList, dotenvFileLoader, enumParser, headerParser, numberParser, resolutionParser, resolveCLIConfig, semicolonSeparatedList } from './browser/config';import { setupExitWatchdog } from './browser/watchdog';import { contextFactory } from './browser/browserContextFactory';@@ -73,6 +74,7 @@ export function decorateCommand(command: Command, version: string) {.option('--user-data-dir <path>', 'path to the user data directory. If not specified, a temporary directory will be created.').option('--viewport-size <size>', 'specify browser viewport size in pixels, for example "1280x720"', resolutionParser.bind(null, '--viewport-size')).addOption(new ProgramOption('--vision', 'Legacy option, use --caps=vision instead').hideHelp())+ .addOption(new ProgramOption('--daemon <socket>', 'run as daemon').hideHelp()).action(async options => {setupExitWatchdog();@@ -106,6 +108,18 @@ export function decorateCommand(command: Command, version: string) {return;}+ if (options.daemon) {+ const serverBackendFactory: mcpServer.ServerBackendFactory = {+ name: 'Playwright',+ nameInConfig: 'playwright-daemon',+ version,+ create: () => new BrowserServerBackend(config, browserContextFactory)+ };+ const socketPath = await startMcpDaemonServer(options.daemon, serverBackendFactory);+ console.error(`Daemon server listening on ${socketPath}`);+ return;+ }+const factory: mcpServer.ServerBackendFactory = {name: 'Playwright',nameInConfig: 'playwright',diff --git a/packages/playwright/src/mcp/sdk/server.ts b/packages/playwright/src/mcp/sdk/server.tsindex 574070a194..9346c720a8 100644--- a/packages/playwright/src/mcp/sdk/server.ts+++ b/packages/playwright/src/mcp/sdk/server.ts@@ -172,7 +172,7 @@ function addServerListener(server: Server, event: 'close' | 'initialized', liste};}-export async function start(serverBackendFactory: ServerBackendFactory, options: { host?: string; port?: number, allowedHosts?: string[] }) {+export async function start(serverBackendFactory: ServerBackendFactory, options: { host?: string; port?: number, allowedHosts?: string[], socketPath?: string }) {if (options.port === undefined) {await connect(serverBackendFactory, new mcpBundle.StdioServerTransport(), false);return;diff --git a/packages/playwright/src/mcp/terminal/cli.ts b/packages/playwright/src/mcp/terminal/cli.tsnew file mode 100644index 0000000000..de388fffc3--- /dev/null+++ b/packages/playwright/src/mcp/terminal/cli.ts@@ -0,0 +1,278 @@+/**+ * 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.+ */++/* eslint-disable no-console */++import { spawn } from 'child_process';+import fs from 'fs';+import net from 'net';+import os from 'os';+import path from 'path';+import { program, debug } from 'playwright-core/lib/utilsBundle';+import { SocketConnection } from './socketConnection';++import type * as mcp from '../sdk/exports';++const debugCli = debug('pw:cli');++const packageJSON = require('../../../package.json');++program+ .version('Version ' + (process.env.PW_CLI_DISPLAY_VERSION || packageJSON.version))+ .name('playwright-command');++function addCommand(name: string, description: string, action: (...args: any[]) => Promise<void>) {+ program+ .command(name)+ .description(description)+ .action(action);+}++addCommand('navigate <url>', 'open url in the browser', async url => {+ await runMcpCommand('browser_navigate', { url });+});++addCommand('close', 'close the browser', async () => {+ await runMcpCommand('browser_close', {});+});++// snapshot.ts+addCommand('click <ref>', 'click an element using a ref from a snapshot, e.g. e67', async ref => {+ await runMcpCommand('browser_click', { ref });+});++addCommand('snapshot', 'get accessible snapshot of the current page', async () => {+ await runMcpCommand('browser_snapshot', {});+});++addCommand('drag <startRef> <endRef>', 'drag from one element to another', async (startRef, endRef) => {+ await runMcpCommand('browser_drag', { startRef, endRef });+});++addCommand('hover <ref>', 'hover over an element', async ref => {+ await runMcpCommand('browser_hover', { ref });+});++addCommand('select <ref> <values...>', 'select option(s) in a dropdown', async (ref, values) => {+ await runMcpCommand('browser_select_option', { ref, values });+});++// TODO: remove?+addCommand('locator <ref>', 'generate a locator for an element', async ref => {+ await runMcpCommand('browser_generate_locator', { ref });+});++// keyboard.ts+addCommand('press <key>', 'press a key on the keyboard', async key => {+ await runMcpCommand('browser_press_key', { key });+});++addCommand('type <ref> <text>', 'type text into an element', async (ref, text) => {+ await runMcpCommand('browser_type', { ref, text });+});++// navigate.ts+addCommand('back', 'go back to the previous page', async () => {+ await runMcpCommand('browser_navigate_back', {});+});++// wait.ts+addCommand('wait <time>', 'wait for a specified time in seconds', async time => {+ await runMcpCommand('browser_wait_for', { time: parseFloat(time) });+});++addCommand('wait-for-text <text>', 'wait for text to appear', async text => {+ await runMcpCommand('browser_wait_for', { text });+});++// dialogs.ts+addCommand('dialog-accept [promptText]', 'accept a dialog', async promptText => {+ await runMcpCommand('browser_handle_dialog', { accept: true, promptText });+});++addCommand('dialog-dismiss', 'dismiss a dialog', async () => {+ await runMcpCommand('browser_handle_dialog', { accept: false });+});++// screenshot.ts+addCommand('screenshot [filename]', 'take a screenshot of the current page', async filename => {+ await runMcpCommand('browser_take_screenshot', { filename });+});++// common.ts (resize)+addCommand('resize <width> <height>', 'resize the browser window', async (width, height) => {+ await runMcpCommand('browser_resize', { width: parseInt(width, 10), height: parseInt(height, 10) });+});++// files.ts+addCommand('upload <paths...>', 'upload files', async paths => {+ await runMcpCommand('browser_file_upload', { paths });+});++// tabs.ts+addCommand('tabs', 'list all browser tabs', async () => {+ await runMcpCommand('browser_tabs', { action: 'list' });+});++addCommand('tab-new', 'create a new browser tab', async () => {+ await runMcpCommand('browser_tabs', { action: 'new' });+});++addCommand('tab-close [index]', 'close a browser tab', async index => {+ await runMcpCommand('browser_tabs', { action: 'close', index: index !== undefined ? parseInt(index, 10) : undefined });+});++addCommand('tab-select <index>', 'select a browser tab', async index => {+ await runMcpCommand('browser_tabs', { action: 'select', index: parseInt(index, 10) });+});+++async function runMcpCommand(name: string, args: mcp.CallToolRequest['params']['arguments']) {+ const session = await connectToDaemon();+ const result = await session.callTool(name, args);+ printResult(result);+ session.dispose();+}++function printResult(result: mcp.CallToolResult) {+ for (const content of result.content) {+ if (content.type === 'text')+ console.log(content.text);+ else+ console.log(`<${content.type} content>`);+ }+}++async function socketExists(socketPath: string): Promise<boolean> {+ try {+ const stat = await fs.promises.stat(socketPath);+ if (stat?.isSocket())+ return true;+ } catch (e) {+ }+ return false;+}++class SocketSession {+ private _connection: SocketConnection;+ private _nextMessageId = 1;+ private _callbacks = new Map<number, { resolve: (o: any) => void, reject: (e: Error) => void, error: Error }>();++ constructor(connection: SocketConnection) {+ this._connection = connection;+ this._connection.onmessage = message => this._onMessage(message);+ this._connection.onclose = () => this.dispose();+ }+++ async callTool(name: string, args: mcp.CallToolRequest['params']['arguments']): Promise<mcp.CallToolResult> {+ return this._send(name, args);+ }++ private async _send(method: string, params: any = {}): Promise<any> {+ const messageId = this._nextMessageId++;+ const message = {+ id: messageId,+ method,+ params,+ };+ await this._connection.send(message);+ return new Promise<any>((resolve, reject) => {+ this._callbacks.set(messageId, { resolve, reject, error: new Error(`Error in method: ${method}`) });+ });+ }++ dispose() {+ for (const callback of this._callbacks.values())+ callback.reject(callback.error);+ this._callbacks.clear();+ this._connection.close();+ }++ private _onMessage(object: any) {+ if (object.id && this._callbacks.has(object.id)) {+ const callback = this._callbacks.get(object.id)!;+ this._callbacks.delete(object.id);+ if (object.error) {+ callback.error.cause = new Error(object.error);+ callback.reject(callback.error);+ } else {+ callback.resolve(object.result);+ }+ } else if (object.id) {+ throw new Error(`Unexpected message id: ${object.id}`);+ } else {+ throw new Error(`Unexpected message without id: ${JSON.stringify(object)}`);+ }+ }+}++function daemonSocketPath(): string {+ if (os.platform() === 'win32')+ return path.join('\\\\.\\pipe', 'pw-daemon.sock');+ return path.join(os.homedir(), '.playwright', 'pw-daemon.sock');+}++async function connectToDaemon(): Promise<SocketSession> {+ const socketPath = daemonSocketPath();+ debugCli(`Connecting to daemon at ${socketPath}`);++ if (await socketExists(socketPath)) {+ debugCli(`Socket file exists, attempting to connect...`);+ try {+ return await connectToSocket(socketPath);+ } catch (e) {+ // Connection failed, delete the stale socket file.+ fs.unlinkSync(socketPath);+ }+ }++ const cliPath = path.join(__dirname, '../../../cli.js');+ debugCli(`Will launch daemon process: ${cliPath}`);+ const child = spawn(process.execPath, [cliPath, 'run-mcp-server', `--daemon=${socketPath}`], {+ detached: true,+ stdio: 'ignore',+ });+ child.unref();++ // Wait for the socket to become available with retries.+ const maxRetries = 50;+ const retryDelay = 100; // ms+ for (let i = 0; i < maxRetries; i++) {+ await new Promise(resolve => setTimeout(resolve, 100));+ try {+ return await connectToSocket(socketPath);+ } catch (e) {+ if (e.code !== 'ENOENT')+ throw e;+ debugCli(`Retrying to connect to daemon at ${socketPath} (${i + 1}/${maxRetries})`);+ }+ }+ throw new Error(`Failed to connect to daemon at ${socketPath} after ${maxRetries * retryDelay}ms`);+}++async function connectToSocket(socketPath: string): Promise<SocketSession> {+ const socket = await new Promise<net.Socket>((resolve, reject) => {+ const socket = net.createConnection(socketPath, () => {+ debugCli(`Connected to daemon at ${socketPath}`);+ resolve(socket);+ });+ socket.on('error', reject);+ });+ return new SocketSession(new SocketConnection(socket));+}++void program.parseAsync(process.argv);diff --git a/packages/playwright/src/mcp/terminal/daemon.ts b/packages/playwright/src/mcp/terminal/daemon.tsnew file mode 100644index 0000000000..8213510b8e--- /dev/null+++ b/packages/playwright/src/mcp/terminal/daemon.ts@@ -0,0 +1,118 @@+/**+ * 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 fs from 'fs/promises';+import net from 'net';+import os from 'os';+import path from 'path';++import { debug } from 'playwright-core/lib/utilsBundle';+import { SocketConnection } from './socketConnection';++import type { ServerBackendFactory } from '../sdk/server';++const daemonDebug = debug('pw:daemon');++/**+ * Normalize socket path for the current platform.+ * On Windows, converts Unix-style paths to named pipe format.+ * On Unix, returns the path as-is.+ */+function normalizeSocketPath(path: string): string {+ if (os.platform() === 'win32') {+ // Windows named pipes use \\.\pipe\name format+ if (path.startsWith('\\\\.\\pipe\\'))+ return path;+ // Convert Unix-style path to Windows named pipe+ const name = path.replace(/[^a-zA-Z0-9]/g, '-');+ return `\\\\.\\pipe\\${name}`;+ }+ return path;+}++async function socketExists(socketPath: string): Promise<boolean> {+ try {+ const stat = await fs.stat(socketPath);+ if (stat?.isSocket())+ return true;+ } catch (e) {+ }+ return false;+}+/**+ * Start a daemon server listening on Unix domain socket (Unix) or named pipe (Windows).+ */+export async function startMcpDaemonServer(+ socketPath: string,+ serverBackendFactory: ServerBackendFactory+): Promise<string> {+ const normalizedPath = normalizeSocketPath(socketPath);++ // Clean up existing socket file on Unix+ if (os.platform() !== 'win32' && await socketExists(normalizedPath)) {+ daemonDebug(`Socket already exists, removing: ${normalizedPath}`);+ try {+ await fs.unlink(normalizedPath);+ } catch (error) {+ daemonDebug(`Failed to remove existing socket: ${error}`);+ throw error;+ }+ }++ const backend = serverBackendFactory.create();+ await backend.initialize?.({+ name: 'mcp-daemon',+ version: '1.0.0',+ roots: [],+ timestamp: Date.now(),+ });++ await fs.mkdir(path.dirname(normalizedPath), { recursive: true });++ const server = net.createServer(socket => {+ daemonDebug('new client connection');+ const connection = new SocketConnection(socket);+ connection.onclose = () => {+ daemonDebug('client disconnected');+ };+ connection.onmessage = async message => {+ const { id, method, params } = message;+ try {+ daemonDebug('received command', method);+ const response = await backend.callTool(method, params, () => {});+ daemonDebug('sending response', !!response);+ if (response)+ await connection.send({ id, result: response });+ } catch (e) {+ daemonDebug('command failed', e);+ await connection.send({ id, error: (e as Error).message });+ daemonDebug('error handling message', e);+ }+ };+ });++ return new Promise((resolve, reject) => {+ server.on('error', (error: NodeJS.ErrnoException) => {+ daemonDebug(`server error: ${error.message}`);+ reject(error);+ });++ server.listen(normalizedPath, () => {+ daemonDebug(`daemon server listening on ${normalizedPath}`);+ resolve(normalizedPath);+ });+ });+}diff --git a/packages/playwright/src/mcp/terminal/socketConnection.ts b/packages/playwright/src/mcp/terminal/socketConnection.tsnew file mode 100644index 0000000000..135d88ec99--- /dev/null+++ b/packages/playwright/src/mcp/terminal/socketConnection.ts@@ -0,0 +1,82 @@+/**+ * 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 net from 'net';++import { debug } from 'playwright-core/lib/utilsBundle';++const daemonDebug = debug('pw:daemon');++export class SocketConnection {+ private _socket: net.Socket;+ private _pendingBuffers: Buffer[] = [];++ onclose?: () => void;+ onmessage?: (message: any) => void;++ constructor(socket: net.Socket) {+ this._socket = socket;+ socket.on('data', buffer => this._onData(buffer));+ socket.on('close', () => {+ this.onclose?.();+ });+ socket.on('error', e => daemonDebug(`error: ${e.message}`));+ }++ async send(message: any) {+ await new Promise((resolve, reject) => {+ this._socket.write(`${JSON.stringify(message)}\n`, error => {+ if (error)+ reject(error);+ else+ resolve(undefined);+ });+ });+ }++ close() {+ this._socket.destroy();+ }++ private _onData(buffer: Buffer) {+ let end = buffer.indexOf('\n');+ if (end === -1) {+ this._pendingBuffers.push(buffer);+ return;+ }+ this._pendingBuffers.push(buffer.slice(0, end));+ const message = Buffer.concat(this._pendingBuffers).toString();+ this._dispatchMessage(message);++ let start = end + 1;+ end = buffer.indexOf('\n', start);+ while (end !== -1) {+ const message = buffer.toString(undefined, start, end);+ this._dispatchMessage(message);+ start = end + 1;+ end = buffer.indexOf('\n', start);+ }+ this._pendingBuffers = [buffer.slice(start)];+ }++ private _dispatchMessage(message: string) {+ try {+ this.onmessage?.(JSON.parse(message));+ } catch (e) {+ daemonDebug('failed to dispatch message', e);+ }+ }+}