Skip to content

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

13.1 KB
Raw Blame

id: test-cli title: "Command line"

Playwright provides a powerful command line interface for running tests, generating code, debugging, and more. The most up to date list of commands and arguments available on the CLI can always be retrieved via npx playwright --help.

Essential Commands

Run Tests

Run your Playwright tests. Read more about running tests.

Syntax

npx playwright test [options] [test-filter...]

Examples

# Run all tests
npx playwright test

# Run a single test file
npx playwright test tests/todo-page.spec.ts

# Run a set of test files
npx playwright test tests/todo-page/ tests/landing-page/

# Run tests at a specific line
npx playwright test my-spec.ts:42

# Run tests by title
npx playwright test -g "add a todo item"

# Run tests in headed browsers
npx playwright test --headed

# Run tests for a specific project
npx playwright test --project=chromium

# Get help
npx playwright test --help

Disable parallelization

npx playwright test --workers=1

Run in debug mode with Playwright Inspector

npx playwright test --debug

Run tests in interactive UI mode

npx playwright test --ui

Common Options

Option Description
--debug [mode] Run tests with Playwright Inspector. Shortcut for PWDEBUG=1 environment variable and --timeout=0 --max-failures=1 --headed --workers=1 options. The optional mode is "inspector" (default) or "cli" — "cli" allows attaching and debugging over the CLI.
--headed Run tests in headed browsers (default: headless).
-g <grep> or --grep <grep> Only run tests matching this regular expression (default: ".*").
--project <project-name...> Only run tests from the specified list of projects, supports '*' wildcard (default: run all projects).
--ui Run tests in interactive UI mode.
-j <workers> or --workers <workers> Number of concurrent workers or percentage of logical CPU cores, use 1 to run in a single worker (default: 50%).

All Options

Option Description
Non-option arguments Each argument is treated as a regular expression matched against the full test file path. Only tests from files matching the pattern will be executed. Special symbols like $ or * should be escaped with \. In many shells/terminals you may need to quote the arguments.
--add-reporter <reporter> Reporter to add on top of the reporters configured in the config file, comma-separated. Can be a built-in reporter name or a path to a custom reporter file. Unlike --reporter, this keeps the configured reporters instead of replacing them.
-c <file> or --config <file> Configuration file, or a test directory with optional "playwright.config.{m,c}?{js,ts}". Defaults to playwright.config.ts or playwright.config.js in the current directory.
--debug [mode] Run tests with Playwright Inspector. Shortcut for PWDEBUG=1 environment variable and --timeout=0 --max-failures=1 --headed --workers=1 options. The optional mode is "inspector" (default) or "cli" — "cli" allows attaching and debugging over the CLI.
--fail-on-flaky-tests Fail if any test is flagged as flaky (default: false).
--forbid-only Fail if test.only is called (default: false). Useful on CI.
--fully-parallel Run all tests in parallel (default: false).
--global-timeout <timeout> Maximum time this test suite can run in milliseconds (default: unlimited).
-g <grep> or --grep <grep> Only run tests matching this regular expression (default: ".*").
-G <grep> or --grep-invert <grep> Only run tests that do not match this regular expression.
--headed Run tests in headed browsers (default: headless).
--ignore-snapshots Ignore screenshot and snapshot expectations.
-j <workers> or --workers <workers> Number of concurrent workers or percentage of logical CPU cores, use 1 to run in a single worker (default: 50%).
--last-failed Only re-run the failures.
--last-failed-file <file> Override the default last-run JSON path for --last-failed (default: <outputDir>/.last-run.json). Same as PLAYWRIGHT_LAST_RUN_OUTPUT_FILE environment variable.
--list Collect all the tests and report them, but do not run.
--max-failures <N> or -x Stop after the first N failures. Passing -x stops after the first failure.
--no-deps Do not run project dependencies.
--output <dir> Folder for output artifacts (default: "test-results").
--only-changed [ref] Only run test files that have been changed between 'HEAD' and 'ref'. Defaults to running all uncommitted changes. Only supports Git.
--pass-with-no-tests Makes test run succeed even if no tests were found.
--project <project-name...> Only run tests from the specified list of projects, supports '*' wildcard (default: run all projects).
--quiet Suppress stdio.
--repeat-each <N> Run each test N times (default: 1).
--reporter <reporter> Reporter to use, comma-separated, can be "dot", "line", "list", "failures", or others (default: "list" locally and "dot" on CI). You can also pass a path to a custom reporter file.
--reporter-only-failures Include only failed, flaky, and interrupted tests in JSON, JUnit, and HTML reports.
--retries <retries> Maximum retry count for flaky tests, zero for no retries (default: no retries).
--run-agents <mode> Run agents to generate the code for page.perform. Possible values are "missing", "all" and "none" (default: "none"). See test-agents.
--shard <shard> Shard tests and execute only the selected shard, specified in the form "current/all", 1-based, e.g., "3/5".
--shuffle [seed] Schedule tests in a random order: test files are shuffled, and so are individual tests in parallel mode. Tests that must run together, for example in a serial suite, keep their order. The seed is printed at the start of the run, pass it to reproduce the same order.
--test-list <file> Path to a file containing a list of tests to run. See test list for details.
--test-list-invert <file> Path to a file containing a list of tests to skip. See test list for details.
--timeout <timeout> Specify test timeout threshold in milliseconds, zero for unlimited (default: 30 seconds).
--trace <mode> Force tracing mode, can be on, off, on-first-retry, on-all-retries, retain-on-failure, retain-on-first-failure, retain-on-failure-and-retries.
--tsconfig <path> Path to a single tsconfig applicable to all imported files (default: look up tsconfig for each imported file separately).
--ui Run tests in interactive UI mode.
--ui-host <host> Host to serve UI on; specifying this option opens UI in a browser tab.
--ui-port <port> Port to serve UI on, 0 for any free port; specifying this option opens UI in a browser tab.
-u or --update-snapshots [mode] Update snapshots with actual results. Possible values are "all", "changed", "missing", "none" and "default". Running tests without the flag defaults to "default"; running tests with the flag but without a value defaults to "changed".
--update-source-method <method> Chooses the way source is updated. Possible values are "patch" (default), "3way" and "overwrite". "Patch" creates a unified diff file that can be used to update the source code later. "3way" generates merge conflict markers in source code. "Overwrite" overwrites the source code with the new snapshot values.
-x Stop after the first failure.

