Skip to main content
Free plan, no cardStart free

EngineeringHow-to guide

How to Debug a Failed Playwright Test: Read the Call Log, Open the Trace, Capture the Three Signals

Most failed browser tests are read wrong, because the reader starts at "Timeout exceeded" and stops. The line that explains the failure is three lines further down. Here is what the messages say, from a run we recorded.

Summarise with AI

Opens a new chat with only this request: Summarise the key points of this article: https://dokimore.com/blog/how-to-debug-failed-playwright-tests

3 of 3Engines that printed the identical call log for a covered button: "<div id=overlay> intercepts pointer events"
26 KBA trace of a three-step flow in Chromium: 12 entries, 6 screenshots, a DOM snapshot file and the network log
134 KBThe same flow traced in Firefox: 38 entries and 32 screenshots
2Console errors captured when the price call answered 500, where the UI showed only the word "error"

In short

  • Read the call log, not the first line. "locator.click: Timeout 400ms exceeded" is the symptom; "waiting for locator('#pay') … element is visible, enabled and stable … <div id="overlay">Loading…</div> intercepts pointer events … retrying click action" is the diagnosis: the button was fine and something covered it. A selector that matches nothing prints only "waiting for locator('#pay-button')" and never gets as far as a state.
  • Record a trace on failure and open it: context.tracing.start({ screenshots: true, snapshots: true }) before the pages, tracing.stop({ path }) after; in Playwright Test, trace: 'on-first-retry'. Our three-step flow produced a 26 KB archive in Chromium with 6 screenshots, a DOM snapshot and the network log, enough to watch the failure step by step.
  • Capture three signals on every run, not only on failure: console messages, failed requests and responses of 400 or more. When the price API answered 500 in our fixture, the page showed one word, "error"; the console carried two errors and the response list carried the URL and the status.

About this article

Format
How-to guide: a procedure to follow, step by step.
Written for
SDETs and automation engineers · Developers who own their tests · QA leads and test managers
Where it applies
Every market. The rules that differ by country are on the country pages.

A browser test fails for one of a few reasons: the element was not there, it was there but could not be acted on, the action happened and the assertion was wrong, or the page did something the test never looked at. Playwright writes which one into the error, but it writes it as a call log under the timeout, and that is the part people skip.

This guide reproduces the first two on a fixture checkout page, in Playwright 1.62.1 against Chromium 151, Firefox 153 and WebKit 26.5, with a trace recording and the three capture hooks running. The messages quoted below are the text those runs produced, unchanged except for line joins; the scripts and the raw output are linked at the end.

Failure one: the selector matches nothing

The test clicked #pay-button on a page whose button is #pay. All three engines printed the same thing after 1.5 seconds, the timeout the test set:

What Playwright printed (Chromium, Firefox and WebKit, identical)
locator.click: Timeout 1500ms exceeded.
Call log:
  - waiting for locator('#pay-button')

That is the whole log. No state is reported because the locator never resolved to an element, which is the tell: a failure that stops at "waiting for locator" is a selector problem, not a timing problem. Lengthening the timeout changes nothing. The fix is the locator, and the quickest check is to paste the page’s HTML and the selector into a selector tester and see what it matches, or to switch to a locator that reads like a user: `page.getByRole('button', { name: 'Pay now' })`.

Failure two: the element is there but something covers it

The page shows a full-screen "Loading…" overlay for 700 ms after load. The test clicked the real #pay button with a 400 ms timeout. Again all three engines printed the same log:

What Playwright printed (Chromium, Firefox and WebKit, identical)
locator.click: Timeout 400ms exceeded.
Call log:
  - waiting for locator('#pay')
    2 × waiting for element to be visible, enabled and stable
      - element is visible, enabled and stable
      - <div id="overlay">Loading…</div> intercepts pointer events
    - retrying click action

