| | |

Playwright 04 ๐ŸŽญ Running Tests โ€” npx playwright test & Headed vs Headless Mode

โฑ๏ธ Estimated read: 8 min | |

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

CommandEffect
npx playwright testAll tests, headless, parallel
npx playwright test --headedVisible browser
npx playwright test --debugInspector, no timeout, one worker
npx playwright test --uiInteractive UI mode
npx playwright test -xStop at first failure
npx playwright test --workers=1Serial execution

Selection Flags

FlagSelects
path/to/file.spec.tsOne file
path/to/dir/All tests in directory
file.spec.ts:42Test at line 42
--project=chromiumOne project
-g "title"Tests matching title
--grep-invert "title"Tests not matching title

Mode Comparison

ModeWindowSpeedUse
Headless (default)NoFasterCI, normal runs
Headed (--headed)YesSlowerDebugging, watching
Debug (--debug)YesSlowestStep-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

PitfallWhy It HappensFix
CI fails on headless: falseNo displayRemove the config setting, use CLI flag locally
Test passes headed, fails headlessTiming or rendering differenceInvestigate the race, not the mode
Output interleavedParallel workers--workers=1
Timeout in --debugDefault 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

ItemValue
Default modeHeadless
Headed flag--headed
Basic commandnpx 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 --headed flag 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 .
  • --project selects a configured browser or environment. The default runs every project in playwright.config.ts; --project=chromium runs one .
  • --debug is 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=1 makes 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.

Was this helpful?


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!