Test list

Options --test-list and --test-list-invert accept a path to a test list file. This file should list tests in the format similar to the output produced in --list mode.

# This is a test list file.
# It can include comments and empty lines.

# Run ALL tests in a file:
path/to/example.spec.ts

# Run all tests in a file for a specific project:
[chromium] › path/to/example.spec.ts

# Run all tests in a specific group/suite:
path/to/example.spec.ts › suite name

# Run all tests in a nested group:
path/to/example.spec.ts › outer suite › inner suite

# Fully qualified test with a project:
[chromium] › path/to/example.spec.ts:3:9 › suite › nested suite › example test

# This test is included for all projects:
path/to/example.spec.ts:3:9 › example test

# Use "›" or ">" as a separator:
[firefox] > example.spec.ts > suite > nested suite > example test

# Line/column numbers are completely ignored, you can omit them.
# Three entries below refer to the same test:
example.spec.ts › example test
example.spec.ts:15 › example test
example.spec.ts:42:42 › example test

Show Report

Display HTML report from previous test run. Read more about the HTML reporter.

Syntax

npx playwright show-report [report] [options]

Examples

# Show latest test report
npx playwright show-report

# Show a specific report
npx playwright show-report playwright-report/

# Show report on custom port
npx playwright show-report --port 8080

Options

Option Description
--host <host> Host to serve report on (default: localhost)
--port <port> Port to serve report on (default: 9323)

Install Browsers

Install browsers required by Playwright. Read more about Playwright's browser support.

Syntax

npx playwright install [options] [browser...]
npx playwright install-deps [options] [browser...]
npx playwright uninstall

Examples

# Install all browsers
npx playwright install

# Install only Chromium
npx playwright install chromium

# Install specific browsers
npx playwright install chromium webkit

# Install browsers with dependencies
npx playwright install --with-deps

Install Options

Option Description
--force Force reinstall of already installed browsers
--with-deps Install browser system dependencies
--dry-run Don't perform installation, just print information
--list Print list of browsers from all Playwright installations
--only-shell Only install chromium-headless-shell instead of full Chromium
--no-shell Don't install chromium-headless-shell
--no-progress Don't show download progress bars
--no-remove Don't remove unused browsers

Install Deps Options

Option Description
--dry-run Don't modify the system. On Linux, simulates the install via apt-get and exits with a non-zero code if any required packages are missing — useful for non-interactive verification scripts. On Windows, prints the install command.

Generation & Debugging Tools

Code Generation

Record actions and generate tests for multiple languages. Read more about Codegen.

Syntax

npx playwright codegen [options] [url]

Examples

# Start recording with interactive UI
npx playwright codegen

# Record on specific site
npx playwright codegen https://playwright.dev

# Generate Python code
npx playwright codegen --target=python

Options

Option Description
-b, --browser <name> Browser to use: chromium, firefox, or webkit (default: chromium)
-o, --output <file> Output file for the generated script
--target <language> Language to use: javascript, playwright-test, python, etc.
--test-id-attribute <attr> Attribute to use for test IDs

Trace Viewer

Analyze and view test traces for debugging. Read more about Trace Viewer.

Syntax

npx playwright show-trace [options] [trace]

Examples

# Open trace viewer without a specific trace (can load traces via UI)
npx playwright show-trace

# View a trace file
npx playwright show-trace trace.zip

# View trace from directory
npx playwright show-trace trace/

Options

Option Description
-b, --browser <name> Browser to use: chromium, firefox, or webkit (default: chromium)
-h, --host <host> Host to serve trace on
-p, --port <port> Port to serve trace on

Specialized Commands

Merge Reports

Read blob reports and combine them. Read more about merge-reports.

Syntax

npx playwright merge-reports [options] <blob dir>

Examples

# Combine test reports
npx playwright merge-reports ./reports

Options

Option Description
-c, --config <file> Configuration file. Can be used to specify additional configuration for the output report
--reporter <reporter> Reporter to use, comma-separated, can be "list", "line", "dot", "failures", "json", "junit", "null", "github", "html", "blob", "perfetto" (default: "list" locally and "dot" on CI)
--reporter-only-failures Include only failed, flaky, and interrupted tests in JSON, JUnit, and HTML reports.

Clear Cache

Clear all Playwright caches.

Syntax

npx playwright clear-cache