Browse all tutorials →
Reference November 20, 2026 9 min read

Playwright CLI Commands: The Complete Cheat Sheet

Everything Playwright does from the terminal goes through npx playwright: running tests, recording them, installing browsers, opening reports and traces, and setting up Test Agents. Here is every command and flag you will actually use, with examples.

⌨️

Quick answer: npx playwright test runs tests; everything else is a subcommand

npx playwright test runs your suite, with flags for files, browsers, retries and workers. codegen records tests, install downloads browsers, show-report and show-trace open results, and init-agents sets up Test Agents.

Which "Playwright CLI"?

Two different tools now share the name:

  • npx playwright, the CLI inside @playwright/test. This is what this cheat sheet covers: running tests, codegen, installs, reports and traces.
  • @playwright/cli, a separate command-line tool that lets AI coding agents such as Claude Code drive a browser with fewer tokens than the MCP Server. It has its own guide: Playwright CLI for Claude Code.

Setup and browser install

CommandWhat it does
npm init playwright@latestCreate a project: config, example test, optional GitHub Actions workflow
npx playwright installDownload all browsers for this Playwright version
npx playwright install chromiumDownload one browser
npx playwright install --with-depsBrowsers plus Linux system libraries (CI)
npx playwright install-depsSystem libraries only
npx playwright uninstallRemove browsers for this version
npx playwright --versionShow the installed version

Running tests: npx playwright test

Terminal
# Everything, using playwright.config
npx playwright test

# One file, or one test by line number
npx playwright test tests/login.spec.ts
npx playwright test tests/login.spec.ts:12

# Files whose path contains "checkout"
npx playwright test checkout

# One project (browser) from the config
npx playwright test --project=chromium

# Watch the browser
npx playwright test --headed

# Control parallelism
npx playwright test --workers=4
npx playwright test --fully-parallel

Filtering tests

FlagExample
-g, --grep-g "wrong password" runs tests whose title matches
--grep @smokeRuns tests tagged @smoke
--grep-invert--grep-invert @slow skips tagged tests
--last-failedOnly tests that failed last run
--only-changedOnly test files changed since the last commit (or --only-changed=main)
--listList the tests without running them

Tags are added in the test details: test('checkout', { tag: '@smoke' }, async ...). See Playwright tags for patterns.

Debugging from the command line

Terminal
# Playwright Inspector: step through one test
npx playwright test tests/login.spec.ts:12 --debug

# UI mode: watch mode, time-travel, locator picker
npx playwright test --ui

# Record a trace for every test this run
npx playwright test --trace on

# Stop at the first failure
npx playwright test -x

# Hunt flakiness: run each test 10 times
npx playwright test tests/cart.spec.ts --repeat-each=10

UI mode is usually the fastest way to understand a failure locally; the UI mode tutorial shows how to use it, and how to debug Playwright tests covers the full toolkit.

Go from commands to AI workflows.

Playwright from your first test, then Claude Code, the MCP Server and Playwright Test Agents.

See the course plan →

Flags for CI

FlagWhy you want it in CI
--retries=2Retry failures and mark them flaky instead of failing at once
--fail-on-flaky-testsFail the run if any test only passed on retry
--forbid-onlyFail if someone committed test.only
--max-failures=10Stop early when the build is clearly broken
--shard=1/4Split the suite across 4 machines
--reporter=blobWrite mergeable results from each shard
--timeout=60000Override the per-test timeout
--update-snapshotsRegenerate screenshot baselines (run deliberately, not on every build)
Merge sharded results
# After each shard uploads its blob-report folder
npx playwright merge-reports --reporter=html ./all-blob-reports

The sharding guide and GitHub Actions guide show complete pipelines.

Codegen: record tests

Terminal
# Open a browser and record your actions as test code
npx playwright codegen https://playwright.dev

# Emulate a device, and save to a file
npx playwright codegen --device="iPhone 13" -o tests/mobile.spec.ts https://example.com

# Log in once, save the session, reuse it
npx playwright codegen --save-storage=auth.json https://example.com/login
npx playwright codegen --load-storage=auth.json https://example.com/dashboard

