Skip to content

Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.

chore(mcp): run commands from terminal (#38820)

Yury Semikhatsky37d58bd440ea
diff --git a/packages/playwright/src/mcp/DEPS.list b/packages/playwright/src/mcp/DEPS.list
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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);
+ }
+ }
+}