| | |

Playwright 15 ๐ŸŽญ Debugging โ€” UI mode, –debug, and the Trace Viewer

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

Playwright ships three debugging tools that serve different moments in the test lifecycle. UI mode is the interactive runner for development: it watches files, runs tests on save, and shows the action timeline with DOM snapshots as the test executes . --debug is the pause-and-step mode: it opens the Playwright Inspector, sets the timeout to zero, and lets you walk through each action with the browser visible . The Trace Viewer is the post-mortem tool: it opens a recorded trace.zip and lets you replay the actions, inspect the DOM at each step, and read the console and network logs for the failure . The three overlap in what they show, but they are used at different times and for different reasons.

This chapter covers the three tools, the config that records the trace, and the workflow that moves from a CI failure to the trace that explains it. The sections that follow walk through UI mode, the --debug inspector, and the trace recording and viewing that makes a remote failure diagnosable.

Key point: UI mode is for local development (--ui), --debug is for stepping through a test with the Inspector, and the Trace Viewer is for the recorded artifact (trace: 'on-first-retry' in CI, opened with show-trace or from the HTML report).


a. UI mode and the action timeline

UI mode is launched with npx playwright test --ui. It opens a desktop application (or a browser tab with --ui-host) that lists every test file, lets you run a single test or a file, and shows the action timeline when a test runs .

The timeline is the feature that replaces the console.log archaeology. Every actionโ€”goto, click, fill, expectโ€”appears as a step, and clicking a step shows the DOM snapshot for that moment. The Before and After tabs show what the page looked like before the action and what changed as a result . The pick locator button lets you hover over the snapshot and get the locator Playwright would use, which is the fastest way to fix a locator that is not matching .

The watch mode is the other half of UI mode. Saving a test file re-runs the affected tests, which makes the red-green-refactor loop a matter of saving the file . The filter bar lets you narrow the list by project, status, or tag, which is the difference between opening the whole suite and opening the failing Firefox-only test .

The UI mode does not run the dependency projects automatically. A test that depends on a setup project needs the setup run first, and the UI mode’s documentation notes that it does not take the setup tests into account . The setup file is run with npx playwright test --project=setup or by running the whole suite once before opening the UI.


b. --debug and the Playwright Inspector

The --debug flag is the shortcut for a debugging run. It sets PWDEBUG=1, launches the browser in headed mode, sets the timeout to zero (no timeout), and opens the Playwright Inspector . The test pauses at the start, and the Inspector’s toolbar lets you play, pause, or step through each action.

npx playwright test --debug

The Inspector shows the current action highlighted in the test code and the matching element highlighted in the browser. The “Pick Locator” button and the locator playground let you edit a locator and see the matching elements in the browser window live . The actionability log shows what Playwright checked before the actionโ€”whether the element was visible, enabled, and stableโ€”which is the information that explains why a click waited or failed.

The page.pause() call is the breakpoint. A test with await page.pause() runs until that line and pauses there, which is faster than stepping through every action to reach the point of interest . The PWDEBUG=console variant exposes a playwright object in the browser’s DevTools console, which is the escape hatch for inspecting the DOM with the browser’s own tools .


c. The Trace Viewer and the recorded artifact

The Trace Viewer is for the test that already ran. The trace is recorded during the run, and the trace config option controls when: 'on-first-retry' records the first retry of a failed test, 'retain-on-failure' keeps the trace for every failure, and 'on' records every test .

// playwright.config.ts
export default defineConfig({
  retries: process.env.CI ? 2 : 0,
  use: {
    trace: "on-first-retry",
  },
});

The trace file is a trace.zip that contains the DOM snapshots, the screenshots, the network requests, the console logs, and the source locations for each action. The viewer is opened with npx playwright show-trace path/to/trace.zip or from the HTML report, where each failed test has a “View Trace” link . The viewer can also open a remote trace directly from a URL, which is the pattern for a CI artifact that is already uploaded to storage .

The viewer’s layout is the same information as the UI mode’s timeline, but for a recorded run. The Actions tab lists every action, and clicking one shows the Before/Action/After snapshots, the action log, and the source line. The Console and Network tabs are filtered to the selected action’s time range, which is the feature that turns a noisy log into a single failure . The trace.playwright.dev hosted viewer loads the trace entirely in the browser, and the cross-origin rules apply to a remote URL .

The trace is the artifact that makes a CI failure reproducible. A test that fails on the CI runner and passes locally is a test that needs the trace from the CI run, and the on-first-retry setting is what records it without the cost of recording every test.


Complete Example Session

// ============================================
// PART 1: THE CONFIG THAT RECORDS THE TRACE
// ============================================
// playwright.config.ts
import { defineConfig } from "@playwright/test";

export default defineConfig({
  retries: process.env.CI ? 2 : 0,
  use: {
    trace: "on-first-retry",
  },
});

// ============================================
// PART 2: UI MODE (LOCAL DEVELOPMENT)
// ============================================
// npx playwright test --ui
// Click a test โ†’ watch the timeline โ†’ pick a locator

// ============================================
// PART 3: --debug (STEP THROUGH)
// ============================================
// npx playwright test --debug
// The Inspector pauses at the start; step through each action

// ============================================
// PART 4: THE TRACE (CI FAILURE)
// ============================================
// The CI run records trace.zip on the first retry.
// Open the HTML report: npx playwright show-report
// Click "View Trace" on the failed test
// Or: npx playwright show-trace trace.zip

