Running Playwright Tests from the CLI: Flags, Filters, and Debugging

Running npx playwright test runs everything, but npx playwright test tests/login.spec.ts --grep "payment fails" --debug runs one test in the inspector, paused before the first action. The difference between knowing the CLI and not knowing it is the difference between re-running the full suite to chase a failure and pinpointing it in 30 seconds. This article covers the flags you'll use daily: filtering by file, name, and tag; headed and debug modes; worker count; reporters; and the combinations that solve the most common run-configuration problems.

The Basic Command

npx playwright test

Runs all tests in your testDir (usually ./tests) across all projects defined in playwright.config.ts.

Filtering Which Tests Run

By file or folder

# Run all tests in a specific file
npx playwright test tests/login.spec.ts

# Run all tests in a folder
npx playwright test tests/api/

# Run multiple files
npx playwright test tests/login.spec.ts tests/dashboard.spec.ts

By test name (`--grep`)

# Run tests whose name contains "login"
npx playwright test --grep "login"

# Run tests matching a regex
npx playwright test --grep "login|registration"

# Invert: run tests that DON'T match
npx playwright test --grep-invert "flaky"

The string is matched against the full test title, which includes the describe block name. "Login page > shows error" would be matched by --grep "error" or --grep "Login page".

By tag

If your tests use tags:

test('smoke test @smoke', async ({ page }) => { ... });

npx playwright test --grep "@smoke"

By project (browser)

# Only run in Chrome
npx playwright test --project=chromium

# Only run in Firefox and WebKit
npx playwright test --project=firefox --project=webkit

UI and Browser Mode

Headed (visible browser)

npx playwright test --headed

Opens a real browser window. Useful for watching what's happening during a test.

Slow motion

npx playwright test --headed --slow-mo=500

Adds 500ms delay between actions. Good for recording demos or debugging timing issues.

UI Mode (interactive)

npx playwright test --ui

Opens Playwright's interactive UI — a time-travel debugger that lets you:

Browse all tests in a sidebar
Run individual tests
Watch a timeline of every action
See DOM snapshots at each step
Inspect network calls

This is the best debugging tool Playwright has. Use it whenever you're tracking down a confusing failure.

Debug Mode

npx playwright test --debug

Pauses before the first action and opens the Playwright Inspector. Step through actions one at a time. You can also type Playwright commands in the inspector console to try things interactively.

For a specific test:

npx playwright test tests/login.spec.ts --debug

Codegen (record a new test)

npx playwright codegen https://lab.becomeqa.com

Opens a browser where your actions are recorded. The generated Playwright code appears in the inspector window. Copy it into your test file.

Parallel Execution

Set number of workers

# 4 parallel workers
npx playwright test --workers=4

# Sequential (1 worker)
npx playwright test --workers=1

Sharding (for CI with multiple machines)

# Split tests into 4 shards — run shard 1 on machine 1
npx playwright test --shard=1/4

# Run shard 2 on machine 2
npx playwright test --shard=2/4

Each shard runs a subset of tests. Total time divided by number of shards (approximately).

Retries

# Retry failed tests up to 3 times
npx playwright test --retries=3

Usually you set retries in playwright.config.ts, but the CLI flag overrides it.

Reporting

Choose reporter

# List (live console output)
npx playwright test --reporter=list

# HTML report
npx playwright test --reporter=html

# Dot (minimal output)
npx playwright test --reporter=dot

# Multiple reporters
npx playwright test --reporter=html,list

Open last HTML report

npx playwright show-report

Opens playwright-report/index.html in your browser. This is the visual report with all test results, screenshots, traces, and videos.

Merge sharded reports

After running sharded tests, merge the reports:

npx playwright merge-reports --reporter html ./blob-reports

Trace Viewer

View a recorded trace (the .zip file from a failed test):

npx playwright show-trace trace.zip

Or from the HTML report — click "Trace" on any failed test.

Useful Combinations

# Debug a specific failing test
npx playwright test tests/checkout.spec.ts --grep "payment fails" --debug

# Run only smoke tests in Chrome, headed
npx playwright test --grep "@smoke" --project=chromium --headed

# Run all tests but retry failures once, with verbose output
npx playwright test --retries=1 --reporter=list

# Quick sanity check: first worker only, first 5 tests
npx playwright test --workers=1 --max-failures=5

# Run without the config file (useful for one-off scripts)
npx playwright test --config=minimal.config.ts

# List all tests without running them
npx playwright test --list

Environment Variables with the CLI

You can pass environment variables directly:

BASE_URL=https://staging.myapp.com npx playwright test

Or set multiple:

BASE_URL=https://staging.myapp.com ENV=staging npx playwright test

These are available in your config and tests via process.env.BASE_URL.

Common Flags Reference

| Flag | What it does |

|------|-------------|

| --headed | Show browser window |

| --debug | Pause and open inspector |

| --ui | Open interactive UI mode |

| --slow-mo=N | Add Nms delay between actions |

| --grep "pattern" | Filter tests by name |

| --grep-invert "pattern" | Exclude tests by name |

| --project=name | Run specific project(browser) |

| --workers=N | Number of parallel workers |

| --retries=N | Retry failed tests N times |

| --shard=X/Y | Run shard X of Y |

| --reporter=type | Choose output format |

| --timeout=N | Override test timeout (ms) |

| --max-failures=N | Stop after N failures |

| --list | List all tests without running |

| --config=file | Use a different config file |

| --pass-with-no-tests | Don't fail if no tests found |

`package.json` Scripts

Add common commands as npm scripts so teammates don't have to remember flags:

{
  "scripts": {
    "test": "npx playwright test",
    "test:headed": "npx playwright test --headed",
    "test:debug": "npx playwright test --debug",
    "test:ui": "npx playwright test --ui",
    "test:smoke": "npx playwright test --grep @smoke",
    "test:chrome": "npx playwright test --project=chromium",
    "test:report": "npx playwright show-report",
    "test:ci": "npx playwright test --reporter=list,junit"
  }
}

Then anyone can run npm run test:smoke without needing to know the grep flag.

The CLI is worth getting comfortable with. Between --grep, --debug, and --ui, you can dramatically speed up your debugging workflow — targeting exactly the failing test, in exactly the mode you need to investigate it.