Playwright CLI Skill
Run any npx playwright command via the Bash tool. This skill covers test execution,
code generation, browser installation, reporting, tracing, screenshots, PDFs, and debugging.
Constraints
- Always use
npx playwright — never assume a global install.
- Playwright must already be installed in the project (
npm i -D @playwright/test or equivalent).
If it is not, guide the user to install it first.
- On Windows, some commands behave differently (e.g.,
show-report may not auto-open a browser
in WSL). Note platform quirks when relevant.
- Commands that launch a GUI (codegen, UI mode, show-report, show-trace, open) require a display.
In headless CI environments, skip or adapt these.
Preflight Check
Before running any Playwright command, verify the installation:
npx playwright --version
If this fails:
- "npx: command not found" — Node.js / npm is not installed.
- "Cannot find module '@playwright/test'" — Playwright is not installed in this project.
Suggest:
npm install -D @playwright/test
- "Executable doesn't exist" on test run — Browsers not installed.
Suggest:
npx playwright install or npx playwright install chromium
Note on Related Skills
This skill (playwright-cli) handles CLI commands — running tests, codegen, install,
screenshots, traces, etc. via npx playwright ... in Bash. It also covers the guided
codegen-to-test-suite workflow: recording, reviewing, adding assertions, and organizing
page objects. See references/codegen-workflow.md when the user wants to turn a recording
into a structured, assertion-bearing test suite — not just run codegen standalone (the
"Code generation" pattern above).
The separate e2e-test skill uses Playwright MCP browser tools for interactive,
step-by-step browser automation with screenshot evidence. Use that skill when the user
wants to manually drive a browser session, not run CLI test suites.
Quick Reference
| Action | Command |
|---|
| Run all tests | npx playwright test |
| Run specific file | npx playwright test tests/login.spec.ts |
| Run by grep | npx playwright test --grep "login" |
| Run headed | npx playwright test --headed |
| Run single browser | npx playwright test --project=chromium |
| Debug tests | npx playwright test --debug |
| UI mode | npx playwright test --ui |
| List tests (dry run) | npx playwright test --list |
| Code generation | npx playwright codegen https://example.com |
| Install browsers | npx playwright install |
| Install one browser | npx playwright install chromium |
| Install system deps | npx playwright install-deps |
| Show HTML report | npx playwright show-report |
| Show trace viewer | npx playwright show-trace trace.zip |
| Take screenshot | npx playwright screenshot https://example.com shot.png |
| Generate PDF | npx playwright pdf https://example.com page.pdf |
| Open URL in Chromium | npx playwright open https://example.com |
| Open URL in Firefox | npx playwright ff https://example.com |
| Open URL in WebKit | npx playwright wk https://example.com |
| Clear browser cache | npx playwright clear-cache |
| Merge shard reports | npx playwright merge-reports ./blob-reports |
| Update snapshots | npx playwright test --update-snapshots |
Common Patterns
Run tests matching a pattern
npx playwright test --grep "checkout" --project=chromium
Exclude pattern:
npx playwright test --grep-invert "slow"
Headed mode with slowdown for observation
npx playwright test --headed --timeout=60000
Retries and workers
npx playwright test --retries=2 --workers=4
For CI with limited resources:
npx playwright test --retries=2 --workers=1
Sharding across CI jobs
Job 1 of 4:
npx playwright test --shard=1/4
Merge after all shards complete:
npx playwright merge-reports ./blob-reports --reporter=html
Code generation with device emulation
npx playwright codegen --device="iPhone 13" https://example.com
With viewport:
npx playwright codegen --viewport-size="1280,720" https://example.com
Record into a file:
npx playwright codegen --target=javascript -o tests/generated.spec.js https://example.com
Save and reuse authentication state
Save storage state after login:
npx playwright codegen --save-storage=auth.json https://example.com
Reuse it:
npx playwright codegen --load-storage=auth.json https://example.com
Or in open:
npx playwright open --load-storage=auth.json https://example.com
Trace viewing
If tests were run with tracing enabled (use: { trace: 'on' } in config):
npx playwright show-trace test-results/example-test/trace.zip
Debug a specific test
npx playwright test tests/login.spec.ts:42 --debug
The :42 targets the test starting at line 42.
Update visual snapshots
npx playwright test --update-snapshots
Custom config file
npx playwright test --config=playwright.ci.config.ts
Reporter selection
npx playwright test --reporter=dot
npx playwright test --reporter=json > results.json
npx playwright test --reporter=junit > results.xml
npx playwright test --reporter=html
Multiple reporters:
npx playwright test --reporter='list,html'
Run only failed tests from last run
npx playwright test --last-failed
Screenshot and PDF
npx playwright screenshot --full-page https://example.com full.png
npx playwright pdf https://example.com output.pdf
Error Handling
| Symptom | Cause | Fix |
|---|
Cannot find module '@playwright/test' | Not installed | npm install -D @playwright/test |
Executable doesn't exist at ... | Browsers not installed | npx playwright install |
browserType.launch: ... | Missing system deps | npx playwright install-deps (Linux) |
| Tests pass locally, fail in CI | Missing browsers or deps in CI | Add npx playwright install --with-deps to CI setup |
Error: Timed out ... | Slow environment | Increase --timeout or use --retries |
ENOMEM / OOM | Too many workers | Reduce --workers=1 |
| Trace file not found | Tracing not enabled | Set use: { trace: 'on' } in config |
| Report empty after shards | Blob reports not merged | Run npx playwright merge-reports ./blob-reports |
Configuration
Playwright searches for a config file in this order:
--config=<path> flagplaywright.config.ts in project rootplaywright.config.js in project root
Key config settings that affect CLI behavior:
projects — defines browser targets (mapped to --project flag)retries — default retry count (overridden by --retries)workers — parallelism (overridden by --workers)reporter — default reporter (overridden by --reporter)use.trace — when to record traces ('on', 'off', 'on-first-retry', 'retain-on-failure')use.baseURL — base URL for relative navigationstestDir — directory containing test files
References
For the full flag-by-flag reference of every subcommand, read references/cli-reference.md.
For the guided workflow that turns a codegen recording into a production-quality test suite
(planning, review, assertions, selectors, page objects, config scaffolding), read
references/codegen-workflow.md. It in turn points to references/test-patterns.md,
references/selector-strategy.md, references/page-object-pattern.md, and
references/config-template.md.