Efficient Test Debugging with Playwright Trace Viewer

Cerosh Jacob
3 min readSep 11


Photo by Immo Wegmann on Unsplash

Identifying the cause of a failed automated test script is important during development or maintenance. There are various methods that can be used to find the cause, such as checking logs, reviewing images of the failure, examining network calls, or exploring the code.

Playwright offers a powerful tool called the Trace Viewer that helps developers debug by providing detailed information on the events leading up to the failure. The Cypress Test Runner is another tool used for debugging and understanding automated tests, but it differs from the Playwright Trace Viewer in some key ways.

While the Playwright Trace Viewer is a more comprehensive tool, displaying a timeline of all events during the test run and is useful for identifying performance bottlenecks and debugging flaky tests, the Cypress Test Runner is a more lightweight tool that is easier to use and debug. It features a built-in debugger that allows you to inspect the state of the browser and test the code.

Cypress has recently released a cloud-based feature called Test Replay that is specifically designed for debugging. Unlike the Playwright Trace Viewer, Test Replay can be accessed from anywhere. Additionally, Test Replay is specifically designed for debugging tests, while the Playwright Trace Viewer can be used for a variety of purposes, such as performance analysis and debugging.

This tool can quickly identify the root cause of the problem for efficient solutions. By default, a trace is recorded only when retrying a test for the first time. This behaviour can be configured in the playwright.config.ts file. The available options include: 'off', 'on', 'retain-on-failure', and 'on-first-retry'.

import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
trace: 'on-first-retry'

When testing with Playwright, traces can be generated and viewed later in the Trace Viewer for detailed execution information. To record the tracing of a single passing test from a suite, a custom command can be used instead of modifying the playwright.config.ts file. To execute a particular test case, use its file name and line number in the following format: test-case-name.spec.ts:35.

npx playwright test test-case-name.spec.ts:35 —trace on

To view test error messages, go to the Test Results tab in the VS Code terminal. If the root cause of the failure cannot be identified with the information provided in the error message, open the trace viewer using the command at the end of the message. Copy and paste this command into the terminal to view the trace.

npx playwright show-trace test-results/test-case-name/trace.zip

Trace Viewer allows us to hover back and forth along the timeline of test execution, helping us understand the sequence of actions and identify the point of failure. Once we reach that point, we can identify the specific action that caused the failure by reviewing the sequential list of actions captured on the left-hand side of the Trace Viewer. Hovering over each action shows the exact location within the element where a click occurred, denoted by a red circle. We can even watch what happened before and after the action, and the various calls during the action, including the expected and actual values that were resolved, and any messages that appeared in the console during that action.

During the test, we have access to the test source code and can compare the differences between the actual and expected results. Once a difference is identified, we can open the inspector from the development tools and pick the correct value from the DOM console. Editing the DOM is also allowed. With these options, we should be able to identify the root cause of the failure and fix the test.