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 { program } from 'commander';
import { gracefullyProcessExitDoNotHang } from '@utils/processLauncher';
import { getPackageManagerExecCommand } from '@utils/env';
import { packageJSON } from '../package';
import { addTraceCommands } from '../tools/trace/traceCli';
import { runDriver, runServer, launchBrowserServer } from './driver';
import { markDockerImage } from './installActions';
import { open, codegen } from './browserActions';
import { installBrowsers, uninstallBrowsers, installDeps } from './installActions';
import { runTraceInBrowser, runTraceViewerApp } from '../server/trace/viewer/traceViewer';
import { screenshot, pdf } from './browserActions';
import { program as cliProgram } from '../tools/cli-client/program';
import { decorateMCPCommand } from '../tools/mcp/program';
import type { TraceViewerServerOptions } from '../server/trace/viewer/traceViewer';
import type { Command } from 'commander';
export function decorateProgram(program: Command) {
program
.version('Version ' + (process.env.PW_CLI_DISPLAY_VERSION || packageJSON.version))
.name(buildBasePlaywrightCLICommand(process.env.PW_LANG_NAME));
program
.command('mark-docker-image [dockerImageNameTemplate]', { hidden: true })
.description('mark docker image')
.allowUnknownOption(true)
.action(async function(dockerImageNameTemplate) {
markDockerImage(dockerImageNameTemplate).catch(logErrorAndExit);
});
commandWithOpenOptions('open [url]', 'open page in browser specified via -b, --browser', [])
.action(async function(url, options) {
open(options, url).catch(logErrorAndExit);
})
.addHelpText('afterAll', `
Examples:
$ open
$ open -b webkit https://example.com`);
commandWithOpenOptions('codegen [url]', 'open page and generate code for user actions',
[
['-o, --output <file name>', 'saves the generated script to a file'],
['--target <language>', `language to generate, one of javascript, playwright-test, python, python-async, python-pytest, csharp, csharp-mstest, csharp-nunit, csharp-xunit, java, java-junit`, codegenId()],
['--test-id-attribute <attributeName>', 'use the specified attribute to generate data test ID selectors'],
]).action(async function(url, options) {
await codegen(options, url);
}).addHelpText('afterAll', `
Examples:
$ codegen
$ codegen --target=python
$ codegen -b webkit https://example.com`);
program
.command('install [browser...]')
.description('ensure browsers necessary for this version of Playwright are installed')
.option('--with-deps', 'install system dependencies for browsers')
.option('--dry-run', 'do not execute installation, only print information')
.option('--list', 'prints list of browsers from all playwright installations')
.option('--force', 'force reinstall of already installed browsers')
.option('--only-shell', 'only install headless shell when installing chromium')
.option('--no-shell', 'do not install chromium headless shell')
.option('--no-progress', 'do not show download progress bars')
.option('--no-remove', 'do not remove unused browsers')
.action(async function(args: string[], options: { withDeps?: boolean, force?: boolean, dryRun?: boolean, list?: boolean, shell?: boolean, onlyShell?: boolean, progress?: boolean, remove?: boolean }) {
try {
await installBrowsers(args, options);
} catch (e) {
console.log(`Failed to install browsers\n${e}`);
gracefullyProcessExitDoNotHang(1);
}
}).addHelpText('afterAll', `
Examples:
- $ install
Install default browsers.
- $ install chrome firefox
Install custom browsers, supports chromium, firefox, webkit, chromium-headless-shell.`);
program
.command('uninstall')
.description('Removes browsers used by this installation of Playwright from the system (chromium, firefox, webkit, ffmpeg). This does not include branded channels.')
.option('--all', 'Removes all browsers used by any Playwright installation from the system.')
.action(async (options: { all?: boolean }) => {
uninstallBrowsers(options).catch(logErrorAndExit);
});
program
.command('install-deps [browser...]')
.description('install dependencies necessary to run browsers (will ask for sudo permissions)')
.option('--dry-run', 'Do not modify the system. On Linux, simulate the install via apt-get and exit with a non-zero code if any required packages are missing; on Windows, print the install command.')
.action(async function(args: string[], options: { dryRun?: boolean }) {
try {
await installDeps(args, options);
} catch (e) {
console.log(`Failed to install browser dependencies\n${e}`);
gracefullyProcessExitDoNotHang(1);
}
}).addHelpText('afterAll', `
Examples:
- $ install-deps
Install dependencies for default browsers.
- $ install-deps chrome firefox
Install dependencies for specific browsers, supports chromium, firefox, webkit, chromium-headless-shell.
- $ install-deps --dry-run
Report which required system dependencies are missing without modifying the system. Exits non-zero if any are missing. Useful for non-interactive verification scripts.`);
const browsers = [
{ alias: 'cr', name: 'Chromium', type: 'chromium' },
{ alias: 'ff', name: 'Firefox', type: 'firefox' },
{ alias: 'wk', name: 'WebKit', type: 'webkit' },
];
for (const { alias, name, type } of browsers) {
commandWithOpenOptions(`${alias} [url]`, `open page in ${name}`, [])
.action(async function(url, options) {
open({ ...options, browser: type }, url).catch(logErrorAndExit);
}).addHelpText('afterAll', `
Examples:
$ ${alias} https://example.com`);
}
commandWithOpenOptions('screenshot <url> <filename>', 'capture a page screenshot',
[
['--wait-for-selector <selector>', 'wait for selector before taking a screenshot'],
['--wait-for-timeout <timeout>', 'wait for timeout in milliseconds before taking a screenshot'],
['--full-page', 'whether to take a full page screenshot (entire scrollable area)'],
]).action(async function(url, filename, command) {
screenshot(command, command, url, filename).catch(logErrorAndExit);
}).addHelpText('afterAll', `
Examples:
$ screenshot -b webkit https://example.com example.png`);
commandWithOpenOptions('pdf <url> <filename>', 'save page as pdf',
[
['--paper-format <format>', 'paper format: Letter, Legal, Tabloid, Ledger, A0, A1, A2, A3, A4, A5, A6'],
['--wait-for-selector <selector>', 'wait for given selector before saving as pdf'],
['--wait-for-timeout <timeout>', 'wait for given timeout in milliseconds before saving as pdf'],
]).action(async function(url, filename, options) {
pdf(options, options, url, filename).catch(logErrorAndExit);
}).addHelpText('afterAll', `
Examples:
$ pdf https://example.com example.pdf`);
program
.command('run-driver', { hidden: true })
.action(async function(options) {
runDriver();
});
program
.command('run-server', { hidden: true })
.option('--port <port>', 'Server port')
.option('--host <host>', 'Server host')
.option('--path <path>', 'Endpoint Path', '/')
.option('--max-clients <maxClients>', 'Maximum clients')
.option('--mode <mode>', 'Server mode, either "default" or "extension"')
.option('--artifacts-dir <artifactsDir>', 'Artifacts directory')
.option('--unsafe', 'Allow clients to set unsafe launch options (args, executablePath, ignoreAllDefaultArgs, etc)')
.action(async function(options) {
runServer({
port: options.port ? +options.port : undefined,
host: options.host,
path: options.path,
maxConnections: options.maxClients ? +options.maxClients : Infinity,
extension: options.mode === 'extension' || !!process.env.PW_EXTENSION_MODE,
artifactsDir: options.artifactsDir,
unsafe: !!options.unsafe,
}).catch(logErrorAndExit);
});
program
.command('launch-server', { hidden: true })
.requiredOption('--browser <browserName>', 'Browser name, one of "chromium", "firefox" or "webkit"')
.option('--config <path-to-config-file>', 'JSON file with launchServer options')
.action(async function(options) {
launchBrowserServer(options.browser, options.config);
});
program
.command('show-trace [trace]')
.option('-b, --browser <browserType>', 'browser to use, one of cr, chromium, ff, firefox, wk, webkit', 'chromium')
.option('-h, --host <host>', 'Host to serve trace on; specifying this option opens trace in a browser tab')
.option('-p, --port <port>', 'Port to serve trace on, 0 for any free port; specifying this option opens trace in a browser tab')
.option('--stdin', 'Accept trace URLs over stdin to update the viewer')
.description('show trace viewer')
.action(async function(trace, options) {
if (options.browser === 'cr')
options.browser = 'chromium';
if (options.browser === 'ff')
options.browser = 'firefox';
if (options.browser === 'wk')
options.browser = 'webkit';
const openOptions: TraceViewerServerOptions = {
host: options.host,
port: +options.port,
isServer: !!options.stdin,
};
if (options.port !== undefined || options.host !== undefined)
runTraceInBrowser(trace, openOptions).catch(logErrorAndExit);
else
runTraceViewerApp(trace, options.browser, openOptions).catch(logErrorAndExit);
}).addHelpText('afterAll', `
Examples:
$ show-trace
$ show-trace https://example.com/trace.zip`);
addTraceCommands(program, logErrorAndExit);
program
.command('cli')
.description('run playwright cli commands from terminal')
.allowExcessArguments(true)
.allowUnknownOption(true)
.helpOption(false)
.action(async options => {
process.argv.splice(process.argv.indexOf('cli'), 1);
cliProgram().catch(logErrorAndExit);
});
decorateMCPCommand(program
.command('mcp')
.description('run the Playwright MCP server'));
}
function logErrorAndExit(e: Error) {
if (process.env.PWDEBUGIMPL)
console.error(e);
else
console.error(e.name + ': ' + e.message);
gracefullyProcessExitDoNotHang(1);
}
function codegenId(): string {
return process.env.PW_LANG_NAME || 'playwright-test';
}
function commandWithOpenOptions(command: string, description: string, options: any[][]): Command {
let result = program.command(command).description(description);
for (const option of options)
result = result.option(option[0], ...option.slice(1));
return result
.option('-b, --browser <browserType>', 'browser to use, one of cr, chromium, ff, firefox, wk, webkit', 'chromium')
.option('--block-service-workers', 'block service workers')
.option('--channel <channel>', 'Chromium distribution channel, "chrome", "chrome-beta", "msedge-dev", etc')
.option('--color-scheme <scheme>', 'emulate preferred color scheme, "light" or "dark"')
.option('--device <deviceName>', 'emulate device, for example "iPhone 11"')
.option('--geolocation <coordinates>', 'specify geolocation coordinates, for example "37.819722,-122.478611"')
.option('--http-credentials <credentials>', 'specify HTTP authentication credentials as "username:password", for example --http-credentials="admin:secret"')
.option('--ignore-https-errors', 'ignore https errors')
.option('--load-storage <filename>', 'load context storage state from the file, previously saved with --save-storage')
.option('--lang <language>', 'specify language / locale, for example "en-GB"')
.option('--proxy-server <proxy>', 'specify proxy server, for example "http://myproxy:3128", "http://user:password@myproxy:3128" or "socks5://myproxy:8080"')
.option('--proxy-bypass <bypass>', 'comma-separated domains to bypass proxy, for example ".com,chromium.org,.domain.com"')
.option('--save-har <filename>', 'save HAR file with all network activity at the end')
.option('--save-har-glob <glob pattern>', 'filter entries in the HAR by matching url against this glob pattern')
.option('--save-storage <filename>', 'save context storage state at the end, for later use with --load-storage')
.option('--timezone <time zone>', 'time zone to emulate, for example "Europe/Rome"')
.option('--timeout <timeout>', 'timeout for Playwright actions in milliseconds, no timeout by default')
.option('--user-agent <ua string>', 'specify user agent string')
.option('--user-data-dir <directory>', 'use the specified user data directory instead of a new context')
.option('--viewport-size <size>', 'specify browser viewport size in pixels, for example "1280, 720"');
}
function buildBasePlaywrightCLICommand(cliTargetLang: string | undefined): string {
switch (cliTargetLang) {
case 'python':
return `playwright`;
case 'java':
return `mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="...options.."`;
case 'csharp':
return `pwsh bin/Debug/netX/playwright.ps1`;
default: {
const packageManagerCommand = getPackageManagerExecCommand();
return `${packageManagerCommand} playwright`;
}
}
}