Playwright Debugging Tools

This chapter introduces Playwright's three major debugging tools: UI Mode, Trace Viewer, and the command-line Debug mode.

Full Introduction to UI Mode

UI Mode is Playwright's built-in graphical test interface, providinga one-stop experience for exploring, running, and debugging tests.

Launching UI Mode

npx playwright test --ui

Browsing the Test List

After launching, the left sidebar shows all test files.

You can expand each file anddescribeblock to run, view, watch, or debug each test individually.

Watch Mode

After clicking the Watch button, Playwright listens for file changes and automatically re-runs affected tests once the test code or source code is updated.

Timeline View

After test execution, a timeline view appears at the top, marking navigation and actions with different colors.

You can hover to view snapshots of each step, or double-click to select a time period and view its detailed logs.

DOM Snapshot

Clicking a step in the timeline displays the DOM snapshot of that moment on the right.

You can see the actual state of the page before and after the action, quickly identifying issues.

Test Filtering

UI Mode supports multiple filtering methods:

  • Search by test name to
  • press
    @tag
    filter
  • Filter by project
  • Filter by status: passed, failed, skipped

In-depth Debugging with Trace Viewer

Trace Viewer is Playwright's recording and playback tool, allowing you toinspect every step of a test just like debugging a recording.。

Configuring Trace Collection

Example

// File path: playwright.config.ts
export default defineConfig({
  use: {
    // Only collect Trace when retrying after a failure
    trace: 'on-first-retry',

    // Optional values:
    // 'off' —— Do not collect
    // 'on' —— Collect every time
    // 'on-first-retry' —— Only collect on the first retry (recommended)
    // 'retain-on-failure' —— Only retain Trace on failure
  },
});

Opening a Trace

# 本地打开
npx playwright show-trace path/to/trace.zip

You can also upload it totrace.playwright.devfor online viewing.

Information Contained in a Trace

ContentDescription
DOM SnapshotComplete page DOM snapshots before and after each step executes
Network RequestsAll HTTP requests and responses (URL, status code, header, body)
Console LogsAll messages output by the browser console
ScreenshotsPage screenshots for each step
Action LogCall arguments and execution time of all Playwright actions
Source CodeTest source code location corresponding to each action

Using Trace to Locate Failures

Find the failed step in the Trace Viewer timeline, inspect the DOM state and network requests of the page before and after that step, and identify the cause of the failure.

Trace is the most powerful debugging tool. When a test fails on CI but you cannot reproduce it locally, you can download the Trace file generated by CI to analyze the cause of the failure offline.

--debug Mode and page.pause()

--debug Command Line Mode

npx playwright test --debug

Features:

  • Automatically opens the Playwright Inspector window
  • Step through operations one by one
  • Debug in browser DevTools
  • Use
    F10
    (Step Over) and
    F11
    (Step Into) to control execution

page.pause() Pauses Execution

Example

// Set a breakpoint in the code
test('test for debugging', async ({ page }) => {
  await page.goto('https://www.example.com/');

  // Pause execution and open the Inspector
  await page.pause();

  // In the Inspector, you can step through subsequent actions
  await page.getByText('EXAMPLE Tutorial').click();
});

After usingpage.pause()to run the test, Playwright will automatically open the Inspector window, allowing you to inspect the page state step by step.

Choosing Among the Three Debugging Methods

MethodApplicable Scenario
UI ModeDaily development, browsing the test list, quickly checking test status
Trace ViewerLocating CI failures, analyzing every step of complex tests
--debug / page.pause()Developing new tests, debugging specific steps in depth
Other Extensions