Debug Playwright Tests with UI Mode, Inspector, and Live Locators

Interactive debugging is most useful after the failing scenario has been narrowed to one test, one project, and one questionable transition. Opening an entire suite in headed mode and clicking around creates activity, not evidence. Playwright UI Mode, the Inspector, and live locator tools each answer a different question, and a disciplined session moves between them deliberately.

UI Mode is the workbench for selecting and rerunning tests while reviewing a recorded timeline. The Inspector is the live execution control for pausing before an action and reading actionability. Codegen and the locator picker are probes for discovering how the current page can be addressed. None of them removes the need to understand the state the product should have reached.

Match the debugging surface to the unknown

Start with Playwright UI Mode when you do not yet know where the journey diverged. Its test tree, status filters, project filters, action timeline, DOM snapshots, network records, and console output help bound the failure. Start with the Inspector when the suspicious line is already known and you need a live page at that point.

Use the locator picker when the element is present but the existing locator is ambiguous, brittle, or unexpectedly absent. Use codegen to observe a short interaction against a representative page, not to design the whole test architecture. This division prevents a selector experiment from distracting from a data, navigation, or authorization defect.

Launch the smallest reproducible run

Use a file, title expression, project, or source line to reduce startup and remove unrelated state. Keep the command in the terminal history so every experiment reruns the same target.

npx playwright test tests/checkout/approval.spec.ts --ui --project=chromium
npx playwright test tests/checkout/approval.spec.ts:47 --debug --project=chromium
npx playwright test --debug --grep "approver publishes release"

Before interpreting a local result, align environment variables, base URL, storage state, feature flags, and test data with the failed run. A test that passes against a developer database does not invalidate a CI failure against seeded data. If project dependencies create authentication or state, note that UI Mode does not automatically account for running setup dependencies; run the required setup project before the dependent test.

Use UI Mode to locate the first divergence

Filter by failed status or test name, select the correct project, and run only the target. In the timeline, hover across actions and find the last point where the page still matches the intended journey. Double-clicking an action narrows the time range and filters associated console and network records, which is more useful than reading every message from the test.

Compare Before and After snapshots around the suspect action. If a Save click occurs but no request follows, focus on the UI event and client validation. If the request succeeds but the page remains unchanged, inspect the response, browser console, and rendering state. If the action itself waits, open its log to see whether Playwright is resolving, scrolling, or waiting for visibility, stability, enabled state, or unobstructed input.

Watch mode is valuable after a small code change because it shortens the edit-rerun loop. Still, periodically execute a clean run. A repeatedly watched process can retain application development state that a fresh CI worker will not have.

Pause at the transition, not at test startup

page.pause() opens the Inspector at the point where understanding matters. Place it immediately before the suspicious action, run in debug mode, and remove it after the investigation. A breakpoint at the first line often wastes time stepping through stable setup.

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

test('approver publishes a release', async ({ page }) => {
  await page.goto('/releases/1842');
  await expect(page.getByRole('heading', { name: 'Release 1842' })).toBeVisible();

  await page.pause();

  const publish = page.getByRole('button', { name: 'Publish' });
  await expect(publish).toBeEnabled();
  await publish.click();
  await expect(page.getByRole('status')).toHaveText('Published');
});

While paused, inspect the page state before modifying the test. Confirm identity, URL, dialogs, loading indicators, and the business data that should enable the action. A locator failure is often the first visible sign that setup reached a different screen.

Read actionability logs as a state diagnosis

When the Inspector pauses on a click, its log explains what Playwright has checked. "Waiting for element to be stable" points toward motion or repeated rendering. "Intercepts pointer events" points toward an overlay or sticky element. Multiple resolved nodes point toward strictness and locator scope. A disabled element indicates missing product readiness, not a reason to call force.

Follow the failed condition into the product. If an overlay should disappear after a request, inspect that request and the state controlling the overlay. If the target re-renders while Playwright waits for stability, identify the animation or subscription causing churn. Raising the timeout only expands the observation window; it does not repair the missing readiness signal.

