Running and Debugging Tests With Playwright UI Mode

Playwright UI Mode gives you a visual way to run, inspect, and debug tests without relying only on terminal output. It lets you see individual test steps, review execution details, inspect DOM snapshots, and rerun failed tests from one interface.

I find it especially useful when a test fails and I need to understand exactly where the flow broke. In this guide, I’ll show you how Playwright UI Mode works, how to launch and use it, and where it fits into a practical debugging workflow.

What Is Playwright UI Mode and How Does It Work?

Playwright UI Mode is an interactive test runner that lets you run and inspect tests through a visual interface instead of relying only on terminal output. It shows your test files, execution status, individual steps, timelines, locators, and page snapshots in one place.

I find it most useful when a failure is difficult to understand from logs alone. For example, if an element appears too late, changes during hydration, or disappears because of a quick DOM update, UI Mode makes it easier to see what happened during each step.

It also works with Playwright’s trace data, so you can inspect snapshots of the application at different points in the test. This helps when debugging flaky selectors, timing issues, transitions, or race conditions because you can review the state Playwright actually saw during execution.

How to Launch UI Mode

Playwright UI Mode is built into Playwright Test, so I do not need to install a separate tool or change the test configuration just to use it.

I can launch it with:

npx playwright test --ui

This opens the UI Mode interface and loads the available tests. From there, I can select individual tests, run or rerun them, inspect each step, and review the page state associated with the execution.

If I only want to debug a specific test file, I can pass its path with the command:

npx playwright test tests/login.spec.ts --ui

This is useful when I am working on one part of a larger test suite because it keeps the interface focused on the tests I actually need.

I can also combine UI Mode with other Playwright options when I need to narrow the run further, such as selecting a particular project or filtering tests by name.

Core Features of Playwright UI Mode

Once I open UI Mode, most of the debugging work happens within a few built-in views. Instead of jumping between terminal logs, screenshots, and test files, I can inspect the test flow from one interface.

• Timeline view: I can move through the test timeline and see snapshots for individual actions. This makes it easier to spot where a navigation, interaction, or delay started affecting the flow.
• Actions and DOM snapshots: The Actions tab shows the locator used for each action and how long it took. I can also compare the DOM before and after an action, which is particularly useful for debugging selectors and unexpected UI changes.
• Locator picker: If a selector is unreliable, I can pick an element directly from the DOM snapshot, test the generated locator, modify it, and copy it back into the test.
• Source and error inspection: UI Mode highlights the corresponding line of test code as I move through actions. When a test fails, the Errors tab shows the failure and the timeline marks where it occurred.
• Console and network logs: I can inspect browser and test console messages alongside network requests, including status codes, request details, response data, and timing. This helps when the problem is caused by an API request rather than the UI itself.
• Watch mode: I can mark individual tests for watch mode so they rerun automatically when I change the test. This is useful when I am actively fixing a failing flow and want quick feedback after each edit.

Together, these features make UI Mode useful for more than simply running tests visually. I can trace a failure from the test code to the browser state, locator, console output, or network request without rebuilding the sequence from logs alone.

How to Debug Tests

When a test fails, I use UI Mode to work backward from the failed step instead of rerunning the test and relying only on terminal logs. I can select the test, move through its timeline, and inspect the DOM snapshot, locator, source code, console output, and network activity around the point of failure.

For example, if a click fails because Playwright cannot find or interact with an element, I can select that action and check which locator was used and what the page looked like at that moment. Playwright also lets me use the locator picker to test and refine selectors directly against the captured page state.

If I need to stop a running test at a specific point and inspect the live page, I can add page.pause():

import { test, expect } from '@playwright/test';



test('submit a form', async ({ page }) => {

  await page.goto('https://example.com');



  await page.getByLabel('Email').fill('user@example.com');



  await page.pause();



  await page.getByRole('button', { name: 'Submit' }).click();

});

page.pause() stops execution at that line so I can inspect the application before allowing the remaining steps to continue. Playwright documents this as the supported way to pause a test for interactive debugging.

For code-level issues, I can also set breakpoints in VS Code and run the test in debug mode. This lets me inspect variables and step through the test code while watching the browser state.

I generally start with UI Mode for failed actions, selectors, and unexpected page states. If I need to inspect the test while it is actively running, I switch to page.pause() or the Playwright Inspector for more control over execution.

Major Limitations

Playwright UI Mode is useful for understanding why a test fails locally, but I would not treat it as a replacement for broader test execution. What passes in UI Mode can still behave differently once the same test runs in CI, another browser, or a different device environment.

• Local results may not match CI: Differences in operating systems, browser versions, machine resources, and execution speed can expose failures that do not appear during local debugging.
• Real device behavior is not fully covered: Device emulation can reproduce settings such as viewport size and user agent, but it cannot reproduce every hardware-specific behavior or interaction found on a physical device.
• Network conditions are difficult to reproduce completely: Local tests may not reflect cellular instability, regional latency, or other network variations that affect asynchronous flows.
• Performance depends on the host machine: CPU load, memory availability, and rendering performance can change test behavior. A powerful development machine may hide timing or performance issues that appear elsewhere.
• It is primarily a debugging interface: UI Mode is designed to make test development and investigation easier. Full validation still requires running the suite across the browsers, environments, and configurations your users depend on.

Best Practices for Faster and More Reliable Debugging

A structured debugging workflow makes failures easier to reproduce and keeps me from spending time on symptoms rather than the actual cause. These are the practices I find most useful:

• Use traces when you need deeper context: Traces give me snapshots, logs, network activity, and action details that I can revisit after a run. They are especially useful for intermittent or timing-related failures.
• Rely on auto-waiting instead of fixed delays: I avoid hard-coded waits such as waitForTimeout() wherever possible. Playwright already waits for elements to become actionable, which keeps tests faster and reduces timing-related flakiness.
• Check locators early: I review selectors while writing the test instead of waiting for failures to appear later. Role-based, label-based, and other user-facing locators are usually more stable than selectors tied to dynamic classes or DOM structure.
• Limit the scope of each debugging session: Rather than loading an entire suite, I run the specific file or test I am investigating. This keeps the interface easier to follow and makes failures quicker to reproduce.
• Break complex flows into clear steps: For longer journeys such as login, checkout, or account setup, I inspect the flow stage by stage. This makes it easier to identify the exact action or transition where behavior starts to differ from what I expect.

Conclusion

Playwright UI Mode makes test debugging more visual and easier to follow. Instead of relying only on terminal output, I can inspect test steps, page snapshots, locators, console messages, and network activity to understand where a failure starts.

It works especially well during local development when I need to reproduce flaky behavior or investigate timing and selector issues. Once the problem is fixed, I still validate the test across the browsers and environments that matter so the result is not limited to a single local setup.