Everything you need is in those six lines. The locator resolved. The element passed the actionability checks: visible, enabled, stable. The click was refused because another element, named by its tag, id and text, was at the point where the click would land. Playwright retried twice and ran out of time. The fix is not a longer timeout but a wait for the overlay to go, `await expect(page.locator('#overlay')).toBeHidden()`, or, if the overlay is the product’s bug, a bug report with this log attached. With the default 30-second timeout the click would have succeeded at 700 ms, which is how this class of failure hides in a suite until the day the overlay stays.

What a trace holds, measured

A trace is the recording a reader opens when the log is not enough. The run started tracing before the page existed and stopped it after the reload that triggered the failing price call. The archives are small enough to keep for every failed run:

trace.zip for the same three-step flow, Playwright 1.62.1, screenshots and DOM snapshots on, sources off
EngineArchiveEntriesScreenshotsOther files
Chromium 15126,563 bytes126one DOM snapshot file, trace.trace, trace.network
Firefox 153134,348 bytes3832the same three
WebKit 26.520,402 bytes104the same three
Recording a trace outside the test runner (inside it: trace: 'on-first-retry' in the config)
const context = await browser.newContext();
await context.tracing.start({ screenshots: true, snapshots: true, sources: false });
const page = await context.newPage();
try {
  await page.goto('/checkout');
  await page.getByRole('button', { name: 'Pay now' }).click();
  await expect(page.locator('#done')).toBeVisible();
} finally {
  await context.tracing.stop({ path: 'trace.zip' });   // npx playwright show-trace trace.zip
}

Firefox takes more screenshots during the same flow, hence the larger archive; the content is the same kind. The viewer shows each action with its screenshot, the DOM before and after, the network requests and the console, which turns "it failed in CI" into something you can watch. In Playwright Test, trace: 'on-first-retry' records only when a failed test is retried, which keeps the cost to the failures.

In the product

The three signals to capture on every run

Our fixture’s price lookup fails on every second call. After a reload the page showed the word "error" in the price field and nothing else. The test had three listeners attached from the start, and they held the story:

Three listeners, attached before page.goto()
const consoleMessages: string[] = [];
const failedRequests: string[] = [];
const badResponses: string[] = [];
page.on('console', (m) => { if (m.type() === 'error' || m.type() === 'warning') consoleMessages.push(`${m.type()}: ${m.text()}`); });
page.on('requestfailed', (r) => failedRequests.push(`${r.url()} ${r.failure()?.errorText}`));
page.on('response', (r) => { if (r.status() >= 400) badResponses.push(`${r.status()} ${r.request().method()} ${r.url()}`); });
// … after the test, attach all three to the report, or assert on them:
expect(badResponses, 'the page made a failing request').toEqual([]);
  • Console: Chromium and WebKit logged "Failed to load resource: the server responded with a status of 500 (Internal Server Error)" and the page’s own "price lookup failed 500". Firefox logged those two plus a warning that the fixture page had not declared its character encoding, a real defect in the fixture that no other signal reported.
  • Failed requests: none in this run, because a 500 is a completed request with a bad status, not a failed one. requestfailed fires for DNS failures, connection resets, aborted and blocked requests; the two lists answer different questions and a suite needs both.
  • Responses of 400 or more: one entry, "500 GET /api/price?call=1". That line is the bug report. Without it the failure reads as "the price field says error".

A reading order for any failed browser test

  • Read the call log under the timeout. "waiting for locator" alone means the selector; a state line plus "intercepts pointer events" or "element is not enabled" means the page; a passed click followed by a failed expect means the assertion or the product.
  • Check the three signals from the run: a 4xx or 5xx response explains most "the page shows nothing" failures.
  • Open the trace and step to the failing action; look at the screenshot and the DOM before it.
  • Rerun once on the same commit. A pass means a flaky test, which is a different investigation; the flaky-tests guide covers it.
  • Fix the cause: the locator, the wait for a real condition, or the product. Never the timeout alone.

How Dokimore shows a failed step

