Software teams are shipping updates faster than ever right now, and ensuring nothing breaks is a daily struggle. When an end-to-end test fails in a Continuous Integration (CI) pipeline, figuring out exactly what went wrong in a sea of headless text logs can waste hours of precious engineering time.

If you are tired of staring at cryptic TimeoutError messages and wondering why a button was not clicked, you need a better approach.

This is where Playwright's interactive visual runner comes in. This comprehensive guide will show you exactly how Playwright UI mode provides a powerful visual time-travel window to walk through your test execution step by step. You will learn how to leverage its live DOM snapshots, network intercepts, and action timelines to fix flaky tests in seconds, making your debugging workflow incredibly fast and efficient.

What is Playwright UI mode?

When engineers ask what is Playwright UI mode, they are usually looking for a better way to visualize test execution without relying on console logs. Think of it as a complete command center for your entire test automation workflow. It allows you to observe every single action your test takes inside a real browser window, capturing the exact state of the DOM at every millisecond.

Instead of reading a long stack trace to figure out why an element was hidden, you get to see exactly what the user would see. You can inspect the Document Object Model at the exact moment a failure occurs, dramatically reducing the time spent guessing why a specific element was not found.

Many teams struggle with flaky tests because they cannot see the network state during a run. This interactive runner captures all network requests and console logs automatically. You do not need to write extra code or complex configurations to enable these features, it hooks directly into the Chrome DevTools Protocol (CDP) to gather massive amounts of debugging data with almost zero performance penalty.

Why engineers need Playwright UI mode

Relying solely on terminal outputs for E2E testing is a massive bottleneck. You need a faster way to understand why a dynamic React component didn't render or why a GraphQL mutation timed out. This visual approach removes the friction from the troubleshooting process entirely.

One major benefit is the ability to isolate specific test files instantly. You can filter your test tree and only execute the exact describe block you are actively working on. This targeted approach saves computing resources and tightens your feedback loop.

Tip: Use the built-in search bar in the test explorer to filter by @tags. If you tag tests with @auth or @checkout, typing @auth instantly scopes the UI runner down to just those critical paths.

Another huge advantage is the live Watch Mode. When you edit your TypeScript or JavaScript test files, the runner instantly detects the change and triggers a rerun automatically. You can check your browser compatibility on the fly without restarting the Node process.

Context switching is a known productivity killer. By keeping the code execution, the browser rendering, and the network logs in one unified dashboard, cognitive load is heavily reduced. Furthermore, it simplifies the onboarding process for junior developers. Visual tools are universally easier to grasp than dense command line outputs, making UI mode an invaluable teaching tool for teams scaling their software quality initiatives.

Prerequisites

npm init playwright@latest

# Launch the interactive UI mode for the entire test suite
npx playwright test --ui

# Target a specific test file
npx playwright test tests/authentication.spec.ts --ui

# Target a specific line number within a file
npx playwright test tests/checkout.spec.ts:42 --ui

# Run only Chromium tests in UI mode
npx playwright test --project=chromium --ui

The Attachments tab is particularly useful for visual regression testing. If your test captures screenshots, they appear here neatly organized by step, preventing your local directory from getting cluttered.

Using the locator picker

One of the most powerful features inside the visual runner is the Locator Picker. It eliminates the guesswork of writing CSS selectors or XPath queries by hand.

Click the crosshair icon (Pick Locator button) in the toolbar and hover over any element on the rendered page. The runner instantly generates the recommended Playwright locator for that element. It prioritizes the most resilient strategies in this order:

• Role-based - page.getByRole('button', { name: 'Submit' })
• Label-based - page.getByLabel('Email')
• Test ID - page.getByTestId('login-form')
• Text-based - page.getByText('Welcome back')

This priority order ensures your locators do not break when developers change CSS classes or restructure HTML. You can copy the generated locator directly from the UI and paste it into your test file. Combined with watch mode, your test reruns immediately with the new selector.

The locator picker also highlights all matching elements on screen. If your selector accidentally matches three buttons instead of one, you will see it immediately. This prevents false-positive test passes caused by overly broad selectors, a common source of flaky tests that teams struggle with.

Playwright UI mode vs trace viewer

Many engineers get confused when comparing Playwright UI mode vs trace viewer. While they share an identical visual interface, they serve completely different purposes in the development lifecycle.

Trace Viewer is a static, post-mortem report generated after a test completes, usually in a CI pipeline. When a test fails on GitHub Actions, you download the trace.zip file, open it in the trace viewer, and analyze the historical data.

Playwright UI Mode is a live, dynamic environment for active local development. You can edit code, click play, and watch the test execute in real time. You cannot run new tests or watch for file changes from within a static trace report.

A clear side by side infographic comparing live execution versus static reporting tools

If you want to write or debug tests locally, the interactive mode is the clear winner. If you need to figure out why a test failed on a remote build server, you use the trace viewer instead. Both are essential for maintaining a high test suite health.

Because they share the same underlying rendering engine, learning to navigate one tool automatically teaches you the other. This significantly lowers the learning curve for the whole team.

How to debug failing tests step by step

A three-step visual infographic showing how to debug tests using timeline scrubber, DOM snapshot, and network source

