Course contentsShow
← React
Lesson 2172 of 2,39648. End-to-End TestingFree lesson

Debugging Tests: UI Mode and Trace Viewer

Use Playwright's UI mode for step-through debugging and trace viewer to inspect failed test runs with screenshots and logs.

Debugging Tests: UI Mode and Trace Viewer

You'll learn how to debug failing Playwright tests using two powerful built-in tools: UI mode for interactive step-through debugging and trace viewer for post-mortem analysis.

Why Debugging E2E Tests Is Different

When an E2E test fails, you need to see what the browser actually did. Console logs aren't enough—you need visual feedback, network activity, and the ability to replay what happened. Playwright provides two specialized debugging tools for exactly this.

UI Mode: Interactive Step-Through Debugging

UI mode launches a graphical interface where you can step through your test line-by-line, watching the browser react in real-time. It's like having a debugger attached to both your test code and the live application.

Run UI mode with:

npx playwright test --ui

You'll see a split view: your test code on one side, the browser on the other. Click through each action, inspect locators, and see exactly where things go wrong. You can even watch selectors highlight as Playwright searches for them—invaluable when a locator fails to find anything.

Trace Viewer: Post-Mortem Investigation

The trace viewer lets you record and replay entire test runs with full context: screenshots at every step, network logs, console output, and DOM snapshots. Think of it like a flight recorder for your tests.

Enable traces in playwright.config.js:

use: {
  trace: 'on-first-retry', // or 'on' for all tests
}

When a test fails, Playwright generates a trace file. View it with:

npx playwright show-trace trace.zip

You'll see a timeline of every action, complete with before/after screenshots and the ability to inspect the DOM at any moment—perfect for debugging CI failures you can't reproduce locally.

Key Takeaway: Use UI mode (--ui) for interactive debugging during development, and trace viewer (show-trace) to investigate failures after they happen, especially in CI environments where you can't watch tests run live.