The parts covered the trace config, the UI mode, the --debug inspector, and the trace from a CI failure.


Quick Reference

The Three Tools

ToolCommandUse For
UI modenpx playwright test --uiLocal development, watch mode
Debugnpx playwright test --debugStepping through a test
Trace Viewernpx playwright show-trace trace.zipRecorded failure

Trace Recording Options

OptionRecords
'off'Nothing
'on'Every test
'on-first-retry'The first retry of a failed test
'retain-on-failure'Every failure

Trace Viewer Panels

PanelShows
ActionsEvery action and its snapshot
ConsoleBrowser and test logs
NetworkRequests, filtered by action
SourceThe test line for the action

Best Practices

โœ… Do This:

# Use UI mode for local development
npx playwright test --ui                                      # โœ…

# Use --debug to step through a specific test
npx playwright test tests/checkout.spec.ts --debug            # โœ…

# Record the trace on the first retry in CI
trace: "on-first-retry"                                       # โœ…

โŒ Don’t Do This:

# Record every trace by default
trace: "on" # heavy                                         # โŒ

# Use --debug in CI
# (it waits for a human)                                    # โŒ

# Forget the setup project in UI mode
# (the dependency is not run automatically)                 # โŒ

Common Pitfalls

PitfallWhy It HappensFix
No trace in CItrace: "off""on-first-retry"
UI mode shows unauthenticated testsSetup project not runRun the setup project first
Trace does not open remotelyCORS rulesUse the HTML report or upload the trace
Inspector does not pauseNo --debugPass the flag

Real-World Examples

1. UI mode

npx playwright test --ui

2. Debug a single test

npx playwright test tests/checkout.spec.ts --debug

3. Trace config

use: { trace: "on-first-retry" }

4. Open a trace

npx playwright show-trace trace.zip

5. Open from the HTML report

npx playwright show-report

6. Remote trace

npx playwright show-trace https://example.com/trace.zip

7. The hosted viewer

https://trace.playwright.dev/?trace=<url>

8. Pause in a test

await page.pause();

9. Pick a locator in UI mode

Click "Pick locator" โ†’ hover the snapshot โ†’ copy

10. Filter by action

Double-click an action โ†’ the console and network filter

Visual

The Three Tools

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚  UI MODE                    DEBUG                       โ”‚
โ”‚  Local development           Step through               โ”‚
โ”‚  Watch mode                  Inspector                  โ”‚
โ”‚  Timeline                    Timeout = 0                โ”‚
โ”‚                                                         โ”‚
โ”‚  TRACE VIEWER                                           โ”‚
โ”‚  Recorded artifact                                      โ”‚
โ”‚  CI failure analysis                                    โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

The Trace Recording

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚  trace: "on-first-retry"                                โ”‚
โ”‚         โ”‚                                               โ”‚
โ”‚         โ–ผ                                               โ”‚
โ”‚  Test fails โ†’ retry โ†’ trace.zip recorded                โ”‚
โ”‚         โ”‚                                               โ”‚
โ”‚         โ–ผ                                               โ”‚
โ”‚  HTML report โ†’ "View Trace"                             โ”‚
โ”‚         โ”‚                                               โ”‚
โ”‚         โ–ผ                                               โ”‚
โ”‚  Trace Viewer โ†’ Actions, Console, Network               โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

The Action Timeline

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚  Actions:                                               โ”‚
โ”‚  โ”œโ”€โ”€ goto /login                                        โ”‚
โ”‚  โ”œโ”€โ”€ fill Email                                         โ”‚
โ”‚  โ”œโ”€โ”€ fill Password                                      โ”‚
โ”‚  โ”œโ”€โ”€ click Sign in                                      โ”‚
โ”‚  โ””โ”€โ”€ expect heading "Dashboard"   โ—„โ”€โ”€ failed            โ”‚
โ”‚                                                         โ”‚
โ”‚  Click the failed action โ†’ DOM snapshot โ†’ inspect       โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

Summary

ItemValue
UI modenpx playwright test --ui
Debugnpx playwright test --debug
Trace configuse: { trace: "on-first-retry" }
Open tracenpx playwright show-trace trace.zip
HTML reportnpx playwright show-report
Hosted viewertrace.playwright.dev
Pauseawait page.pause()

Key takeaways:

  • UI mode is for local development. It watches files, runs tests on save, and shows the action timeline with DOM snapshots. The pick locator button is the fastest way to fix a locator that is not matching .
  • --debug is for stepping through a test. It opens the Inspector, sets the timeout to zero, and lets you walk through each action with the browser visible. The page.pause() call is the breakpoint that skips the stepping .
  • The Trace Viewer is for the recorded failure. The trace: "on-first-retry" setting records the trace on the first retry of a failed test, which is the artifact that makes a CI failure diagnosable .
  • The trace is opened from the HTML report or the CLI. The report’s “View Trace” link is the fastest local entry point, and the show-trace command opens a file directly .
  • The viewer’s timeline filters the logs. Double-clicking an action narrows the console and network to that action’s time range, which turns a noisy test into a single failure .

Remember: The three tools are for three moments. UI mode is for writing the test, --debug is for stepping through the test that is failing locally, and the Trace Viewer is for the test that failed on CI and cannot be reproduced locally. Use the UI mode for the development loop, the --debug flag for the local failure, and the trace: "on-first-retry" setting for the CI artifact. The trace is the evidence; the viewer is how the evidence is read.

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!