Every replayed step keeps a screenshot, the network calls it caused with their statuses, and the assertion result, so the three signals above are collected without listeners and shown beside the step in the run detail. When a locator stops matching, the stored fallbacks try to rescue the step and the run shows the original, the replacement and the strategy, which is the "waiting for locator" failure turned into a review instead of a red build.

What to do next

  1. Attach the three listeners (console, requestfailed, responses of 400 or more) in a fixture that every test uses, and attach their output to the report on failure.
  2. Turn on trace: 'on-first-retry' in playwright.config and keep the archives for failed runs; at 20 to 134 KB per run they cost nothing to store.
  3. Read the next failing call log to the bottom before touching a timeout; the line that names the covering element or the missing locator is the diagnosis.
  4. Replace selectors that fail at "waiting for locator" with role, label or test-id locators, and check them in the selector tester before they go into the suite.
  5. Rerun a failure once on the same commit before investigating it as a bug; a pass makes it a flaky test and a different procedure.

Questions people ask

What does "Timeout exceeded" mean in a Playwright test?

Only that the action did not complete within the limit. The reason is in the call log beneath it: "waiting for locator" alone means the selector matched nothing; "element is visible, enabled and stable" followed by "intercepts pointer events" means the element was fine and another element covered it. In our run both messages were identical in Chromium, Firefox and WebKit.

How do I see what the page looked like when a Playwright test failed?

Record a trace: trace: 'on-first-retry' in the config, or context.tracing.start({ screenshots: true, snapshots: true }) and tracing.stop({ path }) around the flow, then open it with npx playwright show-trace. A three-step flow produced a 26 KB archive in Chromium with 6 screenshots and a DOM snapshot; the viewer steps through each action with the page and the network as they were.

Why does the page show "error" but my test gives no reason?

Because the reason was in a response the test never looked at. Attach listeners for console messages, failed requests and responses with status 400 or more before page.goto(); in our run the console held two errors and the response list held "500 GET /api/price" while the UI showed one word.

Should I increase the timeout when a Playwright test fails?

Not until the call log says the element was still loading. A selector that matches nothing never passes with more time, and a covering overlay that goes away at 700 ms passes with a 30-second timeout only until the day it stays. Fix the locator, wait for the real condition, or report the product bug the log describes.

How we measured this

  • Run on 2026-11-04 with Playwright 1.62.1 and its pinned builds (Chromium 151.0.7922.34, Firefox 153.0, WebKit 26.5), networking disabled, fixture page and server on 127.0.0.1. Scripts and raw output: docs/marketing/keyword-research/research/playwright-guides-2026-11-04 (e3-debug.js, out/e3-debug.json). The error texts are quoted from that output with line breaks restored; nothing else was edited.
  • The covered-button case was checked within 400 ms of page load, while the fixture’s overlay (removed at 700 ms) was still present; a first run of the script checked it after the wrong-selector case had already consumed 1.5 s, by which time the overlay was gone and the click succeeded, which is why the order was changed and the run repeated. Trace sizes are from the repeated run.
  • The measurements used the library API; the snippets wrap the same calls for Playwright Test where that is how a reader would write them.
  • Dokimore’s behaviour is the product code on the article date: each replayed step keeps a screenshot, its network calls and the assertion result, and a rescued locator is shown with its strategy in the run detail.

Sources

  1. Playwright documentation, Trace viewer: what a trace contains and how to record one (trace option, on-first-retry, tracing.start/stop) read
  2. Playwright documentation, Locators: prefer getByRole, getByText and getByTestId; CSS and XPath tied to DOM structure break when it changes read
  3. Playwright documentation, Browsers: each release pins its own browser builds read

See it on your own project

Every new account starts a 14-day Solo Pro trial, then 14 days on the Free plan. No card. Record one flow and measure the difference on your own numbers.

  • Free plan, no card
  • 14-day Solo Pro trial
  • Demo replies within one business day
  • Data hosted in India