Actionability also protects realism. Forcing an action can make a test perform input a user cannot perform. Use it only when bypassing actionability is itself the explicit scenario, and document why the user-facing constraint does not apply.

Experiment with live locators without weakening intent

The Inspector's locator field highlights matches as you edit. Start with the user-facing contract: role and accessible name, label, placeholder, visible text, or an intentional test id. Scope to a stable parent when a page has repeated controls.

const releaseRow = page
  .getByRole('row')
  .filter({ has: page.getByRole('cell', { name: 'Release 1842' }) });

await expect(releaseRow).toHaveCount(1);
await releaseRow.getByRole('button', { name: 'Review' }).click();

The explicit count turns uniqueness into an assertion rather than relying on .first(). A positional escape can hide duplicate content, wrong sorting, or an unexpected modal. If a generated locator contains a long CSS chain, ask which stable product concept it is trying to express and encode that concept directly.

Test the locator in relevant states: loading complete, empty data, repeated rows, alternate locale, and each supported project where markup differs. A locator that highlights one element in a single paused page is a candidate, not proof of durability.

Use codegen as an observation tool

Codegen can record actions and propose locators based on the rendered page. It is useful when learning an unfamiliar flow or checking how Playwright sees an element. Keep the recording short, begin from controlled state, and stop once the uncertain interaction is captured.

Generated code does not know your domain fixtures, data ownership, assertion strategy, or reuse boundaries. Refactor the result into the existing suite, replace incidental text with stable semantics where appropriate, and add assertions that prove the business outcome. Delete generated waits or navigation that duplicate fixture setup.

For an application with custom context setup, page.pause() can expose codegen controls after routes, storage, or permissions are established. This is preferable to recording against a different environment that lacks the conditions of the failing test.

Distinguish timing symptoms from locator defects

A locator can appear flaky because the page sometimes takes a different path. Before rewriting it, verify URL, response status, authentication role, and enclosing component. If the expected button never exists because an API returned an empty collection, locator syntax is irrelevant.

Conversely, a correct page can expose an ambiguous locator after a new secondary button is introduced. In that case, scope by region, row, or dialog and assert uniqueness. Do not solve ambiguity with a longer timeout; strictness failures are deterministic evidence that the test contract is underspecified.

If stepping slowly makes the test pass, investigate readiness and races. Interactive delay can allow asynchronous work to finish. Replace the accidental delay with an observable assertion or event tied to the user outcome, then verify headless execution without debug pacing.

Preserve evidence when local and CI behavior differ

UI Mode and Inspector change execution speed and normally display a headed browser. CI may use fewer resources, a different browser project, or a clean worker with no cached application state. Retain the CI trace and compare its metadata and first divergent action with the local run.

Try a local headless focused run after the interactive fix. Recreate CI worker count and retries when resource contention is suspected. If the failure only occurs with parallel tests, inspect shared accounts, files, ports, and database records rather than continuing to tune the locator in isolation.

Operational interactive-debugging checklist

• Reproduce one test under the same Playwright project as CI.
• Confirm base URL, credentials, flags, and setup dependencies.
• Use UI Mode to find the last correct action.
• Pause immediately before the first divergent transition.
• Read actionability logs before changing timeout or using force.
• Validate page identity and business state before editing a locator.
• Prefer semantic locators and assert uniqueness when repetition is possible.
• Treat codegen output as a draft observation.
• Rerun once interactively and once cleanly in headless mode.
• Remove page.pause() and temporary focus markers before completion.

Finish with a verified explanation

A debugging session is complete when it can state why the original run failed and demonstrate that the correction addresses that cause under equivalent conditions. Use UI Mode to bound the divergence, the Inspector to inspect the live transition, and locator tools to test only the selector hypothesis. Then remove debugging scaffolding, rerun the focused test cleanly, and execute the surrounding group. The result should be a clearer product-state contract, not merely a green run obtained at interactive speed.