Playwright CLI Commands: Run, Filter, Debug and Report Tests

Knowing the Playwright command line saves you hours. In this lesson you will learn how to run exactly the tests you want, watch and debug them, control parallelism and retries, generate reports, and turn long commands into simple npm scripts.

---

⌨️ The Basic Command

Every test run starts with:

npx playwright test

npx runs the Playwright version installed in your project. By default this runs all tests, in all projects from your config, headless and in parallel. Everything else in this lesson is an option you add to that command.

---

📂 Run Specific Files, Folders or Lines

npx playwright test tests/login.spec.ts          # one file
npx playwright test login                         # any file whose path contains "login"
npx playwright test tests/checkout/               # a whole folder
npx playwright test login.spec.ts cart.spec.ts    # several files
npx playwright test tests/login.spec.ts:12        # the test that starts on line 12

---

🔍 Filter Tests by Name or Tag

npx playwright test -g "locked out user"          # title contains this text (--grep)
npx playwright test --grep "@smoke"               # tests tagged @smoke
npx playwright test --grep-invert "@slow"         # everything except @slow
npx playwright test --grep "@smoke|@regression"   # either tag (regex)

Tags are added in the test title or with the tag option:

test('user can log in', { tag: '@smoke' }, async ({ page }) => {
  // ...
});

Tagging is covered in depth in the lesson on grouping and tagging tests.

---

🌐 Choose Browsers (Projects)

npx playwright test --project=chromium
npx playwright test --project=chromium --project=firefox
npx playwright test --project="Mobile Chrome"

Project names come from the projects array in playwright.config.ts.

---

👀 See What Is Happening: Headed, UI Mode and Debug

Command	What you get
npx playwright test --headed	Real browser windows open while tests run
npx playwright test --ui	UI mode: pick tests, watch them, time-travel through each step, re-run on save
npx playwright test --debug	Playwright Inspector: step through the test one action at a time
npx playwright test login.spec.ts:12 --debug	Debug one specific test

---

⚡ Control Speed, Retries and Failures

npx playwright test --workers=1          # run one test at a time (no parallelism)
npx playwright test --workers=4          # four parallel workers
npx playwright test --retries=2          # retry failed tests twice
npx playwright test -x                   # stop after the first failure
npx playwright test --max-failures=5     # stop after five failures
npx playwright test --timeout=60000      # 60 s per test
npx playwright test --repeat-each=5      # run each test 5 times (find flaky tests)
npx playwright test --last-failed        # re-run only the tests that failed last time

---

📊 Reports, Traces and Listing Tests

npx playwright test --reporter=list          # one line per test in the terminal
npx playwright test --reporter=dot           # compact output for CI
npx playwright test --reporter=html          # HTML report
npx playwright show-report                   # open the last HTML report
npx playwright test --trace on               # record a trace for every test
npx playwright show-trace test-results/<folder>/trace.zip   # open a trace file
npx playwright test --list                   # list tests without running them

---

🛠️ Other Useful Playwright Commands

Command	Purpose
npx playwright codegen https://www.saucedemo.com	Record actions and generate test code
npx playwright install	Download or update the browsers
npx playwright install --with-deps chromium	Install Chromium plus Linux system libraries
npx playwright --version	Show the installed Playwright version
npx playwright test --update-snapshots	Update screenshot baselines for visual tests
npx playwright test --shard=1/3	Run the first third of the suite (split across CI machines)
npx playwright test --config=api.config.ts	Use a different config file
npx playwright test --help	List every option

---

📦 Save Commands as npm Scripts

Typing long commands is error-prone. Add shortcuts to package.json:

{
  "scripts": {
    "test": "playwright test",
    "test:headed": "playwright test --headed --project=chromium",
    "test:ui": "playwright test --ui",
    "test:smoke": "playwright test --grep @smoke",
    "test:debug": "playwright test --debug",
    "report": "playwright show-report"
  }
}

Now run npm test, npm run test:smoke or npm run report. Inside npm scripts you do not need npx.

---

🧑‍💻 Running Tests from VS Code

The Playwright Test for VSCode extension gives you the same power with clicks:

• ▶ next to a test or file runs it; right-click for Debug Test.
• Show browser runs headed; Show trace viewer opens traces automatically.
• Select which projects (browsers) to run in the Playwright panel of the Testing view.
• Pick locator and Record new use the Inspector and Codegen.

Installation is covered in Install Playwright and set up VS Code.

---

📝 Assignment

Use the login tests you wrote in your first Playwright test:

1. Run only the “locked out user” test using -g.
2. Run all login tests only in Firefox, headed.
3. Open UI mode, run the suite, and use the timeline to inspect the step where the login button is clicked.
4. Add the tag @smoke to two tests and run only those tests.
5. Run your suite with --repeat-each=3 --workers=1 and confirm every run passes.
6. Add test:smoke and report scripts to package.json and use them.

---

❓ FAQ

🤔 How do I run a specific test in Playwright?

Use the file and line: npx playwright test tests/login.spec.ts:12, or filter by title: npx playwright test -g "test title". In VS Code, click ▶ next to the test.

🤔 How do I run Playwright tests in headed mode?

Add --headed: npx playwright test --headed. Set headless: false in the config to make it the default.

🤔 How do I run Playwright tests in one browser only?

Use --project=chromium (or another project name from your config).

🤔 How do I run tests one by one instead of in parallel?

Use --workers=1. Tests then run sequentially in a single worker process.

🤔 How do I see all Playwright CLI options?

Run npx playwright test --help for test options and npx playwright --help for all commands.