skip to content

Interactive Run Modes

3 roadmaps5 questions

Running tests inside a watching UI or a paused inspector, stepping each action and picking locators live, rather than squinting at a headed browser flying past at full speed.

on this pageshow

explore

questions

5

What does npx playwright test --ui give you that a plain headed run does not?

level: juniorimportance: must knowfreq 62%

answer

  1. An explorer window, not a one-shot run
  2. Eye icon next to each test
  3. Filter by text, status, project, tag
  4. Every action keeps a DOM snapshot
  5. A button that hands you locators

basics

~20 s

Playwright's UI mode opens a watching test explorer: pick tests, re-run them on save, and step through a recorded timeline with before and after DOM snapshots, plus a Pick locator button. A headed run only shows the browser flying past.

solid answer

~50 s

`npx playwright test --ui` starts Playwright's UI mode: a long-lived window that lists every test the config discovers and keeps the run on screen after it finishes. You pick a test or a file, run it, then walk the recorded action list - selecting an action shows the DOM before and after it, with Source, Log, Console, Network, Errors and Attachments panes beside it. The eye icon next to a test turns on watch mode, so saving the spec re-runs it automatically. A filter box plus status chips, project and `@tag` filters narrow a large suite down to the one failing test. Pick locator lets you hover the snapshot and get the locator Playwright would generate for that element. A plain `--headed` run gives none of that: the browser flashes past at full speed and the evidence is gone when it closes.

code

bash · 8 lines
bash
# open the whole suite in UI mode
npx playwright test --ui

# open it already scoped to the order-tracker specs
npx playwright test tests/order-tracker --ui

# bind the UI server to a fixed port (containers, remote dev boxes)
npx playwright test --ui --ui-port=8080

go deeper

for a junior

Remember the command and the three things it buys you: a clickable test list, watch mode on the eye icon, and an action list with before and after snapshots. Try it on one failing test before reaching for print statements.

for a middle

Be able to explain that UI mode is a long-lived runner process that keeps each run's actions and DOM snapshots around, and that Pick locator validates a locator against real page state rather than generating a guess.

for a senior

Show that you use UI mode as the default local loop and know its edges: it needs a display, it is not a CI surface, and config changes need a restart while spec edits do not.

for a principal

Own the question of what the team's default debugging loop should be, and what it costs when everyone instead re-runs the whole suite headlessly and reads terminal output to find one broken selector.

UI mode is Playwright's interactive test explorer. Started with `npx playwright test --ui`, it replaces the one-shot terminal run with a window you keep open while you work, the way you keep a dev server open. ## What the window is made of - **Test list** on the left - every file, `describe` and test the config discovers, each with a status glyph and a duration. - **Timeline** along the top of a finished run - hovering it scrubs through film-strip frames of the page. - **Actions list** - one row per Playwright call: `page.goto`, `getByRole(...).click()`, every `expect`. - **Snapshot pane** - the DOM before, during and after the selected action. It is a real DOM you can hover, not a screenshot. - **Source, Log, Console, Network, Errors and Attachments tabs**, all scoped to whichever action you selected. On a food-delivery order tracker, selecting the click on the **Track driver** button shows you the page exactly as it was before the click, the call log for that click, the requests it fired, and the line of your spec that issued it - all without re-running anything. ## The watch loop The edit-and-rerun cycle is the reason UI mode exists. 1. Click the eye icon next to a spec file or a single test to watch it. 2. Edit and save the spec - or let your dev server rebuild the app under test. 3. The watched tests re-run on their own and the timeline refreshes in place. You never retype a command, never re-scope a `--grep`, and never lose the window's scroll position. For a test you are actively writing, that turns a ten-second terminal round trip into a save. ## Narrowing a big suite UI mode gives four independent filters, and they stack: - a free-text box that matches test titles; - status chips for passed, failed and skipped; - a project selector fed by the `projects` array in your Playwright config; - `@tag` filtering, matching tags written into test titles. So `@smoke` plus **failed** plus the `chromium` project is two clicks away from a suite of several hundred order-tracker tests. ## Pick locator The **Pick locator** button turns the snapshot into a locator picker: hover an element and Playwright shows the locator it would generate for it, ready to copy. The box is editable in both directions - type `getByRole('button', { name: 'Track driver' })` into it and UI mode highlights what that locator actually resolves to. That is a live check that the locator you are about to commit hits exactly one intended element, done against the real page state rather than by guessing. ## UI mode versus a plain headed run | | `--headed` | `--ui` | |---|---|---| | What you watch | the live browser at full speed | a recorded action list you scrub | | After the run | window closes, evidence gone | run stays on screen indefinitely | | Re-running | retype the command | save the file, watch mode re-runs | | Choosing tests | `--grep` or a path argument | click, filter by status, project, tag | | Locator help | none | Pick locator with live highlight | | Per-action detail | none | DOM snapshot, Log, Console, Network, Source | A headed run answers "did the page look roughly right?". UI mode answers "what exactly was on the page at the moment step seven ran, and what did that step do?". ## Practical notes - It is a local developer tool. It needs a display and a browser window, so it is not something you turn on inside a pipeline. - `--ui-port` and `--ui-host` control where the UI server binds, which is what you need when you run it inside a container or a remote dev box. - It respects your config: the same `projects`, fixtures and `use` options apply, so a test that passes in UI mode is running under the same settings as the terminal run. - Changing the config itself is the one edit that needs a restart of the UI process; spec edits do not. - It complements rather than replaces the terminal run - CI still runs `npx playwright test` and reports through reporters.

  • How do you get UI mode to re-run a test without touching the terminal?
    Click the eye icon beside the test or its file to enable watch mode, then save the spec. Playwright re-runs just the watched tests and refreshes the action list in place. You can also hit the run button on a single test, or run the whole file, straight from the sidebar.
  • Why is UI mode a local tool rather than something you enable in a pipeline?
    It is an interactive window: it serves a UI, keeps the process alive waiting for clicks, and needs a display and a browser. A pipeline has no one to click and no window to draw into, so CI runs the normal headless command and reports through reporters instead.

A headed run is watching a play from the back row; UI mode is the rehearsal recording you can pause, rewind and step through frame by frame.

saying these in an interview costs you the question

  • Says UI mode is just the headed browser with a nicer title bar
  • Thinks UI mode needs a special config flag to be enabled
  • Claims watch mode re-runs the entire suite on every save
  • Believes UI mode is meant to run in CI pipelines
  • Assumes the snapshot pane is a screenshot rather than a real DOM
open as a page

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

level: middleimportance: must knowfreq 55%

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.

open as a page

Why does await page.pause() in a Playwright test require a headed browser?

level: middleimportance: should knowfreq 44%

basics

~20 s

The only way past page.pause() is a human pressing Resume in the Playwright Inspector, and the Inspector is a window. Headless there is nobody to resume it, so the call belongs in a local session and never in committed code.

open as a page

In Playwright, what does DEBUG=pw:api show you that a headed re-run does not?

level: seniorimportance: should knowfreq 37%

basics

~20 s

Playwright's DEBUG=pw:api logging prints its own call log to stderr: every API call, the element each locator resolved to, and the reason each action retried. A headed re-run shows the final picture but never names the failing check.

open as a page

Your team debugs every Playwright failure by re-running headed with slowMo. What would you change?

level: principalimportance: should knowfreq 30%

basics

~20 s

Make UI mode the default local loop and keep headed plus slowMo for the rare interaction you must watch in real time. Slowing every action changes timing, costs wall-clock minutes per look, and leaves no record to re-examine.

open as a page