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
| Command | What it does |
|---|---|
npm init playwright@latest | Create a project: config, example test, optional GitHub Actions workflow |
npx playwright install | Download all browsers for this Playwright version |
npx playwright install chromium | Download one browser |
npx playwright install --with-deps | Browsers plus Linux system libraries (CI) |
npx playwright install-deps | System libraries only |
npx playwright uninstall | Remove browsers for this version |
npx playwright --version | Show the installed version |
Running tests: npx playwright test
# 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
| Flag | Example |
|---|---|
-g, --grep | -g "wrong password" runs tests whose title matches |
--grep @smoke | Runs tests tagged @smoke |
--grep-invert | --grep-invert @slow skips tagged tests |
--last-failed | Only tests that failed last run |
--only-changed | Only test files changed since the last commit (or --only-changed=main) |
--list | List 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
# 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.
Flags for CI
| Flag | Why you want it in CI |
|---|---|
--retries=2 | Retry failures and mark them flaky instead of failing at once |
--fail-on-flaky-tests | Fail the run if any test only passed on retry |
--forbid-only | Fail if someone committed test.only |
--max-failures=10 | Stop early when the build is clearly broken |
--shard=1/4 | Split the suite across 4 machines |
--reporter=blob | Write mergeable results from each shard |
--timeout=60000 | Override the per-test timeout |
--update-snapshots | Regenerate screenshot baselines (run deliberately, not on every build) |
# 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
# 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
| Command | What it does |
|---|---|
npx playwright show-report | Serve the last HTML report |
npx playwright show-report my-report | Serve a report from another folder |
npx playwright show-trace trace.zip | Open a trace in the Trace Viewer |
npx playwright test --reporter=list,html | Combine reporters for one run |
npx playwright screenshot URL out.png | Quick screenshot without writing a test |
npx playwright pdf URL out.pdf | Save a page as PDF (Chromium) |
Playwright Test Agents: init-agents
# 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
"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
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.
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