Playwright 15 ๐ญ Debugging โ UI mode, –debug, and the Trace Viewer
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
| Tool | Command | Use For |
|---|---|---|
| UI mode | npx playwright test --ui | Local development, watch mode |
| Debug | npx playwright test --debug | Stepping through a test |
| Trace Viewer | npx playwright show-trace trace.zip | Recorded failure |
Trace Recording Options
| Option | Records |
|---|---|
'off' | Nothing |
'on' | Every test |
'on-first-retry' | The first retry of a failed test |
'retain-on-failure' | Every failure |
Trace Viewer Panels
| Panel | Shows |
|---|---|
| Actions | Every action and its snapshot |
| Console | Browser and test logs |
| Network | Requests, filtered by action |
| Source | The 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
| Pitfall | Why It Happens | Fix |
|---|---|---|
| No trace in CI | trace: "off" | "on-first-retry" |
| UI mode shows unauthenticated tests | Setup project not run | Run the setup project first |
| Trace does not open remotely | CORS rules | Use the HTML report or upload the trace |
| Inspector does not pause | No --debug | Pass 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
| Item | Value |
|---|---|
| UI mode | npx playwright test --ui |
| Debug | npx playwright test --debug |
| Trace config | use: { trace: "on-first-retry" } |
| Open trace | npx playwright show-trace trace.zip |
| HTML report | npx playwright show-report |
| Hosted viewer | trace.playwright.dev |
| Pause | await 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 .
--debugis 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. Thepage.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-tracecommand 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.
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!