Playwright Trace Viewer helps you understand what happened before a test failed, not just where the final error was reported. A trace can capture the test timeline, actions, DOM snapshots, screenshots, network activity, console output, and locator information.
A practical debugging workflow is simple: open the failed action, inspect the page state, then work backward until you find the first unexpected state.
Leapwork Play extends this debugging workflow by keeping your Playwright execution within the Play test flow, so you can start from the failed step and investigate the execution context around it instead of treating the final exception as the whole story.
How do you debug a Playwright failure with Trace Viewer?
Start by capturing a trace for failed or retried tests.
For example:
import { defineConfig } from '@playwright/test';
export default defineConfig({
trace: 'on-first-retry'
});
When a test fails, open the trace and follow this sequence:
-
Find the failed action.
-
Check what the page looked like at that point.
-
Inspect the locator and element state.
-
Check console or network activity if the UI state is unexpected.
-
Move backward until you find the first meaningful difference from a successful run.
The goal is not simply to understand the final error. It is to find what went wrong first.
How to debug a Playwright test failure in five minutes
Use this five-minute Trace Viewer workflow to move from the final error message to the first meaningful failure. The goal is to diagnose the cause of a failed Playwright test before changing timeouts, retries, waits, or locators.
Step 1: Start with the failed action
Open the trace and select the action that failed. For example, you might see:
locator.click: Timeout exceeded
Do not immediately increase the timeout. First, check what Playwright was trying to click and what the application looked like when the action failed.
Step 2: Inspect the page state
Ask these questions before changing the test:
-
Is the test on the expected page?
-
Is the element actually present?
-
Is another element covering it?
-
Did authentication fail earlier?
-
Did an expected dialog, navigation, or page state never appear?
A click timeout may only be the final symptom. For example:
Authentication fails
↓
Page remains on login
↓
Orders button never appears
↓
Click times out
In this case, the click is not the root problem. Authentication is.
Step 3: Check the locator
Inspect which element the locator resolved to in the trace. A locator-related failure can happen when:
-
no matching element is found;
-
multiple elements match the same locator;
-
the accessible name has changed;
-
the test has an outdated assumption about the UI;
-
the test is on the wrong page entirely.
Only fix the locator when the trace shows the locator is actually responsible.
Step 4: Check network and console evidence
If the UI never reaches the expected state, look for supporting evidence in network requests and console output. For example:
Click Save
↓
API request fails
↓
Success state never appears
↓
Assertion times out
The failed assertion is downstream of the actual problem. In this example, the network failure is the issue to investigate first.
Step 5: Fix the first failure, not the last symptom
Once you identify the first unexpected state, fix that problem and rerun the test. Avoid immediately changing timeouts, retries, waits and locators. Unless the trace shows that one of those is actually responsible. Debug Playwright tests from evidence, not from the final exception.
How Play helps you investigate Playwright failures
Play keeps the failure connected to the test execution, so you can start from the failed Play step and inspect what happened during the run.
The Engineering demo shows the debugging workflow directly in Play: open the failed execution, identify the failed step, and use the available execution details to understand what happened before changing the test.
This gives you a practical workflow:
Run test → identify failed step → inspect execution details → find the cause → update and rerun
How Play extends the Playwright debugging workflow
Once the exact Play diagnostics are confirmed, keep this table short:
|
With Playwright Trace Viewer |
With Leapwork Play |
|---|---|
|
Start from the failed Playwright action |
Start from the failed step in the Play execution |
|
Inspect the captured trace and application state |
Inspect the failure in the context of the recorded Play test flow |
|
Work backward to find the first unexpected state |
See which test steps succeeded before the failure |
|
Fix the underlying application or test problem |
Update the Playwright test and rerun it through Play |
Play and Trace Viewer solve complementary parts of the debugging workflow. Trace Viewer helps you inspect the Playwright execution in detail, while Play helps you understand the failure in the context of the complete test flow.
Best practices
-
Start from the failed Play step and inspect the execution context before changing the underlying Playwright test.
-
In Trace Viewer, work backward from the reported failure to the first unexpected state.
-
Check the page state before assuming the locator is wrong.
-
Use network and console evidence when the UI failure appears to be downstream of another problem.
-
Do not increase timeouts simply because the final error says
Timeout exceeded. -
Fix the root cause before adding retries.
Troubleshooting
|
Problem |
What to check |
|---|---|
|
Trace shows a click timeout |
Check the page state immediately before the click. |
|
Element is missing |
Confirm that the test reached the correct page and previous actions succeeded. |
|
Locator looks correct but still fails |
Check whether the application state or accessible name changed. |
|
Assertion times out |
Look for an earlier application/network failure that prevented the expected state. |
|
Trace contains many failures |
Find the first meaningful divergence; later failures may only be consequences. |
Frequently asked questions
What is Playwright Trace Viewer?
Trace Viewer is Playwright's tool for inspecting a recorded test execution, including actions and other captured diagnostic information.
What should I check first in a Playwright trace?
Start with the failed action, inspect the application state at that point, and then work backward until you find the first unexpected state.
Should I increase the timeout when Trace Viewer shows a timeout?
Not automatically. First determine why the expected condition was never reached. The timeout may only be the final symptom.
How do I find the root cause of a Playwright failure?
Find the first point where the failed execution differs from the expected behavior. Later errors often result from that earlier problem.
How does Leapwork Play help diagnose Playwright failures?
Play keeps the failure within the context of the complete test execution. Start from the failed Play step, inspect what happened during the run, and identify the point where the test stopped behaving as expected before changing the underlying Playwright test.