Running, Tagging, and Debugging Tests

Playwright's CLI exposes a rich set of run modes that help both humans and AI agents iterate quickly. npx playwright test runs everything; you can scope to one file (npx playwright test e2e/auth.spec.ts), to a single project (--project=chromium), or to a substring of a test name (-g 'login'). Tags live in the test title, so test('login @smoke', ...) can be selected with --grep @smoke or excluded with --grep-invert @slow. Other useful flags include --headed to watch the browser, --debug (or PWDEBUG=1) to open the inspector, --ui for the interactive UI mode, --list to enumerate tests without running, --workers=1 to disable parallelism, --max-failures=1 to bail early, --retries=2 to retry, --shard=1/3 to split a suite across machines, and --forbid-only to keep test.only out of the main branch.

The fastest way to bootstrap a new test is npx playwright codegen , which records clicks and typing into a spec. Codegen output is rarely production-ready: it tends to pick brittle CSS selectors and weak assertions, so the standard workflow is to record, then refactor toward getByRole/getByLabel and meaningful expect() checks. When recording against a mobile profile, pass --device 'iPhone 13', and when you need to record post-login flows, load a storage state into a persistent context so the generator starts authenticated.

When tests fail, traces are the single most useful artifact. Setting use.trace = 'on-first-retry' (or 'on' locally) records screenshots, DOM snapshots, network, console, and actions into trace.zip, which you can open with npx playwright show-trace path/to/trace.zip. The HTML report itself is opened with npx playwright show-report, and you can attach extra debug info via testInfo.attach('name', { body, contentType }). Pair this with screenshot: 'only-on-failure' and video: 'retain-on-failure' so artifacts only accumulate when something actually went wrong. For local debugging, --headed --debug or page.pause() drops you into the inspector where you can step through actions and re-evaluate locators in real time.