How to Run Playwright from the Command Line

Playwright’s command-line entry point is npx playwright. Run every configured test with:

npx playwright test

Tests run headless by default and use the projects in your Playwright configuration. Add a file, directory, line number, or title filter to run a smaller scope.

Install Playwright and its browsers

1. Add the test package

npm install -D @playwright/test@latest

2. Download browser binaries

npx playwright install

On a Linux machine or CI runner that also needs operating-system packages:

npx playwright install --with-deps

Install only one browser when you do not need the others:

npx playwright install chromium

Check the installed CLI version:

npx playwright --version

After upgrading Playwright, run the browser install command again so the binaries match the package version. To simulate dependency installation without changing the machine, use:

npx playwright install --dry-run

Run all tests

npx playwright test

The command reads playwright.config.*, discovers the configured test files, and runs the configured projects. Headless mode is the default, which is suitable for CI and fast local checks.

Run one file, directory, line, or test title

Goal	Command
One file	npx playwright test tests/todo-page.spec.ts
All tests in a directory	npx playwright test tests/landing-page/
A test at a line	npx playwright test my-spec.ts:42
A title or title pattern	npx playwright test -g "add a todo item"

Non-option arguments are regular expressions matched against complete test-file paths. Quote arguments containing shell metacharacters, spaces, parentheses, brackets, or other regular-expression characters when your shell could interpret them.

npx playwright test 'tests/cart/[checkout].spec.ts'
npx playwright test -g 'checkout.*guest'

Choose a browser project

Use --project to run only a configured project:

npx playwright test --project=chromium
npx playwright test --project=firefox
npx playwright test --project=webkit

The project name must match a project in your configuration. If you define device projects or custom names, use those exact names.

See the browser while tests run

Headed mode

npx playwright test --headed

--headed opens visible browser windows while retaining the normal test runner.

UI Mode

npx playwright test --ui

UI Mode provides an interactive view for selecting tests, watching steps, and inspecting results.

Debug a specific test

npx playwright test tests/example.spec.ts:10 --debug

--debug launches the Playwright Inspector with headed mode, one worker, an unlimited timeout, and execution stopping after the first failure. It is a convenient shortcut for interactive diagnosis.

Control workers, retries, timeouts, and failures

Option	Example	Use it for
--workers	--workers=1	Serial execution and easier debugging
--retries	--retries=2	Retrying failures, especially in CI
--timeout	--timeout=30000	Setting a per-test timeout in milliseconds
--max-failures	--max-failures=1	Stopping after a chosen number of failures
--repeat-each	--repeat-each=3	Repeating every test to expose intermittent failures
--shard	--shard=1/4	Splitting a suite across CI jobs
--only-changed	--only-changed	Focusing on tests affected by recent changes

For a deterministic local reproduction, combine a narrow filter with one worker:

npx playwright test tests/cart.spec.ts --project=chromium --workers=1 --retries=0

Parallel workers improve throughput, but tests that share accounts, files, ports, or mutable server state may need isolation or serial execution.

Choose a reporter

npx playwright test --reporter=list
npx playwright test --reporter=dot
npx playwright test --reporter=line
npx playwright test --reporter=json
npx playwright test --reporter=junit
npx playwright test --reporter=html
npx playwright test --reporter=blob

Use a concise reporter for local runs, machine-readable JSON or JUnit for CI systems, HTML for interactive review, and blob reports when you will merge results from multiple shards.

Open the HTML report

npx playwright show-report
npx playwright show-report playwright-report/ --port 8080

The report lets you filter passed, failed, skipped, and flaky tests and inspect each test’s steps and attachments. If the report is in a non-default directory, pass that directory explicitly.

Inspect traces

Enable tracing through your configuration or a trace-related test option, then open the resulting archive:

npx playwright show-trace trace.zip

You can also provide host and port options when exposing the trace viewer in a development environment. Blob reports from sharded runs can be combined with the CLI’s report-merging command before you inspect the final report.

Generate starter tests with Codegen

