Playwright Trace Viewer: how to debug failing tests

8 min read · TypeScript · 6 linked exercises

A failing test tells you which line failed. It rarely tells you why. The usual next step, adding logs and running the test again, is slow, and it's impossible when the failure happened once in CI.

A trace records the whole run: every action, the page before and after it, the network and the console. This guide shows how to read the error first, then record and read a trace, and how to collect the same evidence in code.

Read the error first

Many failures don't need a trace at all. A Playwright error has three parts: what failed, the call log of everything Playwright tried, and the line in your test.

Error: locator.click: Timeout 5000ms exceeded.
Call log:
  - waiting for getByRole('button', { name: 'Place order' })
    - locator resolved to <button disabled type="submit">Place order</button>
  - attempting click action
    - waiting for element to be visible, enabled and stable
      - element is not enabled
    - retrying click action

Read the call log from the top. Here Playwright found the button, so the locator is right. The click never happened because the button stayed disabled. The test skipped something a user does first, such as ticking a checkbox.

A failed assertion shows the expected and received values instead. Compare them character by character: a difference in capitals or spaces is easy to miss.

Practise it
  • Reading FailuresBeginnerFive failing tests. Fix each one from what its error says.

Record a trace

For one run, add a flag:

npx playwright test checkout.spec.ts --trace on

For every run, set it in playwright.config.ts:

export default defineConfig({
  retries: process.env.CI ? 2 : 0,
  use: {
    trace: 'on-first-retry',
  },
});
ValueRecordsUse it
'on-first-retry'The first retry of a failed testIn CI. Needs retries above 0
'retain-on-failure'Every test, kept only for failuresWhen you run without retries
'on'Every testLocally, for the test you're working on
'off'NothingThe default without a config

Recording slows a test a little, and a trace can take several megabytes, which is why the usual CI setting records on the first retry only. To record every test in one file while you work on it, put test.use({ trace: 'on' }) at its top.

Open the trace

There are three ways in:

  • From the HTML report. npx playwright show-report, open the failed test and click its trace.
  • From the file. npx playwright show-trace test-results/<test-folder>/trace.zip.
  • In the browser. Drop a trace.zip on trace.playwright.dev. The file is read in your browser and isn't uploaded anywhere. This is the quickest way to open a trace a colleague or a CI run gave you.

UI mode, npx playwright test --ui, shows the same view live for every test you run, with no flag. Use it while you write tests.

What a trace shows

  • Actions. Every step of the test in order, with its duration. The failed one is marked.
  • Snapshots. The page before and after each action. They are DOM snapshots, not screenshots: you can open DevTools on them, and use "Pick locator" to try a locator against the page as it was.
  • Call and Log. The locator, its arguments and what Playwright waited for.
  • Console. Everything the page logged, including errors nobody saw on screen.
  • Network. Every request with its status, headers and bodies.
  • Source. The line of your test that ran the selected action.

Selecting an action filters the console and network tabs to what happened during it. That's how you connect a click to the request it sent.

A method for reading one

Take the most confusing kind of failure: the feature works when you try it by hand and fails in the test. Work through the trace in this order.

  1. Select the failed action and look at "Before". Was the page in the state you assumed? Look for values that were still loading.
  2. Open the Network tab for that action. Find the request with a 4xx or 5xx status. Read what the page sent, not only what came back.
  3. Open the Console tab. Apps often log the real reason and show the user a generic message.
  4. Ask what a person would have waited for. Playwright acts the moment an element is ready. A person first reads the page. If the test was faster than the data, add an assertion on that data before the action.
// Before: clicks as soon as the button is enabled
await page.getByRole('button', { name: 'Place order' }).click();

// After: waits for the price a customer would read first, then clicks
await expect(page.getByTestId('delivery-price')).toHaveText(/^\$\d/);
await page.getByRole('button', { name: 'Place order' }).click();

Don't fix this kind of failure with a sleep. The auto-waiting guide explains what to wait for instead.

Practise it
  • Trace ViewerIntermediateA payment that works by hand and fails in a test. Find out why from the trace.

Collect the evidence in code

A trace is for a person. To make a test fail when the page logs an error, listen for it. An automatic fixture does that for every test without changing them:

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

export const test = base.extend<{ pageErrors: Error[] }>({
  pageErrors: [
    async ({ page }, use) => {
      const errors: Error[] = [];
      page.on('pageerror', (error) => errors.push(error));
      await use(errors);
    },
    { auto: true },
  ],
});

test('syncs without errors', async ({ page, pageErrors }) => {
  // …
  expect(pageErrors).toEqual([]);
});

page.on('pageerror') receives uncaught exceptions. page.on('console') receives log messages, and message.type() tells errors from warnings. testInfo.attach() adds what you collected to the report, next to the trace.

Once a trace has shown you which request matters, assert on it with page.waitForResponse(), so the next regression fails with a clear message.

Practise it
  • Debugging ToolkitAdvancedA screen that says everything worked, while the console says otherwise.
  • API PlaygroundIntermediateAssert on the status and body of the requests a page sends.

Steps, pause and the Inspector

A long test produces a long list of actions. Group them with test.step(), and the trace and the report show named, collapsible steps:

await test.step('Add a laptop to the cart', async () => {
  await page.getByRole('searchbox', { name: 'Search products' }).fill('laptop');
  // …
});

To stop a test and look around, run it with --debug or call await page.pause() where you want to stop. The Inspector opens, and you can step through the actions and try locators on the live page. Remove page.pause() before you commit.

Practise it
  • First E2E TestIntermediateGroup a whole purchase into steps and read them in the trace.

Failures you can't reproduce

A test that fails one run in twenty needs many runs. Repeat it and keep the traces of the failures only:

npx playwright test cart.spec.ts --repeat-each=20 --trace retain-on-failure

Then compare a failed trace with a passing one. Look at the order of the network responses and at the "Before" snapshot of the failed action. Timing bugs show up there.

In CI you can't rerun by hand, so record on the first retry and keep the report as an artifact. The CI guide shows the setup.

Practise it
  • Flaky LabAdvancedTests that pass most of the time. Run them twenty times and fix them.

Exercises in this guide

More guides