Playwright 04 ๐ญ Running Tests โ npx playwright test & Headed vs Headless Mode
Playwright runs tests in headless mode by default. No browser window opens, the results appear in the terminal, and the run completes faster because there is no rendering to wait for. The --headed flag flips this: the browser window opens for each test, the actions are visible as they execute, and the run is slower because the browser is doing everything it does in headless mode plus drawing it on screen. The choice between the two is not about correctnessโthe same test passes or fails either wayโit is about whether a human needs to watch.
This chapter covers the run command, the filtering flags that select a subset of tests, the headed and headless modes, and the debugging flags that pause execution for inspection. The sections that follow walk through the basic run, the selection options, and the mode that determines what the human sees.
Key point: npx playwright test runs all tests headless; --headed opens the browser window for debugging; the selection flags (--project, -g, file paths, :line) narrow the run without changing the mode.
a. The run command and test selection
The base command is npx playwright test. It reads playwright.config.ts, runs every test in the configured testDir, on every configured project, in parallel by default, and prints the results to the terminal . The command exits with a non-zero code if any test fails, which is what CI uses to decide whether to continue.
The command accepts positional arguments that are treated as regular expressions matched against the full test file path. A single file runs by passing its path; a directory runs every test inside it; a line number runs the test at that line .
# Run all tests
npx playwright test
# Run a single file
npx playwright test tests/todo-page.spec.ts
# Run a set of files or directories
npx playwright test tests/todo-page/ tests/landing-page/
# Run the test at line 42 of a file
npx playwright test my-spec.ts:42
# Run tests matching a title
npx playwright test -g "add a todo item"
The --project flag selects a configured browser or environment. The default runs every project in playwright.config.ts; --project=chromium runs only the Chromium project, and --project=chromium --project=firefox runs two .
# Run only Chromium
npx playwright test --project=chromium
The -g (or --grep) flag filters by test title. The regular expression is matched against the project name, file name, describe names, and test name, which is why -g "login" can match a test in auth.spec.ts titled “user can log in” .
b. Headed and headless modes
Headless is the default. The browser runs without a visible window, and the test’s actions are invisible. The mode is faster, uses less memory, and is the only mode that makes sense in CI where there is no display .
Headed mode opens a visible browser window for each test. The --headed flag is the switch .
# Headless (default)
npx playwright test
# Headed: watch the browser
npx playwright test --headed
The headed mode is for debugging, not for the normal run. A test that fails only in headed mode is usually a timing or visibility issue that the headless run hides, and a test that fails only in headless mode is usually a rendering difference that the headed run hides. The headed mode is slower because the browser has to draw the page, and the extra time can change the behavior of a test that races against an animation or a network response.
The mode can also be set in the config with use: { headless: false }, but the CLI flag takes precedence and is the easier switch for a single run . The --debug flag implies --headed and also sets --workers=1 and --max-failures=1, so a debugging run stops at the first failure with a visible browser .
c. Parallelism, workers, and the debugger
Playwright runs tests in parallel by default, using a number of worker processes equal to 50% of the logical CPU cores . The --workers flag overrides the count; --workers=1 runs everything serially, which is useful when the test output is interleaved and hard to read, or when a test depends on shared state that parallel execution breaks.
# Serial run
npx playwright test --workers=1
# Stop after the first failure
npx playwright test -x
# Debug with the Playwright Inspector
npx playwright test --debug
The --debug flag is a shortcut for the combination of PWDEBUG=1, --timeout=0 (no timeout), --max-failures=1, --headed, and --workers=1 . It opens the Playwright Inspector, which lets the test pause at each action, step through the calls, and inspect the locators. The --ui flag runs the tests in the interactive UI mode, which includes a watch mode and a timeline view of each test’s steps .
The -x flag stops the run after the first failure. In a suite with a broken shared setup, the first failure is the cause and the rest are symptoms; -x keeps the output focused on the cause. The --retries flag sets the number of retries for flaky tests, and --repeat-each runs every test a given number of times to surface intermittent failures .
Complete Example Session
# ============================================
# PART 1: THE BASIC RUN
# ============================================
npx playwright test
# Headless, parallel, all projects, all tests
# ============================================
# PART 2: SELECTING A SUBSET
# ============================================
# One project
npx playwright test --project=chromium
# One file
npx playwright test tests/login.spec.ts
# Tests matching a title
npx playwright test -g "login"
# ============================================
# PART 3: HEADED MODE
# ============================================
# Watch the browser
npx playwright test --headed
# ============================================
# PART 4: DEBUGGING
# ============================================
# Inspector, no timeout, one worker, headed
npx playwright test --debug
# UI mode with watch
npx playwright test --ui
# Stop at first failure
npx playwright test -x
# Serial run
npx playwright test --workers=1
The parts covered the basic run, the selection flags, the headed mode, and the debugging flags.
Quick Reference
Run Commands
| Command | Effect |
|---|---|
npx playwright test | All tests, headless, parallel |
npx playwright test --headed | Visible browser |
npx playwright test --debug | Inspector, no timeout, one worker |
npx playwright test --ui | Interactive UI mode |
npx playwright test -x | Stop at first failure |
npx playwright test --workers=1 | Serial execution |
Selection Flags
| Flag | Selects |
|---|---|
path/to/file.spec.ts | One file |
path/to/dir/ | All tests in directory |
file.spec.ts:42 | Test at line 42 |
--project=chromium | One project |
-g "title" | Tests matching title |
--grep-invert "title" | Tests not matching title |
Mode Comparison
| Mode | Window | Speed | Use |
|---|---|---|---|
| Headless (default) | No | Faster | CI, normal runs |
Headed (--headed) | Yes | Slower | Debugging, watching |
Debug (--debug) | Yes | Slowest | Step-through inspection |
Best Practices
โ Do This:
# Run headless in CI
npx playwright test # โ
# Use --headed for debugging
npx playwright test --headed -g "failing test" # โ
# Select a project when only one matters
npx playwright test --project=chromium # โ
# Use --debug for step-through
npx playwright test --debug # โ
โ Don’t Do This:
# Set headless: false in the config and forget
# (CI has no display) # โ
# Use --headed for the normal run
# (slower, no benefit without watching) # โ
# Debug with --workers=1 but no --headed
# (cannot see the actions) # โ
Common Pitfalls
| Pitfall | Why It Happens | Fix |
|---|---|---|
CI fails on headless: false | No display | Remove the config setting, use CLI flag locally |
| Test passes headed, fails headless | Timing or rendering difference | Investigate the race, not the mode |
| Output interleaved | Parallel workers | --workers=1 |
Timeout in --debug | Default timeout | --debug sets --timeout=0 |
Real-World Examples
1. All tests headless
npx playwright test
2. One file
npx playwright test tests/login.spec.ts
3. One project
npx playwright test --project=chromium
4. Title filter
npx playwright test -g "add to cart"
5. Line filter
npx playwright test my-spec.ts:42
6. Headed
npx playwright test --headed
7. Debug
npx playwright test --debug
8. UI mode
npx playwright test --ui
9. Stop on failure
npx playwright test -x
10. Serial
npx playwright test --workers=1
Visual
Headless vs Headed
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ HEADLESS (default) โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ Browser runs without a window โ โ
โ โ Results in terminal โ โ
โ โ Faster, less memory โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ
โ HEADED (--headed) โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ Browser window opens โ โ
โ โ Actions visible as they run โ โ
โ โ Slower, for debugging โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Selection Flow
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ npx playwright test โ
โ โ โ
โ โโโ --project=chromium โ only Chromium โ
โ โโโ -g "login" โ only matching titles โ
โ โโโ tests/file.ts โ only that file โ
โ โโโ :42 โ only that line โ
โ โ
โ Flags combine: --project=chromium -g "login" โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Debug vs UI Mode
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ --debug --ui โ
โ โโโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ Playwright Inspector โ โ Interactive UI โ โ
โ โ Step through โ โ Watch mode โ โ
โ โ No timeout โ โ Timeline view โ โ
โ โ One worker โ โ Step details โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Summary
| Item | Value |
|---|---|
| Default mode | Headless |
| Headed flag | --headed |
| Basic command | npx playwright test |
| Project filter | --project=chromium |
| Title filter | -g "pattern" |
| Debug | --debug (headed, no timeout, one worker) |
| UI mode | --ui |
| Stop on failure | -x |
| Serial | --workers=1 |
Key takeaways:
- Headless is the default and the correct mode for CI. No browser window opens, the run is faster, and the results appear in the terminal. The
--headedflag is for debugging, not for the normal run . - The positional arguments are file paths and line numbers. A single file, a directory, or a line number narrows the run without changing the mode .
--projectselects a configured browser or environment. The default runs every project inplaywright.config.ts;--project=chromiumruns one .--debugis a bundle of flags. It sets headed mode, no timeout, one worker, and stops at the first failure, and it opens the Playwright Inspector for step-through debugging .- Parallelism is the default.
--workers=1makes the run serial, which is useful when the output is interleaved or a test depends on shared state .
Remember: The run command is npx playwright test, and the mode is headless unless --headed is passed. The selection flags narrow what runs; the mode flags determine what the human sees. Use headless for the normal run and CI, headed for watching a test that needs to be seen, and --debug for stepping through the actions. The --project and -g flags combine to focus a run on one browser and one behavior, which is the fastest way to investigate a failure.
Stop using slow, ad-bloated tool sites! ๐คฎ
๐ Search “KandZ Tools” on Google to use many professional utilities for free.
KandZ.me is the ultimate minimalist hub for:
โ
Finance (Mortgage, Interest, Inflation)
โ
Tech (Base64, JSON, Dev Suite, IP)
โ
Health (BMI, BMR, TDEE)
โ
Productivity (Timer, Workspace, QR)
โก๏ธ Fast & Private
๐ No data leaves your device
๐ 100% Free
๐ Use it now: https://tools.kandz.me
๐ Bookmark itโyouโll need it later!