Which tool should I use first when a test fails on CI?

Open the trace from the CI artifacts. It shows the page state, network calls, and console output at the failing step without needing to reproduce the run locally.

Is the code from codegen ready to commit?

Usually not. It is a fast draft. Replace brittle locators with role or label locators, add meaningful assertions, and refactor repeated steps into page objects.

Debugging Playwright Tests: UI Mode, Trace Viewer, and Codegen

Introduction

A failing test is only useful if you can see why it failed. Playwright ships with strong debugging tools: a watch-mode UI, a step-through debugger, a trace viewer that records everything about a run, and a recorder that writes tests for you. This lesson shows when to use each.

Prerequisites

A Playwright project with a few tests
The HTML report from the setup lesson

Step-by-Step Guide

Step 1: Explore tests in UI mode

UI mode shows your tests, lets you run them selectively, and displays a timeline with a snapshot of the page at every action. It is great for writing and understanding tests.

npx playwright test --ui

Step 2: Step through with the debugger

The --debug flag opens the Playwright Inspector and runs tests one action at a time in a headed browser. Call page.pause() inside a test to stop at a specific line.

npx playwright test --debug

// or pause at a specific point
await page.pause();

Step 3: Record traces

A trace records actions, DOM snapshots, network calls, and console messages. Set trace to on-first-retry in the config, or force it for a single run when investigating.

npx playwright test --trace on

Step 4: Open a trace

Open traces from the HTML report, or open a trace file directly. You can move through each step, inspect the page as it was at that moment, and see the network requests that were made.

npx playwright show-trace test-results/path-to/trace.zip

Step 5: Generate tests with codegen

Codegen records your clicks and typing in a browser and writes the matching test code. Treat it as a starting point: review the locators and add assertions.

npx playwright codegen https://demo.playwright.dev/todomvc

FAQs

Which tool should I use first when a test fails on CI?: Open the trace from the CI artifacts. It shows the page state, network calls, and console output at the failing step without needing to reproduce the run locally.
Is the code from codegen ready to commit?: Usually not. It is a fast draft. Replace brittle locators with role or label locators, add meaningful assertions, and refactor repeated steps into page objects.

Summary

Use UI mode while authoring, the debugger for stepping through logic, traces for failures that happened elsewhere, and codegen to draft new tests quickly. Traces are especially valuable in CI.