Codegen records browser actions and opens the Playwright Inspector:

npx playwright codegen https://playwright.dev

Select a target language:

npx playwright codegen --target=python https://playwright.dev

Write generated output to a file:

npx playwright codegen --output=tests/generated.spec.ts https://example.com

Codegen also supports browser selection, test-id attributes, viewport, timezone, geolocation, language, and persistent user-data options. Treat generated code as a starting point: review locators, remove accidental steps, and add assertions that express the behavior you actually need.

Find the right command quickly

npx playwright --help
npx playwright test --help

The help output is tied to the installed version, so it is the best way to confirm available flags on a particular project or CI image.

Practical command recipes

Fast Chromium smoke test

npx playwright test tests/smoke.spec.ts --project=chromium --workers=1

Visible run with an HTML report

npx playwright test --headed --reporter=html
npx playwright show-report

Debug the first failure

npx playwright test tests/checkout.spec.ts:42 --debug

CI run split into four shards

npx playwright test --shard=1/4 --reporter=blob

Repeat a flaky scenario

npx playwright test tests/payment.spec.ts --repeat-each=10 --workers=1

Common errors and fixes

Symptom	Likely cause	Fix
playwright: command not found	The package is not installed locally or the command was run without the package manager.	Install @playwright/test and invoke it with npx playwright.
Executable browser is missing	Playwright’s package is present but browser binaries were not downloaded, or the package was upgraded.	Run npx playwright install; use --with-deps on supported Linux environments.
Browser fails to start in CI	Required operating-system libraries are absent.	Run npx playwright install --with-deps in the image setup.
No tests found	The path, regular expression, test directory, or configured test pattern does not match.	Check the path, quote shell characters, and run npx playwright test --help to review filters.
A line filter runs nothing	The file or line number is wrong, or the test was moved.	Use the current file path and line, then narrow further with -g.
Interactive debugging times out	The normal timeout is too short for inspection.	Use --debug, which configures an unlimited timeout and headed Inspector session.
Tests interfere with one another	Parallel workers share mutable state.	Isolate data per worker or run with --workers=1.
Report does not open	The report directory is not the default path or no HTML report was generated.	Pass the actual directory to show-report and select --reporter=html for the run.
Trace archive cannot be viewed	The path is wrong or the trace was not retained by the configured trace policy.	Locate the generated archive and run npx playwright show-trace path/to/trace.zip.

Performance and reliability guidance

• Run only the project and test scope you need during local development.
• Use parallel workers for independent tests; reduce workers when shared state causes races.
• Use retries to collect evidence about intermittent failures, but investigate repeated retries instead of treating them as a permanent fix.
• Shard large suites across CI jobs and merge blob reports for one combined result.
• Keep browser binaries aligned with the installed Playwright version.
• Use line or title filters while iterating, then run the complete configured suite before merging.
• Use HTML reports for human review and JSON or JUnit for CI integrations.
• Enable traces for failure diagnosis according to your retention policy; traces add storage and collection work.

Or skip the browser setup

If your goal is a reliable screenshot rather than browser test development, ScreenshotNeo provides a single GET request. Its API accepts the URL and returns PNG, JPEG, WebP, or PDF output. See the ScreenshotNeo API documentation for the complete option list.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo removes cookie and consent banners, newsletter popups, and chat widgets before capture. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers identify the page verdict and billing result. Its MCP server gives AI agents tools for screenshots, page information, and PDFs. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.

FAQ

What is the basic Playwright CLI command?

npx playwright test runs the configured test suite.

Are Playwright tests headed by default?

No. They run headless by default. Add --headed, --ui, or --debug when you need a visible or interactive session.

How do I run one test?

Use a file path, line filter, or title expression, such as npx playwright test tests/example.spec.ts:10 or npx playwright test -g "checkout".

How do I open a Playwright report?

Run npx playwright show-report, optionally passing the report directory and port.

What command records browser actions?

npx playwright codegen URL opens Codegen and the Inspector, where you can record a starter test.