Blog # 18: 🧪 Playwright Trace - Your Test's Black Box Recorder

When I first started dabbling in Playwright for automation testing, I was amazed by its power—but honestly, I was intimidated by debugging. Failed tests felt like cryptic puzzles. Why did that button click fail? Was it the DOM? The network?
Then I discovered Playwright Trace Viewer, and it was like getting a magnifying glass to solve my test mysteries. This isn’t just a feature—it’s my trusty debugging sidekick. Here’s how I went from “What went wrong?” to “I’ve got this!” using Trace Viewer.

✨ What is Trace Viewer?

Picture Trace Viewer as a time machine for your tests. It records everything—clicks, navigations, network calls, console logs, and even what the page looked like—and lets you rewind to spot exactly where things went off the rails.
For someone new like me, this was mind-blowing. Here's what Trace Viewer helped me see:

✅ Every action—like a movie script of my test
🖼️ Screenshots that said “This is what the page looked like!”
🌐 Network logs that exposed API failures
📄 DOM snapshots for inspecting the structure
💥 Error lines from my script, without endless console.log hunts

It's like being a detective with all the clues pinned up on a digital evidence board.

Trace Viewer

🛠️ My First Step: How to Set Trace On

Getting started with tracing was easier than I expected—and gave me instant clarity on failed test cases.

🔹 Option 1: CLI Shortcut

This command was my first win:

npx playwright test --trace=on

Then I learned the smarter way for CI runs:

npx playwright test --trace=retain-on-failure

✅ Pro tip: This only saves traces for failed tests and helps avoid massive storage issues.

🔹 Option 2: Config File Setup (Set It & Forget It)

Once I realized tracing was gold, I made it permanent in my playwright.config.js:

import { defineConfig } from '@playwright/test';
export default defineConfig({
  use: {
    trace: 'retain-on-failure', // Ideal for CI
  },
});

No more manually passing flags—traces just work when I need them.

🔍 Cracking Open the Case: How to View the Trace

After running my test, I found a shiny .zip file inside the test-results folder. Time to investigate!

📁 Option 1: Open via CLI

npx playwright show-trace relative path                                                                 Example: npx playwright show-trace test-results/login-test/trace.zip

One command, and BOOM—Trace Viewer opens in the browser, like a full control center for your test run.

🌐 Option 2: Web Interface (Drag-and-Drop)

Go to: https://trace.playwright.dev

Drag your trace.zip file into the page, and you’re in!

🕵️‍♂️ The Thrill of the Investigation: Inside Trace Viewer

Using Trace Viewer felt like stepping into a debugging control room. Here’s what I explored:

▶️ Actions Tab
A play-by-play of the test’s moves: page.goto, page.click, and more.
Clicking an action showed the locator and duration. Hovering revealed screenshots and DOM snapshots—actual time travel.

⏳ Timeline
I could zoom in on specific moments and spot exactly when things broke (hello, red error line!).

🖼️ Screenshots Tab
Polaroid-style captures of the page state—perfect for visual test debugging.

🌐 Network Tab

Helped me catch a delayed API that was silently breaking a test. Headers, payloads—everything’s visible.

📋 Logs Tab
Both browser and script logs, grouped by action. Super helpful for tracking sneaky bugs.

❌ Errors Tab
Pinpointed the exact line of failure and showed the full stack trace.

🧾 Metadata & Attachments
From browser version to viewport size—every detail, every clue.

❤️ Why I’m Obsessed

Trace Viewer turned debugging from a chore into an interactive adventure. As a Playwright learner, it’s helped me build confidence to investigate failures without panicking. Instead of guessing or drowning in logs, I follow the clues like a pro.
It’s not just a tool—it’s my debugging superpower.