Before UI Mode, debugging Playwright meant a loop of console.log, --headed, re-running, and opening trace files by hand. UI Mode combines all of it into one interactive window that the Playwright team recommends right on the installation page of the docs.
What Is Playwright UI Mode?
UI Mode is an interactive test runner built into Playwright Test. It lists every test in your project, runs any of them on demand, and records a full trace of each run so you can “time travel” through it.
| Tool | When to use it |
|---|---|
UI Mode (--ui) | Writing and debugging tests locally, with watch mode and time travel |
Headed mode (--headed) | Just watching the browser while tests run |
Debug / Inspector (--debug) | Pausing and stepping through one test line by line |
| Trace Viewer | Analysing a recorded run after the fact — especially from CI |
The Playwright UI Mode Command
# open UI Mode for the whole project npx playwright test --ui # open it for one file or folder only npx playwright test tests/checkout --ui
A window opens with your tests in the sidebar. Nothing runs until you press a play button, so it is safe to open on large suites.
Tour of the UI Mode Interface
Sidebar and filters
Filter tests by name, by @tag, by project (chromium, firefox, webkit…) and by status: passed, failed or skipped. Expand a file to run a single test or a single describe block.
Timeline and actions
After a run, the timeline across the top shows each navigation and action, colour-coded. The Actions tab lists every step with its locator and duration, and hovering an action shows Before and After DOM snapshots. You can pop the snapshot out into its own window to compare side by side.
Pick locator
Click the pick-locator button, then click any element in the snapshot. UI Mode shows the locator Playwright recommends (usually getByRole) and lets you edit it to see what matches. This is the fastest way to build the stable locators described in our locators guide.
Detail tabs
| Tab | What it shows |
|---|---|
| Source | Highlights the line of code for the action you hover |
| Call | Action metadata: timing, locator, strict mode, keys pressed |
| Log | Everything Playwright did internally, e.g. waiting for the element to be visible |
| Errors | Error messages, with markers on the timeline |
| Console | Browser console output and console.log from your test |
| Network | Every request with headers, body, status, duration and size |
| Attachments | Screenshots and visual-comparison diffs with an image slider |
| Metadata | Browser, viewport, duration and other run details |
There is also an “Open in VS Code” button that jumps straight to the test source. If you prefer to stay in the editor, see our guide to the debugging options.
Watch Mode: Re-run on Save
Click the eye icon next to a test or file to watch it. Every time you save the test file, UI Mode re-runs it automatically. This gives you a tight edit-and-see loop while writing a new test — keep the window on one screen and your editor on the other.
Tip: watch only the test you are working on. Watching the entire suite re-runs everything on every save.
Debugging a Failing Test in UI Mode
- Filter the sidebar by Failed and run the failing test.
- Open the Errors tab and click the error marker on the timeline to jump to the failing action.
- Hover the actions just before it and compare the Before/After snapshots — is the element there? Is it covered by a modal or spinner?
- Check Network for a failed or slow API call — a common root cause of timeout errors.
- Use pick locator on the snapshot to confirm your locator matches exactly one element.
- Fix the test, save, and let watch mode confirm the fix.
Does UI Mode Work with Playwright Python?
UI Mode is part of the Node.js test runner, @playwright/test. The Python plugin, pytest-playwright, does not provide --ui. Python users get most of the same insight from traces:
# record a trace for each test pytest --tracing on # open a trace in the Trace Viewer playwright show-trace test-results/<test-folder>/trace.zip # step through a test with the Inspector PWDEBUG=1 pytest -s tests/test_login.py
See our Playwright Python tutorial for the full pytest setup.
Running UI Mode in Docker, WSL or a Remote Machine
By default UI Mode opens a local window. When your tests run inside a container or a remote machine, serve it over HTTP instead and open it in your browser:
# listen on all interfaces (random port) npx playwright test --ui-host=0.0.0.0 # fixed port, e.g. to map it from Docker npx playwright test --ui-port=8080 --ui-host=0.0.0.0
Binding to 0.0.0.0 exposes UI Mode to your network. Only do this on a trusted network or behind port forwarding.
Playwright UI Mode Not Working? Fixes
| Problem | Fix |
|---|---|
| UI Mode shows no tests | Check testDir and testMatch in playwright.config.ts; files must match (default: *.spec.ts / *.test.ts). Also clear the name, tag, project and status filters in the sidebar. |
| Some projects' tests missing | Open the Projects filter in the sidebar and make sure the project is checked. |
| Window does not open (WSL, Docker, SSH) | There is no display. Use --ui-host=0.0.0.0 (and --ui-port) and open the printed URL in your host browser. |
error: unknown option '--ui' | You are on a very old Playwright version, or running npx playwright from a project without @playwright/test. Update with npm i -D @playwright/test@latest. |
| Tests run but browsers fail to launch | Run npx playwright install (plus --with-deps on Linux). |
| Test file errors before listing | A syntax or import error stops discovery — run npx playwright test --list in the terminal to see the error. |
Frequently Asked Questions
What is the command to open Playwright UI Mode?
Run npx playwright test --ui. Add a file or folder path to open UI Mode for only part of your suite.
What is the difference between UI Mode and Trace Viewer?
UI Mode is an interactive runner: it runs tests, watches files and shows a live trace of each run. Trace Viewer opens a recorded trace.zip after the fact, which makes it the tool for analysing CI failures.
Can I use Playwright UI Mode in CI?
No — UI Mode is for local development. In CI, record traces with trace: 'on-first-retry' and open them in the Trace Viewer.
Why is Playwright UI Mode not showing my tests?
Usually testDir/testMatch do not match your files, a sidebar filter is active, the project is unchecked, or a syntax error stops discovery. Run npx playwright test --list to check.
Does Playwright UI Mode support Python?
Not directly. UI Mode belongs to the Node.js test runner. With pytest-playwright, use --tracing on and playwright show-trace, or PWDEBUG=1 for the Inspector.
Asim Noaman
Senior QA Automation Engineer & AI Testing Specialist
With years of hands-on experience building test automation frameworks for production applications, Asim specializes in combining traditional QA methodologies with cutting-edge AI tools. He has helped teams adopt Playwright and AI-driven testing workflows to ship faster with fewer bugs.
Complete Course
Debug Faster, Ship Stable Tests
The complete Udemy course covers UI Mode, Trace Viewer and debugging workflows hands-on — then shows how to let Claude AI write and fix tests for you.
- UI Mode and Trace Viewer in practice
- Locators that survive UI changes
- AI-assisted debugging with Claude
- Real-world projects