All topics·Beginner·4 / 16

Running and debugging tests

CLI flags, UI mode, debugging with --debug, headed runs, filtering by name/file/tag.

The test CLI

npx playwright test runs every project from playwright.config.ts in parallel headless mode. The CLI is the single entry point: you filter, pick projects, choose reporters and debug from it.

bash

# run every test
npx playwright test

# only a file or pattern
npx playwright test tests/auth.spec.ts
npx playwright test --grep "@smoke"

# only one project from the config
npx playwright test --project=chromium

# headed + slow motion to watch the browser
npx playwright test --headed --workers=1

UI mode

UI mode (--ui) opens a dedicated app: filter tests, watch them re-run on file change, inspect locator picks, time-travel through the trace, view network and console. This is the most productive way to author and debug tests.

bash

npx playwright test --ui

Debug a single test

Use --debug to launch the Playwright Inspector and step through the spec. Combine with a grep to focus on one test. In code, page.pause() pauses execution at that point.

bash

npx playwright test --debug
npx playwright test auth.spec.ts --debug --grep "login"

ts

test('drill into a step', async ({ page }) => {
  await page.goto('/login')
  await page.pause() // opens the Inspector
  await page.getByLabel('Email').fill('a@b.c')
})

HTML report

After a run, open the HTML report to see steps, screenshots, video and trace per test. Failed tests link directly into the trace viewer.

bash

npx playwright show-report

Take the quiz