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
/**
* 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 path from 'path';
import { playwrightExtensionInstallUrl } from '../utils/extension';
import { processExit } from '../../bootstrap';
import type { ChannelSession } from './channelSessions';
import type { BrowserDescriptor } from '../../serverRegistry';
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 ListData = {
all: boolean;
browsers: ListedBrowser[];
servers?: BrowserDescriptor[];
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;
errorTooManyArguments(expected: number, received: number, commandHelp: string): never;
errorAttachConflict(): never;
errorDetachNotAttached(session: string): never;
errorBrowserNotOpenForTool(session: string): never;
errorAttachNoTarget(): never;
errorInstallGlobalRequiresSkills(): 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;
detach(session: string, wasAttached: 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);
// eslint-disable-next-line no-restricted-syntax
return processExit(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);
// eslint-disable-next-line no-restricted-syntax
return processExit(1);
}
errorTooManyArguments(expected: number, received: number, commandHelp: string): never {
console.error(`error: too many arguments: expected ${expected}, received ${received}`);
console.log('');
console.log(commandHelp);
// eslint-disable-next-line no-restricted-syntax
return processExit(1);
}
errorAttachConflict(): never {
console.error(`Error: only one of [name], --cdp, --endpoint, or --extension can be specified`);
// eslint-disable-next-line no-restricted-syntax
return processExit(1);
}
errorDetachNotAttached(session: string): never {
console.error(`Error: session '${session}' was not attached; use \`playwright-cli${session !== 'default' ? ` -s=${session}` : ''} close\` to stop it.`);
// eslint-disable-next-line no-restricted-syntax
return processExit(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]`);
// eslint-disable-next-line no-restricted-syntax
return processExit(1);
}
errorAttachNoTarget(): never {
console.error(`Error: no target specified for attach command; use one of [name], --cdp, --endpoint, or --extension to specify the target to attach to.`);
// eslint-disable-next-line no-restricted-syntax
return processExit(1);
}
errorInstallGlobalRequiresSkills(): never {
console.error(`Error: --global requires --skills`);
// eslint-disable-next-line no-restricted-syntax
return processExit(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, BrowserDescriptor[]>();
for (const server of servers) {
let list = serversByWorkspace.get(server.workspaceDir ?? '');
if (!list) {
list = [];
serversByWorkspace.set(server.workspaceDir ?? '', 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 -s=${session} <command>`);
console.log('');
} 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`);
}
detach(session: string, wasAttached: boolean): void {
if (!wasAttached) {
console.log(`Browser '${session}' is not attached.`);
return;
}
console.log(`Browser '${session}' detached\n`);
}
installed(): void {
// The spawned install subprocess handles its own output.
}
show(_session: string, pid: number | undefined): void {
if (process.env.PWTEST_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}` });
// eslint-disable-next-line no-restricted-syntax
return processExit(1);
}
errorUnknownOption(opts: string[], _commandHelp: string): never {
this._emit({ isError: true, error: `Unknown option${opts.length > 1 ? 's' : ''}: ${opts.map(f => `--${f}`).join(', ')}` });
// eslint-disable-next-line no-restricted-syntax
return processExit(1);
}
errorTooManyArguments(expected: number, received: number, _commandHelp: string): never {
this._emit({ isError: true, error: `error: too many arguments: expected ${expected}, received ${received}` });
// eslint-disable-next-line no-restricted-syntax
return processExit(1);
}
errorAttachConflict(): never {
this._emit({ isError: true, error: `only one of [name], --cdp, --endpoint, or --extension can be specified` });
// eslint-disable-next-line no-restricted-syntax
return processExit(1);
}
errorDetachNotAttached(session: string): never {
this._emit({ isError: true, error: `session '${session}' was not attached; use close to stop it.` });
// eslint-disable-next-line no-restricted-syntax
return processExit(1);
}
errorBrowserNotOpenForTool(session: string): never {
this._emit({ isError: true, error: `The browser '${session}' is not open, please run open first` });
// eslint-disable-next-line no-restricted-syntax
return processExit(1);
}
errorAttachNoTarget(): never {
this._emit({ isError: true, error: `no target specified for attach command; use one of [name], --cdp, --endpoint, or --extension to specify the target to attach to.` });
// eslint-disable-next-line no-restricted-syntax
return processExit(1);
}
errorInstallGlobalRequiresSkills(): never {
this._emit({ isError: true, error: `--global requires --skills` });
// eslint-disable-next-line no-restricted-syntax
return processExit(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' });
}
detach(session: string, wasAttached: boolean): void {
this._emit({ session, status: wasAttached ? 'detached' : 'not-attached' });
}
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: BrowserDescriptor): string {
const lines = [`- browser "${server.title}":`];
lines.push(` - browser: ${server.browser.browserName}`);
lines.push(` - version: v${server.playwrightVersion}`);
if (server.browser.userDataDir)
lines.push(` - data-dir: ${server.browser.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.extensionInstalled)
lines.push(` - attach (extension): \`playwright-cli attach --extension=${session.channel}\``);
else
lines.push(` - attach (extension): install at ${playwrightExtensionInstallUrl}`);
if (session.endpoint) {
lines.push(` - attach (remote debugging): \`playwright-cli attach --cdp=${session.channel}\``);
} else {
const inspectScheme = session.channel.startsWith('msedge') ? 'edge' : 'chrome';
lines.push(` - attach (remote debugging): enable at ${inspectScheme}://inspect/#remote-debugging`);
}
return lines.join('\n');
}