Playwright UI Mode: Step-by-Step Browser Testing

Playwright UI Mode is a built-in graphical interface that turns your Playwright tests into an interactive, visual debugging and exploration tool. Instead of running tests headlessly and reading terminal output, you can watch tests execute in a real browser, inspect the page at each step, and edit tests live. This guide walks you through setting it up and using it effectively.

What You’ll Need

• Node.js (version 16 or later) installed on your machine.
• A project with Playwright installed. If you don’t have one, run npm init playwright@latest in an empty folder to create a basic setup.
• A basic test file (e.g., tests/example.spec.js) that you can run. The default Playwright scaffold includes one.

Step-by-Step

1. Open the UI Mode. In your terminal, navigate to your project root and run npx playwright test --ui. This launches the UI Mode window. If you have a custom test directory, Playwright will find it automatically.
2. Choose your tests. The left sidebar lists all your test files. Click a file to see its individual tests. Check the box next to a test to select it, or check the file box to select all tests in that file.
3. Run the selected tests. Click the green “Run” button (a play icon) at the top of the sidebar. The tests will execute in a real browser window, and you’ll see each step appear in the “Timeline” panel on the right.
4. Watch the execution. As the test runs, the browser window shows exactly what’s happening. The timeline highlights each action (click, fill, navigation) with a timestamp. You can slow down execution using the “Slow” slider to see each step more clearly.
5. Inspect any step. Click on a step in the timeline. The browser window will show the page state at that exact moment. The “Actions” panel below the timeline lists the page snapshot, accessibility snapshot, and console logs for that step.
6. Use the picker to debug. Click the “Pick locator” button (crosshair icon) in the top toolbar, then click on an element in the browser window. Playwright will generate a locator for that element and show it in the “Locator” input. You can copy this locator into your test code.
7. Edit tests live. In the code editor panel (opened by clicking the file name in the sidebar), make changes to your test. Save the file, and the test will re-run automatically with your changes. This is great for tweaking selectors or adding assertions.
8. Use the watch mode. Toggle the “Watch” icon (eye) to automatically re-run tests whenever you save changes to any test file. This gives you instant feedback while writing tests.
9. Trace viewer integration. If a test fails, click on the failed step in the timeline to open the full trace viewer. This shows you network requests, console messages, and a full DOM snapshot to help diagnose the issue.
10. Filter and search. Use the search bar at the top of the sidebar to filter tests by name. You can also filter by status (passed, failed, skipped) using the dropdown next to the search bar.

Common Mistakes

• Forgetting to run in UI mode. Running npx playwright test without --ui runs headlessly. Always include --ui to see the browser.
• Not selecting tests. If you click “Run” without checking any test boxes, nothing runs. Make sure at least one test is selected.
• Editing tests without saving. In live edit mode, changes only take effect after you save the file. If you forget to save, the test will run the old version.
• Using the wrong browser. UI Mode defaults to the browser configured in your playwright.config.js. If you expect Chromium but see Firefox, check your config.
• Ignoring the console panel. The console output for each step is hidden in the “Actions” panel. If a test fails, check there for error messages before guessing.

Tips

• Use the timeline to spot timing issues. If a test passes but is slow, look at the timeline to see where delays occur. You can then add explicit waits or adjust selectors.
• Combine with the picker. The locator picker is the fastest way to get robust selectors. Use it to replace brittle XPaths or CSS selectors.
• Take screenshots at key steps. In your test code, add await page.screenshot({ path: 'step.png' }) at important points. These appear in the timeline and help you compare states.
• Use the “Watch” mode for TDD. Write a failing test, then implement the feature. The test will re-run automatically and turn green when you’re done.
• Keep the browser window visible. If you minimize or hide the browser window, some steps may be skipped to save resources. Keep it visible for accurate timing.

Troubleshooting

• UI Mode doesn’t open. Make sure you’re in the correct project directory and that Playwright is installed. Try npx playwright install to ensure browsers are downloaded.
• Tests run headlessly despite --ui. Check your playwright.config.js for a headless: true option. In UI Mode, Playwright forces headed mode, but if you have a custom config that overrides it, you may need to set headless: false.
• No tests appear in the sidebar. Ensure your test files are in the directory specified in the config (default is tests/). Also check that files match the pattern *.spec.js or *.test.js.
• Browser closes immediately after test. This is normal if the test finishes. To keep it open, add a await page.pause() at the end of your test, or use the “Pause” button in UI Mode.
• Live editing doesn’t trigger re-run. Make sure the file is saved. Also, the “Watch” mode must be enabled; otherwise, you need to click “Run” again manually.

Frequently Asked Questions

Can I use UI Mode with multiple browsers?

Yes. UI Mode respects the projects configuration in your playwright.config.js. You can select which browser to run from the dropdown in the top toolbar.

How do I debug a specific test without running the whole suite?

In the sidebar, check only the test you want to run, then click “Run”. You can also right-click a test and choose “Run” from the context menu.

Is UI Mode available for all Playwright languages?

UI Mode is currently available for JavaScript/TypeScript projects. For Python, Java, or .NET, you can use the Trace Viewer for similar debugging.

Can I use UI Mode in CI/CD?

UI Mode is designed for local development. In CI, you should run tests headlessly with npx playwright test. You can still generate traces for debugging.

How do I save a trace from UI Mode?

After a test run, click the “Trace” button in the top toolbar. This opens the trace viewer. You can then export the trace as a .zip file for sharing.

Why is my test slower in UI Mode?

UI Mode adds overhead for visualization and step recording. This is normal. Use the “Slow” slider to slow down, or disable it for faster runs.

Related

• How Images Infect Computers on Social Media
• How to Make a Windows 11 Laptop Battery Last Longer
• Install VirtualBox on a USB Drive: Full Guide