UI Mode - Playwright

Overview

Playwright UI Mode is an interactive test runner that combines the power of watch mode, the Inspector, and the Trace Viewer into a single experience. It’s designed for test development and debugging with live updates as you edit your code.

Starting UI Mode

Basic Command

npx playwright test --ui

This launches the UI Mode interface in a desktop application window (using Playwright’s own browsers).

Open in Browser Tab

Instead of a desktop window, open UI Mode in your default browser:

npx playwright test --ui-host=127.0.0.1
npx playwright test --ui-host=0.0.0.0 --ui-port=9323

Specifying a host or port opens the UI in a browser tab, making it easier to share with team members or use on remote machines.

Port Configuration

npx playwright test --ui-port=9323
npx playwright test --ui-port=0  # Use any free port

UI Mode Interface

The UI Mode window is divided into several panels:

Test Explorer

Left sidebar showing:

All test files in your project
Test hierarchy (describe blocks, test cases)
Test status indicators:
- ✅ Passed
- ❌ Failed
- ⏭️ Skipped
- 🔄 Running

Click any test to:

Run it individually
View its trace
See test code

Filter Bar

Top section with controls:

Project Filter

Select which projects to run (Chromium, Firefox, WebKit)

Status Filter

Show only passed, failed, or skipped tests

Text Search

Filter tests by name or file path

Running Tests

Run All Tests

Click the “Run All” button or press Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac).

Run Single Test

example.spec.ts

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

test('example test', async ({ page }) => {
  await page.goto('https://example.com');
  await expect(page.locator('h1')).toHaveText('Example Domain');
});

Click the play button next to the test name to run only that test.

Run Test File

Click the play button next to a file name to run all tests in that file.

Run by Project

Run tests only in specific browsers:

Use project filter dropdown
Select Chromium, Firefox, or WebKit
Run tests

Time Travel Debugging

One of UI Mode’s most powerful features:

How It Works

Run a test in UI Mode
Click any action in the timeline
See the exact state of the page at that moment
Hover over elements to inspect them
Copy locators from the DOM

Debugging Failed Tests

test('failing test example', async ({ page }) => {
  await page.goto('https://example.com');
  await page.click('button.submit');
  
  // This assertion fails
  await expect(page.locator('.result')).toHaveText('Success');
});

In UI Mode:

Test fails and stops at the assertion
Click on the failed action
See the screenshot showing what was actually displayed
Check the Console tab for errors
Inspect the Network tab for failed requests
Copy the correct locator

Live Trace View

UI Mode records traces automatically:

Run Test

Execute any test in UI Mode

Click Action

Click any action in the timeline

Explore State

View DOM snapshots, screenshots, network, and console

Pick Locators

Use Pick Locator tool to generate selectors

Unlike the Trace Viewer which analyzes saved traces, UI Mode provides live trace viewing as tests run.

Pick Locator Tool

Build selectors interactively:

Click “Pick Locator” button
Hover over elements in the page snapshot
Click an element

UI Mode generates the best locator:

page.getByRole('button', { name: 'Submit' })
page.getByText('Welcome')
page.getByTestId('user-menu')

Copy and paste into your test

Watch Mode

UI Mode watches for changes:

What Triggers Re-runs

Saving test files (.spec.ts, .spec.js)
Saving helper files imported by tests
Changes to page objects or fixtures

What Doesn’t Trigger Re-runs

Config file changes (restart UI Mode)
Installing new dependencies
Changes to unrelated files

Customizing Watch Behavior

playwright.config.ts

import { defineConfig } from '@playwright/test';

export default defineConfig({
  // Run tests in parallel in UI mode
  workers: process.env.CI ? 1 : 2,
  
  use: {
    // Collect traces in UI mode
    trace: 'on',
  },
});

Keyboard Shortcuts

Shortcut	Action
`Ctrl/Cmd+Shift+R`	Run all tests
`Ctrl/Cmd+R`	Re-run last test
`Ctrl/Cmd+F`	Focus search box
`Ctrl/Cmd+Shift+C`	Pick locator
`Esc`	Stop running tests
`F5`	Reload UI Mode

UI Mode Features

Multiple Projects

Run tests across browsers:

playwright.config.ts

export default defineConfig({
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
    { name: 'Mobile Chrome', use: { ...devices['Pixel 5'] } },
  ],
});

In UI Mode:

See tests grouped by project
Run all projects or select specific ones
Compare results across browsers

Error Messages

When tests fail, UI Mode displays:

Full error stack trace
Expected vs actual values
Diff viewer for complex objects
Link to source code line

Console Output

View all console messages:

test('console example', async ({ page }) => {
  page.on('console', msg => console.log(msg.text()));
  
  await page.goto('https://example.com');
  
  await page.evaluate(() => {
    console.log('Page loaded');
    console.error('This appears in UI Mode');
  });
});

