How do you debug a failing Playwright test?

Start by reading the failure message: Playwright usually names the locator, the action and the check that failed. Then reproduce with a trace or the Inspector. Guessing at waits without looking at the page state is how a small failure turns into a slow, flaky test.

test("debug checkout", async ({ page }) => {
  await page.goto("/checkout");
  await page.pause();
  await page.getByRole("button", { name: "Pay" }).click();
});

Tools in order of usefulness

• The HTML report, which shows the failing step and attaches a trace
• The trace viewer for DOM, network and console state at each step
• --debug or PWDEBUG=1 to launch the Inspector and step through actions
• page.pause() for a breakpoint inside one test
• DEBUG=pw:api for verbose internal API and protocol logs
• --headed to watch the browser when the issue is visual or timing-related

In the Inspector you can step over actions, resume, and inspect the locator picker. If the element is covered or moving, the trace snapshot often shows why. If the failure is a network response, inspect the request in the trace before changing the test.