Playwright CLI

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

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

Configuration

Playwright searches for a config file in this order:

1. --config=<path> flag
2. playwright.config.ts in project root
3. playwright.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 navigations
• testDir — 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.