Console tab shows:

All console.* calls from the browser
Test runner logs
Uncaught exceptions

Network Panel

Inspect all network activity:

XHR/Fetch requests
Resource loads (images, CSS, JS)
API calls
WebSocket connections

Click any request to see:

Request URL and method
Request/response headers
Response body
Timing information

Using UI Mode for Development

TDD Workflow

new-feature.spec.ts

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

test('new feature', async ({ page }) => {
  // 1. Start UI Mode: npx playwright test --ui
  
  // 2. Write test (it fails)
  await page.goto('https://example.com/feature');
  await page.click('button.new-feature');
  await expect(page.locator('.result')).toBeVisible();
  
  // 3. See failure in UI Mode
  // 4. Fix application code
  // 5. Test re-runs automatically
  // 6. Repeat until passing
});

Debugging Flaky Tests

# Run the same test multiple times
npx playwright test flaky.spec.ts --ui --repeat-each=10

In UI Mode:

Watch tests run repeatedly
See which attempts fail
Compare traces between passing and failing runs
Identify timing issues or race conditions

UI Mode vs Other Tools

UI Mode
Inspector
Trace Viewer

Best for:

Active test development
Quick feedback loops
Comparing browser behaviors
Watch mode workflows

Features:

Live updates on file save
Run specific tests easily
Multi-project visualization

Command Line Options

From /home/daytona/workspace/source/packages/playwright/src/program.ts:435, UI Mode supports:

# Basic UI mode
npx playwright test --ui

# Open in browser with specific host
npx playwright test --ui-host=127.0.0.1

# Custom port (0 for any free port)
npx playwright test --ui-port=9323

# Combine with other test options
npx playwright test --ui --project=chromium --headed

# Run specific tests in UI mode
npx playwright test example.spec.ts --ui

# Use with grep
npx playwright test --ui -g "login"

Remote UI Mode

Run UI Mode on a remote server:

# On remote machine
npx playwright test --ui-host=0.0.0.0 --ui-port=9323

# Access from local machine
open http://remote-machine:9323

Be cautious when exposing UI Mode on a public network. Use SSH tunneling or VPN for secure access.

SSH Tunnel Example

# Local machine: Create tunnel
ssh -L 9323:localhost:9323 user@remote-machine

# Remote machine: Start UI Mode
npx playwright test --ui-host=127.0.0.1 --ui-port=9323

# Local machine: Access UI Mode
open http://localhost:9323

Tips and Tricks

Use Tags

Add @slow or @smoke tags to filter tests quickly

Multiple Windows

Open multiple UI Mode instances for different test suites

Headed Mode

Add --headed to see actual browser windows alongside UI Mode

Save Traces

Click “Export” to save traces for later analysis

Getting Started

Core Concepts

Test Runner

Guides

Tools

Advanced

​Overview

​Starting UI Mode

​Basic Command

​Open in Browser Tab

​Port Configuration

​UI Mode Interface

​Test Explorer

​Filter Bar

Project Filter

Status Filter

Text Search

Tags

​Action Timeline

​Watch Mode

​Running Tests

​Run All Tests

​Run Single Test

​Run Test File

​Run by Project

​Time Travel Debugging

​How It Works

​Debugging Failed Tests

​Live Trace View

​Pick Locator Tool

​Watch Mode

​What Triggers Re-runs

​What Doesn’t Trigger Re-runs

​Customizing Watch Behavior

​Keyboard Shortcuts

​UI Mode Features

​Multiple Projects

​Error Messages

​Console Output

​Network Panel

​Using UI Mode for Development

​TDD Workflow

​Debugging Flaky Tests

​UI Mode vs Other Tools

​Command Line Options

​Remote UI Mode

​SSH Tunnel Example

​Tips and Tricks

Use Tags

Multiple Windows

Headed Mode

Save Traces

​See Also

Build docs developers (and LLMs) love

Overview

Starting UI Mode

Basic Command

Open in Browser Tab

Port Configuration

UI Mode Interface

Test Explorer

Filter Bar

Action Timeline

Watch Mode

Running Tests

Run All Tests

Run Single Test

Run Test File

Run by Project

Time Travel Debugging

How It Works

Debugging Failed Tests

Live Trace View

Pick Locator Tool

Watch Mode

What Triggers Re-runs

What Doesn’t Trigger Re-runs

Customizing Watch Behavior

Keyboard Shortcuts

UI Mode Features

Multiple Projects

Error Messages

Console Output

Network Panel

Using UI Mode for Development

TDD Workflow

Debugging Flaky Tests

UI Mode vs Other Tools

Command Line Options

Remote UI Mode

SSH Tunnel Example

Tips and Tricks

See Also