In Playwright, what does the --debug flag change about how a test run executes?

middlemust knowfreq 55%

answer

A shortcut for one environment variable
Headed, and only one worker
Nothing expires while you read
Paused before the first action
Not the same run that failed

basics

~20 s

Playwright's --debug flag is a shortcut for PWDEBUG=1. It runs the browser headed, drops the run to a single worker, sets timeouts to zero so nothing expires while you read, and opens the Playwright Inspector paused before the first action.

solid answer

~50 s

npx playwright test --debug is the shortcut for the PWDEBUG=1 environment variable, and it changes four things at once. The browser runs headed, the run drops to a single worker, timeouts are set to zero so neither the test nor an individual action can expire while you sit reading, and the Playwright Inspector opens with execution paused before the first action. In the Inspector you step action by action with Step over, let it run with Resume, watch the highlighted line of your spec, read the call log for the pending action, and use Pick locator to build a selector against the live page. Those four changes are also a caveat: a run under --debug is not the run that failed. One worker and no timeouts can hide a parallelism or timing problem, so always scope it to the failing test rather than debugging the whole suite.

`npx playwright test --debug` is the shortcut for the `PWDEBUG=1` environment variable, and it changes four things at once. The browser runs **headed**, the run drops to a **single worker**, **timeouts are set to zero** so neither the test nor an individual action can expire while you sit reading, and the **Playwright Inspector** opens with execution paused before the first action. In the Inspector you step action by action with Step over, let it run with Resume, watch the highlighted line of your spec, read the call log for the pending action, and use Pick locator to build a selector against the live page. Those four changes are also a caveat: a run under `--debug` is not the run that failed. One worker and no timeouts can hide a parallelism or timing problem, so always scope it to the failing test rather than debugging the whole suite.

code

bash · 8 lines

bash

# whole suite - stops at the first line of every test, rarely what you want
npx playwright test --debug

# scoped to one test by file and line number
npx playwright test tests/driver-map.spec.ts:42 --debug

# the environment variable the flag is a shortcut for
PWDEBUG=1 npx playwright test tests/driver-map.spec.ts

go deeper

for a junior

Learn the command and what appears: a headed browser plus the Inspector, paused, with Resume and Step over. Scope it to one file so you are not pausing on every test in the suite.

for a middle

Explain all four effects - headed, one worker, timeouts zeroed, Inspector opened - and name the environment variable the flag stands in for. That completeness is what the question is testing.

for a senior

Point out that the debug run is not the run that failed: no timeouts and a single worker can hide exactly the race or shared-state clash you were chasing, and that gap is itself diagnostic information.

for a principal

Decide when stepping through a single test is worth an engineer's afternoon versus investing in evidence the run produces on its own, so that most failures are explained without anyone reproducing them by hand.

--debug is the flag on npx playwright test that hands the run over to the Playwright Inspector. It is documented as a shortcut for the PWDEBUG=1 environment variable, so PWDEBUG=1 npx playwright test behaves the same way.

The four things it changes

Headed. The browser opens with a visible window, whatever headless says in your config, because you need to see the page you are stepping through.
One worker. Parallelism is switched off so the Inspector is driving a single, comprehensible test at a time.
Timeouts go to zero. Test timeout and action timeouts are disabled, so nothing expires while you read a call log or take a phone call.
The Inspector opens, paused. Execution stops before the first action and waits for you.

What the Inspector gives you

Resume runs to the end (or to the next page.pause()), Step over executes exactly one action.
The source pane highlights the line about to run, so you always know where you are.
The call log shows what the pending action is doing - the locator it resolved, the checks it is waiting on, each retry.
Pick locator and the explore box let you hover elements in the live page and get, or verify, a locator - useful when the failure is "this selector does not match what I thought".
The browser itself highlights the element the pending action targets, which instantly answers "is it even aiming at the right button?".

On a food-delivery order tracker, stepping to the click on Refresh and seeing the highlight land on the map overlay rather than the button ends the investigation in one step.

Why the changed settings are also a caveat

The run you are debugging is not the run that failed, and that matters:

With timeouts at zero, an action that would have failed after 30 seconds now hangs indefinitely. You have to read the call log to notice, rather than waiting for a red failure.
With one worker, any failure caused by two workers sharing an account, a database row or a port simply will not reproduce.
Under headed rendering, viewport, focus and animation behaviour can differ from the headless run.

So a test that passes under --debug and fails in the normal run is itself a finding: it points at timing or parallelism rather than at the selector.

Scope the debug run

Never point --debug at the whole suite - it stops at the first line of every test in turn and you spend the afternoon pressing Resume. Scope it:

by file: npx playwright test tests/driver-map.spec.ts --debug
by line, to a single test: npx playwright test tests/driver-map.spec.ts:42 --debug
by title: npx playwright test -g "driver marker" --debug

The related environment variables

Setting	Headed	Timeouts	What it opens
`--debug` / `PWDEBUG=1`	yes	zero	the Playwright Inspector
`PWDEBUG=console`	yes	zero	no Inspector; exposes a `playwright` helper object in the browser console
`DEBUG=pw:api`	no change	unchanged	nothing - it only writes a call log to stderr

The distinction worth carrying: PWDEBUG is about pausing and stepping, DEBUG is about logging. They are different variables that solve different problems, and mixing them up is a common interview stumble.

What it does not change

--debug is a run switch, not a rewrite of your test. Everything else stays as configured:

your fixtures, use options and projects still apply, so you are debugging the real setup;
expect still retries exactly as it normally would - it simply has no deadline;
reporters still run, so the session produces its usual terminal output;
nothing is written into your spec file, which is its main advantage over an in-code breakpoint.

