Debugging a failing test

Trace viewer#

A trace records the whole run: every action, the page as it was at that moment (which you can inspect), the network, the console, the errors and the line of code. Choose when to keep it in Run options → Trace: Off, On failure (default) or Always.

• After the run, Trace opens it in a window of the app, without internet. With a suite or test data, Traces (N) lists one per test.
• The button next to it saves the trace as a file to attach to a bug report; it opens with Playwright or on trace.playwright.dev.
• Environment secrets are hidden (••••••); if the environment has secrets, the trace has no screenshots. In In-App runs the trace contains only the test’s pages.

Breakpoints#

Pause an In-App run of a single recorded test before a step, on the page as it is at that moment:

1. In the Project tab, open the test’s menu → Show steps. The Steps view of the Output tab lists its steps. (With the test open in the recorder, use the dots on the step cards.)
2. Click the dot next to a step to set (red) or remove a breakpoint.
3. Run the test In-App. It stops before that step: Continue (to the next breakpoint), Step (one step, then stop), To the end (ignore breakpoints) or Stop.

While paused, inspect the page with DOM, Console and Network; the time spent paused doesn’t count against the test timeout. With test data it stops at every row. Breakpoints are saved on your PC, never in the test or the export, and are ignored in Headless runs.

Run single steps#

To try a fix without rerunning the whole test, use ▶ on a step card: Run this step, Run from here or Run up to here (see Step card). To continue recording from a point, use + → Run up to here, then record.

Self-healing locators#

When the site changes and a step’s chosen locator no longer finds its element (say a renamed test id), the run tries the other locators saved for the same element. If one finds it, the test goes on and the output says ⚕ Healed. Checks are never healed.

• At the end of the run, the Healed section lists the repaired steps: Use it makes that locator the chosen one — in the test, in the Page element (offering to update the tests that use it) or in the Reusable steps.
• If the element changed after the run, Use it changes nothing and says so, so it never undoes a more recent fix.
• Turn it off in Project settings → Runs → Self-healing locators. The exported project runs the tests as they are.

Is it a bug?#

When the failure is a real problem of the site, write it down in the Bugs tab, with the steps, screenshot, network calls and console errors — see Bug reports. An AI agent can investigate failures and write the report for you.