Debugging with UI mode, codegen and inspector

Use UI mode for time-travel debugging, codegen to scaffold selectors, and the inspector to step through a test as it runs.

UI mode

npx playwright test --ui

# in UI mode:
# - pick a test and watch it run with a timeline
# - hover a step to see the DOM snapshot at that moment
# - open the source, the console and the network for that step
# - toggle "watch" and re-run on every file save
# - click the locator picker to test a selector against the live page

• UI mode keeps a DOM snapshot per step, so you can see the page as it was when the step failed, not as it looks now.
• The console and network panels are scoped to the selected step, which points straight at the failing request.
• The locator picker tells you whether a selector is unique before you commit it to a test - the fastest fix for a strict-mode violation.
• Watch mode turns a failing suite into a tight edit-run loop without leaving the browser.

Codegen and the inspector

# scaffold a test by using the app
npx playwright codegen https://staging.example.com

# start from a saved session so you are already logged in
npx playwright codegen --load-storage=playwright/.auth/user.json https://staging.example.com

# emulate a device while recording
npx playwright codegen --device="iPhone 15" https://staging.example.com

# record against a local file
npx playwright codegen ./fixtures/page.html

# step through an existing test
npx playwright test invoices.spec.ts --debug

# or pause at a specific point from inside the test
# await page.pause();

Codegen produces working code, not good code. Its selectors are whatever was stable at the moment you clicked, and they are often weaker than a role-based locator you would have written deliberately. Use it to get the shape of the flow, then rewrite the locators.

A debugging routine

1. Reproduce with --headed first. If a visible browser passes, you have an environment difference, not a logic bug.
2. Open UI mode and select the failing step. Read the DOM snapshot before touching the test.
3. Check the network panel for that step. A missing response explains most timeouts.
4. Try the locator in the picker. A strict-mode violation is usually a selector that matches more than you thought.
5. Add a trace on failure and keep it as an artefact, so the next person has the same information you have.
6. Only after all of that, adjust the wait or the selector and re-run in a loop to confirm the fix holds.

// playwright.config.ts
use: {
  trace: "on-first-retry",       // full trace the second time a test fails
  screenshot: "only-on-failure",
  video: "retain-on-failure",
},

// for a stubborn test, capture everything for one run
// npx playwright test checkout.spec.ts --trace on

npx playwright show-trace test-results/checkout-*/trace.zip

# loop until it fails, then keep the artefacts
for i in $(seq 1 15); do npx playwright test checkout.spec.ts --retries=0 || break; done

FAQ

Related

Auto-waiting, timeouts and flakiness Visual comparisons, screenshots and video

Last refreshed 2026-09-18.