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
feat(cli): add --json global flag for structured output (#40284)
Pavel Feldman10a511e39fc2
diff --git a/packages/playwright-core/src/tools/backend/browserBackend.ts b/packages/playwright-core/src/tools/backend/browserBackend.tsindex 12b18ad297..46f9a3c153 100644--- a/packages/playwright-core/src/tools/backend/browserBackend.ts+++ b/packages/playwright-core/src/tools/backend/browserBackend.ts@@ -51,19 +51,20 @@ export class BrowserBackend implements ServerBackend {}async callTool(name: string, rawArguments: mcpServer.CallToolRequest['params']['arguments'] & { _meta?: Record<string, any> } = {}): Promise<mcpServer.CallToolResult> {+ const json = !!rawArguments._meta?.json;+ const formatError = (message: string): mcpServer.CallToolResult => ({+ content: [{ type: 'text' as const, text: json ? JSON.stringify({ isError: true, error: message }, null, 2) : `### Error\n${message}` }],+ isError: true,+ });const tool = this._tools.find(tool => tool.schema.name === name)!;- if (!tool) {- return {- content: [{ type: 'text' as const, text: `### Error\nTool "${name}" not found` }],- isError: true,- };- }+ if (!tool)+ return formatError(`Tool "${name}" not found`);// eslint-disable-next-line no-restricted-syntaxconst parsedArguments = tool.schema.inputSchema.parse(rawArguments) as any;const cwd = rawArguments._meta?.cwd;const raw = !!rawArguments._meta?.raw;const context = this._context!;- const response = new Response(context, name, parsedArguments, { relativeTo: cwd, raw });+ const response = new Response(context, name, parsedArguments, { relativeTo: cwd, raw, json });context.setRunningTool(name);let responseObject: mcpServer.CallToolResult;try {@@ -71,10 +72,7 @@ export class BrowserBackend implements ServerBackend {responseObject = await response.serialize();this._sessionLog?.logResponse(name, parsedArguments, responseObject);} catch (error: any) {- return {- content: [{ type: 'text' as const, text: `### Error\n${String(error)}` }],- isError: true,- };+ return formatError(String(error));} finally {context.setRunningTool(undefined);}diff --git a/packages/playwright-core/src/tools/backend/response.ts b/packages/playwright-core/src/tools/backend/response.tsindex 6a92c68132..e010fbc551 100644--- a/packages/playwright-core/src/tools/backend/response.ts+++ b/packages/playwright-core/src/tools/backend/response.ts@@ -57,13 +57,15 @@ export class Response {private _clientWorkspace: string;private _imageResults: { data: Buffer, imageType: 'png' | 'jpeg' }[] = [];private _raw: boolean;+ private _json: boolean;- constructor(context: Context, toolName: string, toolArgs: Record<string, any>, options?: { relativeTo?: string, raw?: boolean }) {+ constructor(context: Context, toolName: string, toolArgs: Record<string, any>, options?: { relativeTo?: string, raw?: boolean, json?: boolean }) {this._context = context;this.toolName = toolName;this.toolArgs = toolArgs;this._clientWorkspace = options?.relativeTo ?? context.options.cwd;- this._raw = options?.raw ?? false;+ this._json = options?.json ?? false;+ this._raw = this._json || (options?.raw ?? false);}private _computRelativeTo(fileName: string): string {@@ -157,26 +159,47 @@ export class Response {const rawSections = ['Error', 'Result', 'Snapshot'] as const;const sections = this._raw ? allSections.filter(section => rawSections.includes(section.title as typeof rawSections[number])) : allSections;- const text: string[] = [];- for (const section of sections) {- if (!section.content.length)- continue;- if (!this._raw) {- text.push(`### ${section.title}`);- if (section.codeframe)- text.push(`\`\`\`${section.codeframe}`);- text.push(...section.content);- if (section.codeframe)- text.push('```');- } else {- text.push(...section.content);+ let serializedText: string;+ if (this._json) {+ const payload: Record<string, unknown> = {};+ const isError = sections.some(section => section.isError);+ if (isError)+ payload.isError = true;+ for (const section of sections) {+ if (!section.content.length)+ continue;+ const key = section.title.toLowerCase();+ if (key === 'snapshot') {+ const match = section.content[0]?.match(/^- \[Snapshot\]\(([^)]+)\)$/);+ payload.snapshot = match ? { file: match[1] } : section.content.join('\n');+ } else {+ payload[key] = section.content.join('\n');+ }+ }+ serializedText = JSON.stringify(payload, null, 2);+ } else {+ const text: string[] = [];+ for (const section of sections) {+ if (!section.content.length)+ continue;+ if (!this._raw) {+ text.push(`### ${section.title}`);+ if (section.codeframe)+ text.push(`\`\`\`${section.codeframe}`);+ text.push(...section.content);+ if (section.codeframe)+ text.push('```');+ } else {+ text.push(...section.content);+ }}+ serializedText = text.join('\n');}const content: (TextContent | ImageContent)[] = [{type: 'text',- text: sanitizeUnicode(this._redactSecrets(text.join('\n'))),+ text: sanitizeUnicode(this._redactSecrets(serializedText)),}];diff --git a/packages/playwright-core/src/tools/cli-client/DEPS.list b/packages/playwright-core/src/tools/cli-client/DEPS.listindex 6d5be4ad81..086f0c0e74 100644--- a/packages/playwright-core/src/tools/cli-client/DEPS.list+++ b/packages/playwright-core/src/tools/cli-client/DEPS.list@@ -4,9 +4,14 @@../../serverRegistry.ts./channelSessions.ts./minimist.ts+./output.ts./session.ts./registry.ts+[output.ts]+"strict"+./channelSessions.ts+[channelSessions.ts]"strict"diff --git a/packages/playwright-core/src/tools/cli-client/output.ts b/packages/playwright-core/src/tools/cli-client/output.tsnew file mode 100644index 0000000000..4d8584b5f7--- /dev/null+++ b/packages/playwright-core/src/tools/cli-client/output.ts@@ -0,0 +1,383 @@+/**+ * 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 */+/* eslint-disable no-restricted-properties */++import path from 'path';++import { remoteDebuggingHint } from './channelSessions';++import type { ChannelSession } from './channelSessions';++export type ListedBrowser = {+ name: string;+ workspace: string;+ status: 'open' | 'closed';+ browserType: string | undefined;+ userDataDir: string | null;+ headed: boolean | undefined;+ persistent: boolean;+ attached: boolean;+ compatible: boolean;+ version: string;+};++export type ListedServer = {+ workspace: string;+ title: string;+ browser: string;+ playwrightVersion: string;+ status: 'open' | 'closed';+ userDataDir: string | null;+};++export type ListData = {+ all: boolean;+ browsers: ListedBrowser[];+ servers?: ListedServer[];+ channelSessions?: ChannelSession[];+};++export interface Output {+ readonly json: boolean;++ version(v: string): void;+ help(text: string): void;++ errorUnknownCommand(name: string | undefined, globalHelp: string): never;+ errorUnknownOption(opts: string[], commandHelp: string): never;+ errorAttachConflict(): never;+ errorBrowserNotOpenForTool(session: string): never;++ list(data: ListData): void;+ closeAll(sessions: string[]): void;+ deleteData(session: string, result: { existed: boolean, deletedUserDataDir: boolean }): void;+ killAll(pids: number[]): void;+ open(session: string, pid: number | undefined, toolResult: string): void;+ attach(session: string, pid: number | undefined, endpoint: string | undefined, toolResult: string): void;+ close(session: string, wasOpen: boolean): void;+ installed(): void;+ show(session: string, pid: number | undefined): void;+ toolResult(text: string): void;++ installStdio(): 'inherit' | 'ignore';+}++export class TextOutput implements Output {+ readonly json = false;++ version(v: string): void {+ console.log(v);+ }++ help(text: string): void {+ console.log(text);+ }++ errorUnknownCommand(name: string | undefined, globalHelp: string): never {+ console.error(`Unknown command: ${name}\n`);+ console.log(globalHelp);+ return process.exit(1);+ }++ errorUnknownOption(opts: string[], commandHelp: string): never {+ console.error(`Unknown option${opts.length > 1 ? 's' : ''}: ${opts.map(f => `--${f}`).join(', ')}`);+ console.log('');+ console.log(commandHelp);+ return process.exit(1);+ }++ errorAttachConflict(): never {+ console.error(`Error: cannot use target name with --cdp, --endpoint, or --extension`);+ return process.exit(1);+ }++ errorBrowserNotOpenForTool(session: string): never {+ console.log(`The browser '${session}' is not open, please run open first`);+ console.log('');+ console.log(` playwright-cli${session !== 'default' ? ` -s=${session}` : ''} open [params]`);+ return process.exit(1);+ }++ list({ all, browsers, servers, channelSessions }: ListData): void {+ const byWorkspace = new Map<string, ListedBrowser[]>();+ for (const browser of browsers) {+ let list = byWorkspace.get(browser.workspace);+ if (!list) {+ list = [];+ byWorkspace.set(browser.workspace, list);+ }+ list.push(browser);+ }++ let count = 0;+ for (const [workspaceKey, list] of byWorkspace) {+ if (count === 0)+ console.log('### Browsers');+ if (all)+ console.log(`${path.relative(process.cwd(), workspaceKey) || '/'}:`);+ for (const browser of list)+ console.log(renderBrowser(browser));+ count += list.length;+ }++ if (!all) {+ if (!count)+ console.log(' (no browsers)');+ return;+ }++ if (servers?.length) {+ if (count)+ console.log('');+ console.log('### Browser servers available for attach');+ const serversByWorkspace = new Map<string, ListedServer[]>();+ for (const server of servers) {+ let list = serversByWorkspace.get(server.workspace);+ if (!list) {+ list = [];+ serversByWorkspace.set(server.workspace, list);+ }+ list.push(server);+ }+ for (const [workspaceKey, list] of serversByWorkspace) {+ if (workspaceKey)+ console.log(`${path.relative(process.cwd(), workspaceKey) || '/'}:`);+ for (const server of list)+ console.log(renderServer(server));+ }+ count += servers.length;+ }++ if (!count)+ console.log(' (no browsers)');++ if (channelSessions?.length) {+ console.log('');+ console.log('### Browsers available to attach via CDP');+ for (const session of channelSessions)+ console.log(renderChannelSession(session));+ }+ }++ closeAll(_sessions: string[]): void {+ // Text mode is intentionally silent, matching historical behavior.+ }++ deleteData(session: string, result: { existed: boolean, deletedUserDataDir: boolean }): void {+ if (!result.existed) {+ console.log(`No user data found for browser '${session}'.`);+ return;+ }+ if (result.deletedUserDataDir)+ console.log(`Deleted user data for browser '${session}'.`);+ }++ killAll(pids: number[]): void {+ for (const pid of pids)+ console.log(`Killed daemon process ${pid}`);+ if (pids.length === 0)+ console.log('No daemon processes found.');+ else+ console.log(`Killed ${pids.length} daemon process${pids.length === 1 ? '' : 'es'}.`);+ }++ open(session: string, pid: number | undefined, toolResult: string): void {+ console.log(`### Browser \`${session}\` opened with pid ${pid}.`);+ if (toolResult)+ console.log(toolResult);+ }++ attach(session: string, pid: number | undefined, endpoint: string | undefined, toolResult: string): void {+ if (endpoint) {+ console.log(`### Session \`${session}\` created, attached to \`${endpoint}\`.`);+ console.log(`Run commands with: playwright-cli --session=${session} <command>`);+ } else {+ console.log(`### Browser \`${session}\` opened with pid ${pid}.`);+ }+ if (toolResult)+ console.log(toolResult);+ }++ close(session: string, wasOpen: boolean): void {+ if (!wasOpen) {+ console.log(`Browser '${session}' is not open.`);+ return;+ }+ console.log(`Browser '${session}' closed\n`);+ }++ installed(): void {+ // The spawned install subprocess handles its own output.+ }++ show(_session: string, pid: number | undefined): void {+ if (process.env.PLAYWRIGHT_PRINT_DASHBOARD_PID_FOR_TEST)+ console.log(`### Dashboard opened with pid ${pid}.`);+ }++ toolResult(text: string): void {+ console.log(text);+ }++ installStdio(): 'inherit' | 'ignore' {+ return 'inherit';+ }+}++export class JsonOutput implements Output {+ readonly json = true;++ version(v: string): void {+ this._emit({ version: v });+ }++ help(text: string): void {+ this._emit({ help: text });+ }++ errorUnknownCommand(name: string | undefined, _globalHelp: string): never {+ this._emit({ isError: true, error: `Unknown command: ${name}` });+ return process.exit(1);+ }++ errorUnknownOption(opts: string[], _commandHelp: string): never {+ this._emit({ isError: true, error: `Unknown option${opts.length > 1 ? 's' : ''}: ${opts.map(f => `--${f}`).join(', ')}` });+ return process.exit(1);+ }++ errorAttachConflict(): never {+ this._emit({ isError: true, error: `cannot use target name with --cdp, --endpoint, or --extension` });+ return process.exit(1);+ }++ errorBrowserNotOpenForTool(session: string): never {+ this._emit({ isError: true, error: `The browser '${session}' is not open, please run open first` });+ return process.exit(1);+ }++ list({ all, browsers, servers, channelSessions }: ListData): void {+ const payload: Record<string, unknown> = { browsers };+ if (all) {+ payload.servers = servers ?? [];+ payload.channelSessions = channelSessions ?? [];+ }+ this._emit(payload);+ }++ closeAll(sessions: string[]): void {+ this._emit({ closed: sessions });+ }++ deleteData(session: string, result: { existed: boolean, deletedUserDataDir: boolean }): void {+ this._emit({ session, deleted: result.existed });+ }++ killAll(pids: number[]): void {+ this._emit({ killed: pids.length, pids });+ }++ open(session: string, pid: number | undefined, toolResult: string): void {+ this._emit({ session, pid, result: parseJsonText(toolResult) });+ }++ attach(session: string, pid: number | undefined, endpoint: string | undefined, toolResult: string): void {+ this._emit({+ session,+ pid,+ ...(endpoint ? { endpoint } : {}),+ result: parseJsonText(toolResult),+ });+ }++ close(session: string, wasOpen: boolean): void {+ this._emit({ session, status: wasOpen ? 'closed' : 'not-open' });+ }++ installed(): void {+ this._emit({ installed: true });+ }++ show(session: string, pid: number | undefined): void {+ this._emit({ session, pid });+ }++ toolResult(text: string): void {+ // Daemon already returns pretty-printed JSON, write through verbatim.+ console.log(text);+ }++ installStdio(): 'inherit' | 'ignore' {+ return 'ignore';+ }++ private _emit(value: unknown): void {+ console.log(JSON.stringify(value, null, 2));+ }+}++function parseJsonText(text: string): unknown {+ try {+ return JSON.parse(text);+ } catch {+ return text;+ }+}++function renderBrowser(browser: ListedBrowser): string {+ const lines = [`- ${browser.name}:`];+ lines.push(` - status: ${browser.status}`);+ if (browser.status === 'open' && !browser.compatible)+ lines.push(` - version: v${browser.version} [incompatible please re-open]`);+ if (browser.browserType)+ lines.push(` - browser-type: ${browser.browserType}${browser.attached ? ' (attached)' : ''}`);+ if (!browser.attached) {+ if (browser.userDataDir === null)+ lines.push(` - user-data-dir: <in-memory>`);+ else+ lines.push(` - user-data-dir: ${browser.userDataDir}`);+ if (browser.headed !== undefined)+ lines.push(` - headed: ${browser.headed}`);+ }+ return lines.join('\n');+}++function renderServer(server: ListedServer): string {+ const lines = [`- browser "${server.title}":`];+ lines.push(` - browser: ${server.browser}`);+ lines.push(` - version: v${server.playwrightVersion}`);+ lines.push(` - status: ${server.status}`);+ if (server.userDataDir)+ lines.push(` - data-dir: ${server.userDataDir}`);+ else+ lines.push(` - data-dir: <in-memory>`);+ lines.push(` - run \`playwright-cli attach "${server.title}"\` to attach`);+ return lines.join('\n');+}++function renderChannelSession(session: ChannelSession): string {+ const lines = [`- ${session.channel}:`];+ lines.push(` - data-dir: ${session.userDataDir}`);+ if (session.endpoint) {+ lines.push(` - endpoint: ${session.endpoint}`);+ lines.push(` - run \`playwright-cli attach --cdp=${session.channel}\` to attach`);+ } else {+ lines.push(` - status: remote debugging not enabled`);+ lines.push(` - ${remoteDebuggingHint(session.channel)}`);+ }+ return lines.join('\n');+}diff --git a/packages/playwright-core/src/tools/cli-client/program.ts b/packages/playwright-core/src/tools/cli-client/program.tsindex 950bb227bb..bcbdcfe5ef 100644--- a/packages/playwright-core/src/tools/cli-client/program.ts+++ b/packages/playwright-core/src/tools/cli-client/program.ts@@ -14,27 +14,28 @@* limitations under the License.*/-/* eslint-disable no-console *//* eslint-disable no-restricted-properties */import { execSync, spawn } from 'child_process';import crypto from 'crypto';import os from 'os';-import path from 'path';-import { listChannelSessions, remoteDebuggingHint } from './channelSessions';++import { listChannelSessions } from './channelSessions';+import { JsonOutput, TextOutput } from './output';import { clientKey, createClientInfo, explicitSessionName, Registry, resolveSessionName } from './registry';-import { Session, renderResolvedConfig } from './session';+import { Session } from './session';import { libPath } from '../../package';import { serverRegistry } from '../../serverRegistry';import { minimist } from './minimist';+import type { ListData, ListedBrowser, ListedServer, Output } from './output';import type { ClientInfo, SessionFile } from './registry';-import type { BrowserStatus } from '../../serverRegistry';import type { MinimistArgs } from './minimist';type GlobalOptions = {help?: boolean;+ json?: boolean;raw?: boolean;session?: string;version?: boolean;@@ -56,6 +57,7 @@ type OpenOptions = {};const globalOptions: (keyof (GlobalOptions & OpenOptions & AttachOptions))[] = [+ 'json','raw','session',];@@ -63,6 +65,7 @@ const globalOptions: (keyof (GlobalOptions & OpenOptions & AttachOptions))[] = [const booleanOptions: (keyof (GlobalOptions & OpenOptions & AttachOptions & { all?: boolean }))[] = ['all','help',+ 'json','raw','version',];@@ -80,72 +83,71 @@ export async function program(options?: { embedderVersion?: string}) {delete args.s;}+ const output: Output = args.json ? new JsonOutput() : new TextOutput();const commandName = args._?.[0];if (args.version || args.v) {- console.log(options?.embedderVersion ?? clientInfo.version);+ output.version(options?.embedderVersion ?? clientInfo.version);process.exit(0);}const command = commandName && help.commands[commandName];if (args.help || args.h) {- if (command) {- console.log(command.help);- } else {- console.log('playwright-cli - run playwright mcp commands from terminal\n');- console.log(help.global);- }+ output.help(command ? command.help : 'playwright-cli - run playwright mcp commands from terminal\n\n' + help.global);process.exit(0);}- if (!command) {- console.error(`Unknown command: ${commandName}\n`);- console.log(help.global);- process.exit(1);- }+ if (!command)+ output.errorUnknownCommand(commandName, help.global);- validateFlags(args, command);+ validateFlags(args, command, output);const registry = await Registry.load();const sessionName = resolveSessionName(args.session as string);switch (commandName) {case 'list': {- await listSessions(registry, clientInfo, !!args.all);+ const data = await collectList(registry, clientInfo, !!args.all);+ output.list(data);return;}case 'close-all': {const entries = registry.entries(clientInfo);- for (const entry of entries)- await new Session(entry).stop(true);+ const closed: string[] = [];+ for (const entry of entries) {+ await new Session(entry).stop();+ closed.push(entry.config.name);+ }+ output.closeAll(closed);return;}case 'delete-data': {const entry = registry.entry(clientInfo, sessionName);if (!entry) {- console.log(`No user data found for browser '${sessionName}'.`);+ output.deleteData(sessionName, { existed: false, deletedUserDataDir: false });return;}- await new Session(entry).deleteData();+ const result = await new Session(entry).deleteData();+ output.deleteData(sessionName, result);return;}case 'kill-all': {- await killAllDaemons();+ const pids = await killAllDaemons();+ output.killAll(pids);return;}case 'open': {- await startSession(sessionName, registry, clientInfo, args, 'open');+ const { pid } = await startSession(sessionName, registry, clientInfo, args, 'open');const newEntry = await registry.loadEntry(clientInfo, sessionName);const params = args._.slice(1);- await runInSession(newEntry, clientInfo, { _: ['goto', ...(params.length ? params : ['about:blank'])] });+ const toolText = await runInSession(newEntry, clientInfo, { _: ['goto', ...(params.length ? params : ['about:blank'])] }, output);+ output.open(sessionName, pid, toolText);return;}case 'attach': {const attachTarget = args._[1] as string | undefined;- if (attachTarget && (args.cdp || args.endpoint || args.extension)) {- console.error(`Error: cannot use target name with --cdp, --endpoint, or --extension`);- process.exit(1);- }+ if (attachTarget && (args.cdp || args.endpoint || args.extension))+ output.errorAttachConflict();if (attachTarget)args.endpoint = attachTarget;if (typeof args.extension === 'string') {@@ -154,25 +156,25 @@ export async function program(options?: { embedderVersion?: string}) {}const attachSessionName = explicitSessionName(args.session as string) ?? attachTarget ?? sessionName;args.session = attachSessionName;- await startSession(attachSessionName, registry, clientInfo, args, 'attach');+ const { pid, endpoint } = await startSession(attachSessionName, registry, clientInfo, args, 'attach');const newEntry = await registry.loadEntry(clientInfo, attachSessionName);- await runInSession(newEntry, clientInfo, { _: ['snapshot'], filename: '<auto>' });+ const toolText = await runInSession(newEntry, clientInfo, { _: ['snapshot'], filename: '<auto>' }, output);+ output.attach(attachSessionName, pid, endpoint, toolText);return;}- case 'close':+ case 'close': {const closeEntry = registry.entry(clientInfo, sessionName);- const session = closeEntry ? new Session(closeEntry) : undefined;- if (!session || !await session.canConnect()) {- console.log(`Browser '${sessionName}' is not open.`);- return;- }- await session.stop();+ const { wasOpen } = closeEntry ? await new Session(closeEntry).stop() : { wasOpen: false };+ output.close(sessionName, wasOpen);return;+ }case 'install':- await runInitWorkspace(args);+ await runInitWorkspace(args, output);+ output.installed();return;case 'install-browser':await installBrowser();+ output.installed();return;case 'show': {const daemonScript = libPath('entry', 'dashboardApp.js');@@ -195,19 +197,15 @@ export async function program(options?: { embedderVersion?: string}) {return;}child.unref();- if (process.env.PLAYWRIGHT_PRINT_DASHBOARD_PID_FOR_TEST)- console.log(`### Dashboard opened with pid ${child.pid}.`);+ output.show(sessionName, child.pid);return;}default: {const entry = registry.entry(clientInfo, sessionName);- if (!entry) {- console.log(`The browser '${sessionName}' is not open, please run open first`);- console.log('');- console.log(` playwright-cli${sessionName !== 'default' ? ` -s=${sessionName}` : ''} open [params]`);- process.exit(1);- }- await runInSession(entry, clientInfo, args);+ if (!entry)+ output.errorBrowserNotOpenForTool(sessionName);+ const text = await runInSession(entry, clientInfo, args, output);+ output.toolResult(text);}}}@@ -215,25 +213,25 @@ export async function program(options?: { embedderVersion?: string}) {async function startSession(sessionName: string, registry: Registry, clientInfo: ClientInfo, args: MinimistArgs, mode: 'open' | 'attach') {const entry = registry.entry(clientInfo, sessionName);if (entry)- await new Session(entry).stop(true);- await Session.startDaemon(clientInfo, args, mode);+ await new Session(entry).stop();+ return await Session.startDaemon(clientInfo, args, mode);}-async function runInSession(entry: SessionFile, clientInfo: ClientInfo, args: MinimistArgs) {+async function runInSession(entry: SessionFile, clientInfo: ClientInfo, args: MinimistArgs, output: Output): Promise<string> {const raw = !!args.raw;for (const globalOption of globalOptions)delete args[globalOption];const session = new Session(entry);- const result = await session.run(clientInfo, args, { raw });- console.log(result.text);+ const result = await session.run(clientInfo, args, { raw, json: output.json });+ return result.text;}-async function runInitWorkspace(args: MinimistArgs) {+async function runInitWorkspace(args: MinimistArgs, output: Output) {const cliPath = libPath('entry', 'cliDaemon.js');const daemonArgs: string[] = [cliPath, '--init-workspace', ...(args.skills ? ['--init-skills', String(args.skills)] : [])];await new Promise<void>((resolve, reject) => {const child = spawn(process.execPath, daemonArgs, {- stdio: 'inherit',+ stdio: output.installStdio(),cwd: process.cwd(),});child.on('close', code => {@@ -256,11 +254,11 @@ async function installBrowser() {const daemonProcessPatterns = ['run-mcp-server', 'run-cli-server', 'cli-daemon', 'cliDaemon.js', 'dashboardApp.js'];-async function killAllDaemons(): Promise<void> {+async function killAllDaemons(): Promise<number[]> {const platform = os.platform();const pidFilterEnv = process.env.PLAYWRIGHT_KILL_ALL_PID_FILTER_FOR_TEST;const pidFilter = pidFilterEnv ? new Set(pidFilterEnv.split(',').map(p => parseInt(p, 10)).filter(n => !isNaN(n))) : undefined;- let killed = 0;+ const killed: number[] = [];try {if (platform === 'win32') {@@ -279,8 +277,7 @@ async function killAllDaemons(): Promise<void> {.map(line => line.trim()).filter(line => /^\d+$/.test(line));for (const pid of pids)- console.log(`Killed daemon process ${pid}`);- killed = pids.length;+ killed.push(parseInt(pid, 10));} else {const result = execSync('ps auxww', { encoding: 'utf-8' });const lines = result.split('\n');@@ -294,8 +291,7 @@ async function killAllDaemons(): Promise<void> {continue;try {process.kill(numericPid, 'SIGKILL');- console.log(`Killed daemon process ${pid}`);- killed++;+ killed.push(numericPid);} catch {// Process may have already exited}@@ -306,130 +302,61 @@ async function killAllDaemons(): Promise<void> {} catch (e) {// Silently handle errors - no processes to kill is fine}-- if (killed === 0)- console.log('No daemon processes found.');- else if (killed > 0)- console.log(`Killed ${killed} daemon process${killed === 1 ? '' : 'es'}.`);+ return killed;}-async function listSessions(registry: Registry, clientInfo: ClientInfo, all: boolean): Promise<void> {- let count = 0;- const runningSessions = new Set<string>();+async function collectList(registry: Registry, clientInfo: ClientInfo, all: boolean): Promise<ListData> {+ const browsers: ListedBrowser[] = [];const entries = registry.entryMap();const key = clientKey(clientInfo);for (const [workspaceKey, list] of entries) {if (!all && workspaceKey !== key)continue;- if (count === 0)- console.log('### Browsers');- count += await gcAndPrintSessions(clientInfo, list.map(entry => new Session(entry)), all ? `${path.relative(process.cwd(), workspaceKey) || '/'}:` : undefined, runningSessions);- }-- if (!all) {- if (!count)- console.log(' (no browsers)');- return;- }-- // Filter out server entries that already have an attached session.- const serverEntries = await serverRegistry.list();- if (serverEntries.size) {- if (count)- console.log('');- console.log('### Browser servers available for attach');- }- for (const [workspaceKey, list] of serverEntries)- count += await gcAndPrintBrowserSessions(workspaceKey, list);-- if (!count)- console.log(' (no browsers)');-- const channelSessions = await listChannelSessions();- if (channelSessions.length) {- console.log('');- console.log('### Browsers available to attach via CDP');- for (const session of channelSessions) {- const text: string[] = [];- text.push(`- ${session.channel}:`);- text.push(` - data-dir: ${session.userDataDir}`);- if (session.endpoint) {- text.push(` - endpoint: ${session.endpoint}`);- text.push(` - run \`playwright-cli attach --cdp=${session.channel}\` to attach`);- } else {- text.push(` - status: remote debugging not enabled`);- text.push(` - ${remoteDebuggingHint(session.channel)}`);+ for (const entry of list) {+ const session = new Session(entry);+ const canConnect = await session.canConnect();+ if (!canConnect && !session.config.cli.persistent) {+ await session.deleteSessionConfig();+ continue;}- console.log(text.join('\n'));+ const config = session.config;+ const channel = config.browser?.launchOptions.channel ?? config.browser?.browserName;+ browsers.push({+ name: session.name,+ workspace: workspaceKey,+ status: canConnect ? 'open' : 'closed',+ browserType: channel,+ userDataDir: config.browser?.userDataDir ?? null,+ headed: config.browser ? !config.browser.launchOptions.headless : undefined,+ persistent: !!config.cli.persistent,+ attached: !!config.attached,+ compatible: session.isCompatible(clientInfo),+ version: config.version,+ });}}-}-async function gcAndPrintSessions(clientInfo: ClientInfo, sessions: Session[], header?: string, runningSessions?: Set<string>) {- const running: Session[] = [];- const stopped: Session[] = [];+ if (!all)+ return { all, browsers };- for (const session of sessions) {- const canConnect = await session.canConnect();- if (canConnect) {- running.push(session);- runningSessions?.add(session.name);- } else {- if (session.config.cli.persistent)- stopped.push(session);- else- await session.deleteSessionConfig();+ const serverEntries = await serverRegistry.list();+ const servers: ListedServer[] = [];+ for (const [workspaceKey, list] of serverEntries) {+ for (const descriptor of list) {+ servers.push({+ workspace: workspaceKey,+ title: descriptor.title,+ browser: descriptor.browser.browserName,+ playwrightVersion: descriptor.playwrightVersion,+ status: descriptor.canConnect ? 'open' : 'closed',+ userDataDir: descriptor.browser.userDataDir ?? null,+ });}}-- if (header && (running.length || stopped.length))- console.log(header);-- for (const session of running)- console.log(await renderSessionStatus(clientInfo, session));- for (const session of stopped)- console.log(await renderSessionStatus(clientInfo, session));-- return running.length + stopped.length;+ return { all, browsers, servers, channelSessions: await listChannelSessions() };}-async function gcAndPrintBrowserSessions(workspace: string, list: BrowserStatus[]): Promise<number> {- if (!list.length)- return 0;-- if (workspace)- console.log(`${path.relative(process.cwd(), workspace) || '/'}:`);-- for (const descriptor of list) {- const text: string[] = [];- text.push(`- browser "${descriptor.title}":`);- text.push(` - browser: ${descriptor.browser.browserName}`);- text.push(` - version: v${descriptor.playwrightVersion}`);- text.push(` - status: ${descriptor.canConnect ? 'open' : 'closed'}`);- if (descriptor.browser.userDataDir)- text.push(` - data-dir: ${descriptor.browser.userDataDir}`);- else- text.push(` - data-dir: <in-memory>`);- text.push(` - run \`playwright-cli attach "${descriptor.title}"\` to attach`);- console.log(text.join('\n'));- }- return list.length;-}--async function renderSessionStatus(clientInfo: ClientInfo, session: Session) {- const text: string[] = [];- const config = session.config;- const canConnect = await session.canConnect();- text.push(`- ${session.name}:`);- text.push(` - status: ${canConnect ? 'open' : 'closed'}`);- if (canConnect && !session.isCompatible(clientInfo))- text.push(` - version: v${config.version} [incompatible please re-open]`);- if (config.browser)- text.push(...renderResolvedConfig(config));- return text.join('\n');-}--function validateFlags(args: MinimistArgs, command: { flags: Record<string, 'boolean' | 'string'>, help: string }) {+function validateFlags(args: MinimistArgs, command: { flags: Record<string, 'boolean' | 'string'>, help: string }, output: Output) {const unknownFlags: string[] = [];for (const key of Object.keys(args)) {if (key === '_')@@ -439,12 +366,8 @@ function validateFlags(args: MinimistArgs, command: { flags: Record<string, 'booif (!(key in command.flags))unknownFlags.push(key);}- if (unknownFlags.length) {- console.error(`Unknown option${unknownFlags.length > 1 ? 's' : ''}: ${unknownFlags.map(f => `--${f}`).join(', ')}`);- console.log('');- console.log(command.help);- process.exit(1);- }+ if (unknownFlags.length)+ output.errorUnknownOption(unknownFlags, command.help);}export function calculateSha1(buffer: Buffer | string): string {diff --git a/packages/playwright-core/src/tools/cli-client/session.ts b/packages/playwright-core/src/tools/cli-client/session.tsindex 28ecb5886b..3aed7eee2e 100644--- a/packages/playwright-core/src/tools/cli-client/session.ts+++ b/packages/playwright-core/src/tools/cli-client/session.ts@@ -14,8 +14,6 @@* limitations under the License.*/-/* eslint-disable no-console */-import { spawn } from 'child_process';import fs from 'fs';@@ -44,57 +42,50 @@ export class Session {return compareSemver(clientInfo.version, this.config.version) >= 0;}- async run(clientInfo: ClientInfo, args: MinimistArgs, options?: { raw?: boolean }): Promise<{ text: string }> {+ async run(clientInfo: ClientInfo, args: MinimistArgs, options?: { raw?: boolean, json?: boolean }): Promise<{ text: string }> {if (!this.isCompatible(clientInfo))throw new Error(`Client is v${clientInfo.version}, session '${this.name}' is v${this.config.version}. Run\n\n playwright-cli${this.name !== 'default' ? ` -s=${this.name}` : ''} open\n\nto restart the browser session.`);const { socket } = await this._connect();if (!socket)throw new Error(`Browser '${this.name}' is not open. Run\n\n playwright-cli${this.name !== 'default' ? ` -s=${this.name}` : ''} open\n\nto start the browser session.`);- return await SocketConnectionClient.sendAndClose(socket, 'run', { args, cwd: process.cwd(), raw: options?.raw });+ return await SocketConnectionClient.sendAndClose(socket, 'run', { args, cwd: process.cwd(), raw: options?.raw, json: options?.json });}- async stop(quiet: boolean = false): Promise<void> {- if (!await this.canConnect()) {- if (!quiet)- console.log(`Browser '${this.name}' is not open.`);- return;- }-+ async stop(): Promise<{ wasOpen: boolean }> {+ if (!await this.canConnect())+ return { wasOpen: false };await this._stopDaemon();- if (!quiet)- console.log(`Browser '${this.name}' closed\n`);+ return { wasOpen: true };}- async deleteData() {- await this.stop(true);+ async deleteData(): Promise<{ existed: boolean, deletedUserDataDir: boolean }> {+ await this.stop();const dataDirs = await fs.promises.readdir(this._sessionFile.daemonDir).catch(() => []);const matchingEntries = dataDirs.filter(file => file === `${this.name}.session` || file.startsWith(`ud-${this.name}-`));- if (matchingEntries.length === 0) {- console.log(`No user data found for browser '${this.name}'.`);- return;- }+ if (matchingEntries.length === 0)+ return { existed: false, deletedUserDataDir: false };+ let deletedUserDataDir = false;for (const entry of matchingEntries) {const userDataDir = path.resolve(this._sessionFile.daemonDir, entry);for (let i = 0; i < 5; i++) {try {await fs.promises.rm(userDataDir, { recursive: true });if (entry.startsWith('ud-'))- console.log(`Deleted user data for browser '${this.name}'.`);+ deletedUserDataDir = true;break;} catch (e: any) {- if (e.code === 'ENOENT') {- console.log(`No user data found for browser '${this.name}'.`);+ if (e.code === 'ENOENT')break;- }await new Promise(resolve => setTimeout(resolve, 1000));if (i === 4)throw e;}}}+ return { existed: true, deletedUserDataDir };}private async _connect(): Promise<{ socket?: net.Socket, error?: Error }> {@@ -120,7 +111,7 @@ export class Session {return false;}- static async startDaemon(clientInfo: ClientInfo, cliArgs: MinimistArgs, mode: 'open' | 'attach') {+ static async startDaemon(clientInfo: ClientInfo, cliArgs: MinimistArgs, mode: 'open' | 'attach'): Promise<{ pid: number | undefined, sessionName: string, endpoint: string | undefined }> {await fs.promises.mkdir(clientInfo.daemonProfilesDir, { recursive: true });const cliPath = libPath('entry', 'cliDaemon.js');@@ -201,20 +192,13 @@ export class Session {child.stdout!.destroy();child.unref();- if (cliArgs['endpoint']) {- console.log(`### Session \`${sessionName}\` created, attached to \`${cliArgs['endpoint']}\`.`);- console.log(`Run commands with: playwright-cli --session=${sessionName} <command>`);- } else {- console.log(`### Browser \`${sessionName}\` opened with pid ${child.pid}.`);- }+ return { pid: child.pid, sessionName, endpoint: cliArgs.endpoint as string | undefined };}private async _stopDaemon(): Promise<void> {- const { socket, error: socketError } = await this._connect();- if (!socket) {- console.log(`Browser '${this.name}' is not open.${socketError ? ' Error: ' + socketError.message : ''}`);+ const { socket } = await this._connect();+ if (!socket)return;- }let error: Error | undefined;await SocketConnectionClient.sendAndClose(socket, 'stop', {}).catch(e => error = e);@@ -227,24 +211,6 @@ export class Session {}}-export function renderResolvedConfig(config: SessionConfig) {- const channel = config.browser.launchOptions.channel ?? config.browser.browserName;- const lines = [];- const isAttached = config.attached;- if (channel)- lines.push(` - browser-type: ${channel}${isAttached ? ' (attached)' : ''}`);-- if (!isAttached) {- if (!config.cli.persistent)- lines.push(` - user-data-dir: <in-memory>`);- else- lines.push(` - user-data-dir: ${config.browser.userDataDir}`);- lines.push(` - headed: ${!config.browser.launchOptions.headless}`);- }-- return lines;-}-class SocketConnectionClient {private _connection: SocketConnection;private _nextMessageId = 1;diff --git a/packages/playwright-core/src/tools/cli-client/skill/SKILL.md b/packages/playwright-core/src/tools/cli-client/skill/SKILL.mdindex c38e2ed07c..8a22932e73 100644--- a/packages/playwright-core/src/tools/cli-client/skill/SKILL.md+++ b/packages/playwright-core/src/tools/cli-client/skill/SKILL.md@@ -185,6 +185,11 @@ TOKEN=$(playwright-cli --raw cookie-get session_id)playwright-cli --raw localstorage-get theme```+For structured output wrapping every reply as JSON, pass --json+```bash+playwright-cli list --json+```+## Open parameters```bash# Use specific browser when creating sessiondiff --git a/packages/playwright-core/src/tools/cli-daemon/daemon.ts b/packages/playwright-core/src/tools/cli-daemon/daemon.tsindex 8cd65b1945..84c6154610 100644--- a/packages/playwright-core/src/tools/cli-daemon/daemon.ts+++ b/packages/playwright-core/src/tools/cli-daemon/daemon.ts@@ -90,7 +90,7 @@ export async function startCliDaemonServer(await sendAck();} else if (method === 'run') {const { toolName, toolParams } = parseCliCommand(params.args);- toolParams._meta = { cwd: params.cwd, raw: params.raw };+ toolParams._meta = { cwd: params.cwd, raw: params.raw || params.json, json: !!params.json };const response = await backend.callTool(toolName, toolParams);await connection.send({ id, result: formatResult(response) });} else {diff --git a/packages/playwright-core/src/tools/cli-daemon/helpGenerator.ts b/packages/playwright-core/src/tools/cli-daemon/helpGenerator.tsindex c167a2e115..08634ff924 100644--- a/packages/playwright-core/src/tools/cli-daemon/helpGenerator.ts+++ b/packages/playwright-core/src/tools/cli-daemon/helpGenerator.ts@@ -104,6 +104,7 @@ export function generateHelp() {lines.push('\nGlobal options:');lines.push(formatWithGap(' --help [command]', 'print help'));+ lines.push(formatWithGap(' --json', 'output response as JSON'));lines.push(formatWithGap(' --raw', 'output only the result value, without status and code'));lines.push(formatWithGap(' --version', 'print version'));diff --git a/tests/mcp/cli-json.spec.ts b/tests/mcp/cli-json.spec.tsnew file mode 100644index 0000000000..d026b8ca9e--- /dev/null+++ b/tests/mcp/cli-json.spec.ts@@ -0,0 +1,181 @@+/**+ * 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 { test, expect } from './cli-fixtures';++const SNAPSHOT_FILE = expect.stringMatching(/^\.playwright-cli\/page-[\dTZ:.-]+\.yml$/);++test('output is pretty-printed', async ({ cli }) => {+ const { output } = await cli('--json', 'list');+ expect(output).toBe(`{+ "browsers": []+}`);+});++test('version command returns JSON', async ({ cli }) => {+ const { output } = await cli('--json', '--version');+ const parsed = JSON.parse(output);+ expect(parsed).toEqual({ version: expect.any(String) });+});++test('unknown command returns JSON error with exit 1', async ({ cli }) => {+ const { output, exitCode } = await cli('--json', 'nope');+ expect(JSON.parse(output)).toEqual({ isError: true, error: 'Unknown command: nope' });+ expect(exitCode).toBe(1);+});++test('unknown flag returns JSON error with exit 1', async ({ cli }) => {+ const { output, exitCode } = await cli('--json', 'list', '--bogus');+ expect(JSON.parse(output)).toEqual({ isError: true, error: 'Unknown option: --bogus' });+ expect(exitCode).toBe(1);+});++test('running tool command without open browser returns JSON error', async ({ cli }) => {+ const { output, exitCode } = await cli('--json', 'goto', 'about:blank');+ expect(JSON.parse(output)).toEqual({+ isError: true,+ error: `The browser 'default' is not open, please run open first`,+ });+ expect(exitCode).toBe(1);+});++test('list returns empty browsers before open', async ({ cli }) => {+ const { output } = await cli('--json', 'list');+ expect(JSON.parse(output)).toEqual({ browsers: [] });+});++test('close returns not-open status when nothing is running', async ({ cli }) => {+ const { output } = await cli('--json', 'close');+ expect(JSON.parse(output)).toEqual({ session: 'default', status: 'not-open' });+});++test('delete-data returns not-deleted when there is no session', async ({ cli }) => {+ const { output } = await cli('--json', 'delete-data');+ expect(JSON.parse(output)).toEqual({ session: 'default', deleted: false });+});++test('kill-all returns zero killed when filter matches nothing', async ({ cli }) => {+ const { output } = await cli('--json', 'kill-all', { env: { PLAYWRIGHT_KILL_ALL_PID_FILTER_FOR_TEST: '0' } });+ expect(JSON.parse(output)).toEqual({ killed: 0, pids: [] });+});++test('open returns envelope with session, pid and snapshot file', async ({ cli, server }) => {+ const { output } = await cli('--json', 'open', server.HELLO_WORLD);+ expect(JSON.parse(output)).toEqual({+ session: 'default',+ pid: expect.any(Number),+ result: { snapshot: { file: SNAPSHOT_FILE } },+ });+});++test('list after open returns one browser entry', async ({ cli, server, mcpBrowser }) => {+ await cli('open', server.HELLO_WORLD);+ const { output } = await cli('--json', 'list');+ expect(JSON.parse(output)).toEqual({+ browsers: [{+ name: 'default',+ workspace: expect.any(String),+ status: 'open',+ browserType: mcpBrowser,+ userDataDir: null,+ headed: false,+ persistent: false,+ attached: false,+ compatible: true,+ version: expect.any(String),+ }],+ });+});++test('goto returns snapshot file envelope', async ({ cli, server }) => {+ await cli('open', server.HELLO_WORLD);+ const { output } = await cli('--json', 'goto', server.HELLO_WORLD);+ expect(JSON.parse(output)).toEqual({ snapshot: { file: SNAPSHOT_FILE } });+});++test('eval returns result string', async ({ cli, server }) => {+ await cli('open', server.HELLO_WORLD);+ const { output } = await cli('--json', 'eval', '() => 1 + 2');+ expect(JSON.parse(output)).toEqual({ result: '3' });+});++test('eval with error surfaces isError JSON', async ({ cli, server }) => {+ await cli('open', server.HELLO_WORLD);+ const { output } = await cli('--json', 'eval', '() => { throw new Error("boom"); }');+ const parsed = JSON.parse(output);+ expect(parsed.isError).toBe(true);+ expect(parsed.error).toContain('boom');+});++test('tab-new creates a new tab and returns tab list', async ({ cli, server }) => {+ await cli('open', server.HELLO_WORLD);+ const { output } = await cli('--json', 'tab-new');+ const parsed = JSON.parse(output);+ expect(parsed.result.split('\n')).toEqual([+ `- 0: [Title](${server.HELLO_WORLD})`,+ '- 1: (current) [](about:blank)',+ ]);+});++test('tab-list lists all tabs', async ({ cli, server }) => {+ await cli('open', server.HELLO_WORLD);+ await cli('tab-new');+ const { output } = await cli('--json', 'tab-list');+ const parsed = JSON.parse(output);+ expect(parsed.result.split('\n')).toEqual([+ `- 0: [Title](${server.HELLO_WORLD})`,+ '- 1: (current) [](about:blank)',+ ]);+});++test('tab-close closes a tab and returns remaining tabs', async ({ cli, server }) => {+ await cli('open', server.HELLO_WORLD);+ await cli('tab-new');+ const { output } = await cli('--json', 'tab-close');+ const parsed = JSON.parse(output);+ expect(parsed.result.split('\n')).toEqual([+ `- 0: (current) [Title](${server.HELLO_WORLD})`,+ ]);+});++test('snapshot returns inline snapshot yaml', async ({ cli, server }) => {+ server.setContent('/', '<h1>Hi</h1>', 'text/html');+ await cli('open', server.PREFIX);+ const { output } = await cli('--json', 'snapshot');+ const parsed = JSON.parse(output);+ expect(typeof parsed.snapshot).toBe('string');+ expect(parsed.snapshot).toContain('heading "Hi"');+});++test('tool error on bad navigation returns JSON error', async ({ cli, server }) => {+ await cli('open', server.HELLO_WORLD);+ const { output } = await cli('--json', 'goto', 'https://not-a-real-domain.example.invalid');+ const parsed = JSON.parse(output);+ expect(parsed.isError).toBe(true);+ expect(typeof parsed.error).toBe('string');+});++test('close after open returns closed status', async ({ cli, server }) => {+ await cli('open', server.HELLO_WORLD);+ const { output } = await cli('--json', 'close');+ expect(JSON.parse(output)).toEqual({ session: 'default', status: 'closed' });+});++test('close-all after open returns closed sessions', async ({ cli, server }) => {+ await cli('open', server.HELLO_WORLD);+ const { output } = await cli('--json', 'close-all');+ expect(JSON.parse(output)).toEqual({ closed: ['default'] });+});