To effectively debug your application, you must master the timeline scrubber. When a test fails, the runner automatically highlights the exact step that caused the fatal error. Follow this proven workflow to resolve any failing test quickly:

1. Locate the Error: Find the red failing step in the action list on the left side panel.
2. Inspect the DOM: Click the step to reveal the exact DOM state at the time of the failure. Use the locator playground (the pick locator button) to test new selectors directly on the live screen.
3. Check the Network: Open the Network tab to check for failed 500 API responses or pending requests that caused a timeout.
4. Verify the Source: Open the Source tab to see which exact line of code threw the error message.

Here is a realistic example of using the page.pause() method to halt execution right before a tricky assertion. This acts like a traditional debugger breakpoint:

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

test('should display error on invalid login', async ({ page }) => {
  await page.goto('/login');

  await page.getByRole('textbox', { name: 'Email' }).fill('[email protected]');
  await page.getByRole('textbox', { name: 'Password' }).fill('badpass');
  await page.getByRole('button', { name: 'Submit' }).click();

  // The runner will pause here, allowing you to manually inspect
  // the DOM and Network state before the assertion fires
  await page.pause();
  await expect(page.getByText('Invalid credentials')).toBeVisible();
});

This technique allows engineers to inspect complex state changes that happen too fast to observe normally. You can then step through the remaining actions manually using the toolbar controls. It is also worth noting that VS Code users can achieve a similar breakpoint experience using the official Playwright Test Extension, which integrates directly with the editor's built-in debugger.

Advanced network and console debugging

Infographic demonstrating how to use the Network, Console, and Source tabs to triage a failed test execution

Modern Single Page Applications rely heavily on asynchronous data loading. When a test fails, the root cause is frequently a slow backend API call, not a broken UI component. The built-in network panel is designed specifically to expose these hidden communication errors.

As you scroll through the timeline, the Network panel filters requests to match that exact moment. You can click on any specific request to view its Headers, Payload, and Response Body. This eliminates the need to add messy console.log statements throughout your application code.

If your test is timing out, sort the network traffic by duration or filter by Fetch/XHR to quickly find the specific API call that is hanging. This is especially useful for diagnosing ai codegen scenarios where generated tests rely on dynamic backend data.

Similarly, if your React or Vue application throws a JavaScript exception, it will immediately appear in the Console tab. You can view warnings, errors, and standard log outputs just like in Chrome DevTools. This tight integration prevents you from constantly switching between different debugging applications.

You can also verify whether a specific mock route was actually intercepted during test execution. This ensures your tests are using isolated data and that external dependencies are not causing unpredictable behavior in your suite.

Optimizing your local test runs

Speed is critical when working with a large test suite locally. You do not want to wait several minutes just to verify a minor CSS selector change.

Utilizing the Watch feature correctly is the single best way to maintain developer momentum. Click the eye icon next to a specific test file to enable watch mode. Now, every time you press save in your code editor, only that specific file will rerun automatically.

Pro Tip: Use the built-in tag filtering feature to run only a subset of tests, such as @smoke or @regression, directly from the visual dashboard. This keeps your feedback loop under five seconds.

If your test suite is growing too large, you might need to start sharding tests. While sharding is mostly used in CI environments, keeping your local runs lean is equally important. Always ensure you are only running the tests relevant to your current feature branch.

Another tip is to group your tests logically using test.describe blocks. The visual tree nests these blocks, making it easier to collapse and expand sections. This keeps the interface clean even when dealing with hundreds of assertions.

You can also integrate this efficient workflow with a custom github action. This ensures the exact tests you perfected locally behave the same way in your CI pipeline. Aligning local and remote execution environments is the key to preventing unexpected failures.

Common troubleshooting tips

Even experienced engineers run into unexpected issues with the visual runner. Here are the most common problems and how to fix them:

UI mode window is blank or does not launch:

This usually means your Playwright version is below 1.32. Run npx playwright --version to check. Upgrade with npm install -D @playwright/test@latest and re-install browser binaries using npx playwright install.

Network tab is not showing any requests:

The network panel only captures traffic that occurs during test execution. If you are viewing a step that happens before any navigation (like a test.beforeEach hook), the panel will appear empty. Scrub the timeline forward to a step where network activity occurs.

Tests pass in terminal but fail in UI mode:

This can happen when your playwright.config.ts has different settings for headed versus headless execution. Ensure your use.headless and timeout values are consistent across both modes. Also check that any global setup scripts (like authentication state) are completing before the test suite starts.

Locator picker does not highlight elements:

Make sure the DOM snapshot is fully loaded before using the picker. If the page relies on lazy-loaded content, scrub the timeline to a later point where the element has rendered.

Conclusion

Mastering Playwright UI mode will fundamentally change how you approach test debugging. It removes the frustration of headless terminal logs and replaces it with clear, visual, actionable feedback. By utilizing time-travel debugging, the locator picker, network inspection, and live watch features, you solve complex issues in a fraction of the time.

Start running your suite with the --ui flag today. Your entire team will benefit from faster bug resolutions and much more reliable code deployments. You can calculate your potential time savings by checking out your ci budget metrics online today.

Frequently asked questions