# Generate code for another language
npx playwright codegen --target=python-pytest https://example.com

Codegen is best for finding locators. Its tests rarely include the assertions you need, so add them by hand. More in the codegen tutorial.

Reports and traces

CommandWhat it does
npx playwright show-reportServe the last HTML report
npx playwright show-report my-reportServe a report from another folder
npx playwright show-trace trace.zipOpen a trace in the Trace Viewer
npx playwright test --reporter=list,htmlCombine reporters for one run
npx playwright screenshot URL out.pngQuick screenshot without writing a test
npx playwright pdf URL out.pdfSave a page as PDF (Chromium)

Playwright Test Agents: init-agents

Terminal
# Add planner, generator and healer agents for Claude Code
npx playwright init-agents --loop=claude

# Or for VS Code / GitHub Copilot
npx playwright init-agents --loop=vscode

The command writes agent definitions into your project. Your AI tool then uses them: the planner explores the app and writes a test plan, the generator turns it into tests, and the healer proposes fixes for failures. Re-run it after upgrading Playwright so the definitions match the new version. The Test Agents guide covers the workflow.

Turn the commands into npm scripts

package.json
"scripts": {
  "test": "playwright test",
  "test:ui": "playwright test --ui",
  "test:smoke": "playwright test --grep @smoke",
  "test:failed": "playwright test --last-failed",
  "test:ci": "playwright test --forbid-only --retries=2 --fail-on-flaky-tests",
  "report": "playwright show-report"
}

Inside npm scripts you drop the npx. Pass extra flags after --: npm test -- --headed.

Playwright + Claude AI & MCP Server: AI QA Automation 2026 covers installing, running and reporting on tests in JavaScript, then moves on to Claude Code, the Playwright MCP Server, multi-agent workflows and Playwright Test Agents. See the course plan.


Frequently Asked Questions

What is the Playwright CLI?

It is the playwright command that ships with @playwright/test, usually run as npx playwright. It runs tests and provides tools such as codegen, browser install, report and trace viewers. Separately, @playwright/cli is a newer command-line tool built for AI coding agents.

How do I run a single Playwright test from the command line?

Pass the file and line: npx playwright test tests/login.spec.ts:12. Or match the title with -g "wrong password".

How do I run Playwright tests in headed mode?

Use npx playwright test --headed. For step-by-step debugging use --debug, and for an interactive watch-mode runner use --ui.

How do I re-run only failed Playwright tests?

Run npx playwright test --last-failed. Playwright remembers the failures from the previous run.

How do I install only one browser?

Run npx playwright install chromium. Add --with-deps on Linux CI to install system dependencies too.

How do I set up Playwright Test Agents from the CLI?

Run npx playwright init-agents --loop=claude (or --loop=vscode). It adds planner, generator and healer agent definitions to your project for your AI tool to use.

Asim Noaman, Playwright and Claude AI course instructor

Asim Noaman

Sr. SQA Manager & AI Automation Engineer

18+ years in QA. Asim currently runs an 80+ engineer QA function at Tkxel and built a Testing Center of Excellence for a major Saudi bank. He builds AI testing agents with Playwright, Claude AI and the MCP Server at work, and teaches the same workflow in his courses.

18+ Years in QA 80+ engineer QA function
Udemy Instructor 4.5★ · 140+ ratings · 570+ students
Anthropic Certificates Claude API · MCP
Connect on LinkedIn

Full profile →

Playwright + Claude AI Course on Udemy

From npx playwright test to AI Test Agents.

Learn Playwright in JavaScript from zero: install, run and report on tests, then use Claude Code, the Playwright MCP Server, multi-agent workflows and Playwright Test Agents. 107 lectures, 11.5 hours, rated 4.5★ from 140+ ratings, 570+ students.

  • Playwright from scratch in JavaScript, no prior coding needed
  • Page Object Model, hooks and timeouts
  • Claude Code, custom QA subagents and the Playwright MCP Server
  • Multi-agent workflows and Playwright Test Agents
Enroll on Udemy →