Choosing between the Inspector and UI mode

Both are interactive, and they answer different questions. The Inspector is best when you want to stop before an action and poke at the live page, because everything you inspect is the real, current browser state. UI mode is best when you want to look back over a whole run, comparing what the DOM looked like before and after each step. In practice many teams live in UI mode and drop to --debug for the one action that refuses to explain itself.

`--debug` is the flag on `npx playwright test` that hands the run over to the Playwright Inspector. It is documented as a shortcut for the `PWDEBUG=1` environment variable, so `PWDEBUG=1 npx playwright test` behaves the same way. ## The four things it changes 1. **Headed.** The browser opens with a visible window, whatever `headless` says in your config, because you need to see the page you are stepping through. 2. **One worker.** Parallelism is switched off so the Inspector is driving a single, comprehensible test at a time. 3. **Timeouts go to zero.** Test timeout and action timeouts are disabled, so nothing expires while you read a call log or take a phone call. 4. **The Inspector opens, paused.** Execution stops before the first action and waits for you. ## What the Inspector gives you - **Resume** runs to the end (or to the next `page.pause()`), **Step over** executes exactly one action. - The **source pane** highlights the line about to run, so you always know where you are. - The **call log** shows what the pending action is doing - the locator it resolved, the checks it is waiting on, each retry. - **Pick locator** and the explore box let you hover elements in the live page and get, or verify, a locator - useful when the failure is "this selector does not match what I thought". - The browser itself highlights the element the pending action targets, which instantly answers "is it even aiming at the right button?". On a food-delivery order tracker, stepping to the click on **Refresh** and seeing the highlight land on the map overlay rather than the button ends the investigation in one step. ## Why the changed settings are also a caveat The run you are debugging is not the run that failed, and that matters: - With **timeouts at zero**, an action that would have failed after 30 seconds now hangs indefinitely. You have to read the call log to notice, rather than waiting for a red failure. - With **one worker**, any failure caused by two workers sharing an account, a database row or a port simply will not reproduce. - Under **headed** rendering, viewport, focus and animation behaviour can differ from the headless run. So a test that passes under `--debug` and fails in the normal run is itself a finding: it points at timing or parallelism rather than at the selector. ## Scope the debug run Never point `--debug` at the whole suite - it stops at the first line of every test in turn and you spend the afternoon pressing Resume. Scope it: - by file: `npx playwright test tests/driver-map.spec.ts --debug` - by line, to a single test: `npx playwright test tests/driver-map.spec.ts:42 --debug` - by title: `npx playwright test -g "driver marker" --debug` ## The related environment variables | Setting | Headed | Timeouts | What it opens | |---|---|---|---| | `--debug` / `PWDEBUG=1` | yes | zero | the Playwright Inspector | | `PWDEBUG=console` | yes | zero | no Inspector; exposes a `playwright` helper object in the browser console | | `DEBUG=pw:api` | no change | unchanged | nothing - it only writes a call log to stderr | The distinction worth carrying: `PWDEBUG` is about **pausing and stepping**, `DEBUG` is about **logging**. They are different variables that solve different problems, and mixing them up is a common interview stumble. ## What it does not change `--debug` is a *run* switch, not a rewrite of your test. Everything else stays as configured: - your fixtures, `use` options and `projects` still apply, so you are debugging the real setup; - `expect` still retries exactly as it normally would - it simply has no deadline; - reporters still run, so the session produces its usual terminal output; - nothing is written into your spec file, which is its main advantage over an in-code breakpoint. ## Choosing between the Inspector and UI mode Both are interactive, and they answer different questions. The Inspector is best when you want to *stop before an action and poke at the live page*, because everything you inspect is the real, current browser state. UI mode is best when you want to *look back over a whole run*, comparing what the DOM looked like before and after each step. In practice many teams live in UI mode and drop to `--debug` for the one action that refuses to explain itself.

Your test passes under --debug but fails in a normal run. What does that tell you?
That the failure depends on something `--debug` changed. It forces one worker and disables timeouts, so a shared-state clash between parallel workers, or a race the slower stepping pace papers over, is the likely cause - not the locator. Reproduce it with the normal worker count and read the call log instead.
How is PWDEBUG different from the DEBUG environment variable in Playwright?
`PWDEBUG=1` is an interactive switch: headed browser, zero timeouts, Inspector paused before the first action. `DEBUG=pw:api` is pure logging - it prints Playwright's API call log to stderr, changes nothing about how the run executes, and works fine headless where no Inspector could open.
Why should you scope --debug to a single test rather than the whole suite?
Because it pauses at the start of every test it runs, so a hundred-test suite means a hundred Resume presses. Scope it with a path, a `file:line` argument, or `-g` on the title, so the Inspector opens exactly on the test you are investigating.

saying these in an interview costs you the question

Thinks --debug only makes the browser headed
Believes timeouts still apply during a debug run
Confuses PWDEBUG with the DEBUG logging variable
Assumes a debug run reproduces parallel-worker failures
Runs --debug across the whole suite and pauses everywhere
Says --debug needs a config change to work

In Playwright, what does the --debug flag change about how a test run executes?

§ answer

basics

solid answer

code

§ go deeper

▾level notes4 levels

▾deep dive~4 min

The four things it changes

What the Inspector gives you

Why the changed settings are also a caveat

Scope the debug run

The related environment variables

What it does not change

Choosing between the Inspector and UI mode

▾common follow-ups3 questions

▾red flags6 flags

The four things it changes

What the Inspector gives you

Why the changed settings are also a caveat

Scope the debug run

The related environment variables

What it does not change

Choosing between the Inspector and UI mode

answer

go deeper