Part 23: Screenshots, Video and Trace

A screenshot is one moment, a video shows visible change, and a trace is a detailed timeline.

failure → inspect evidence → locate cause

Series: Playwright Zero to Expert | Demo app used throughout this series: saucedemo.com

Recall Part 16’s honest design philosophy: capture rich debugging data only when something actually fails, not for every single test unconditionally. This part covers the three artifacts that philosophy applies to, what each one actually shows you, and — genuinely the important part — how to read them effectively when a test does fail.

---

Screenshots

// playwright.config.ts
use: {
  screenshot: 'only-on-failure',
},

A screenshot is exactly what it sounds like — a single image capturing the page’s exact visual state at the moment of failure. Genuinely useful for the simplest, fastest class of debugging: “was the page even showing what I expected at all?” — catching things like an unexpected error banner, a page that clearly never navigated where it should have, or a layout that’s visibly broken.

You can also capture screenshots manually, at any point, for reasons beyond just automatic failure capture:

await page.screenshot({ path: "inventory-page.png" });
await page
  .getByRole("button", { name: "Login" })
  .screenshot({ path: "login-button-only.png" }); // element-specific

Screenshots are the least detailed of the three artifacts in this part — a single frozen moment, with no information about what happened before that moment, which is exactly the gap video and trace exist to fill.

---

Video

use: {
  video: 'retain-on-failure',
},

A recorded video of the entire test’s execution, from start to finish — genuinely useful for understanding the sequence of events leading up to a failure, not just the final broken state. Did a modal appear and then unexpectedly close on its own right before the failure? Did the page flash briefly to an error state before recovering? A screenshot alone, taken only at the final moment of failure, can’t answer these questions; video can.

retain-on-failure specifically means: record every test’s video during execution, but only actually keep the recording afterward for tests that failed — deleting it for tests that passed, avoiding the storage cost of retaining video for the (typically vast majority of) tests that never needed it.

---

Trace — the Most Powerful of the Three

use: {
  trace: 'on-first-retry',
},

A trace is meaningfully more than a recording — it’s a complete, interactive, step-by-step reconstruction of the entire test’s execution, including a screenshot at every single action, the full DOM snapshot at each step (meaning you can genuinely inspect the actual live page state, not just look at a flat image), every network request and response, and console logs — all viewable afterward in Playwright’s Trace Viewer.

Analogy: Crime Scene Photo vs. Security Camera vs. The Flight Black Box Imagine investigating an accident:

• Screenshot (Crime Scene Photo): You get a single, high-quality picture taken after the crash occurred. You see the dented bumper, but you cannot tell what speed the car was going, or who was driving.
• Video (Security Camera): You watch a flat visual recording of the crash. You see the car hit the wall, but you don’t know what credentials were typed into the dashboard or what the server’s response was.
• Trace (Flight Black Box + Replay Chamber): You get the airplane’s flight recorder. It logs altitude, fuel flow, button states, engine heat, and crew cabin audio. Even better: it places you in a virtual simulator where you can pause time at second 12, walk around the cabin, inspect the engine dials, click the navigation console, and check the weather radar status.

📊 Table: Comparative Debugging Artifacts Matrix

Here is the level of evidence detail captured by each of Playwright’s automatic failure tracking mechanisms:

Artifact	Type	Captures Visuals?	Retains DOM History?	Retains Network Payloads?	Execution Speed Impact
Screenshot	Static Image (.png)	Yes (Final state)	No	No	Minimal (Near zero)
Video	Flat Recording (.webm)	Yes (Entire flow)	No	No	Low
Trace	Interactive Archive (.zip)	Yes (Frame-by-frame)	Yes (Full DevTools Elements)	Yes (Headers & Bodies)	Medium (Best on retry)

npx playwright show-trace trace.zip

This opens an interactive interface where you can click through your test action by action — seeing exactly what the page looked like, and what its DOM actually contained, at each individual step, alongside the network activity and console output happening at that exact same moment.

This is genuinely the single most powerful debugging tool available to you for a failed Playwright test, and it’s worth treating as your default first step when investigating any confusing, non-obvious failure — dramatically more informative than a screenshot or even a video alone, because it lets you actually interact with the reconstructed state, not just passively watch or look at it.

on-first-retry is a deliberate, efficient default worth understanding: it records a trace only when a test is retried after an initial failure (recall Part 16’s retries setting) — meaning you get this rich, detailed data specifically for tests that genuinely failed, without paying the real recording overhead for every single test that simply passed on its first attempt.

---

How It Works in a Real Test Run

These artifacts answer different questions. A screenshot shows one visual moment, video shows the visible timeline, and trace connects Playwright actions with DOM snapshots, timing, logs, and network evidence.

A useful CI policy retains lightweight evidence for failures and records richer traces on the first retry. Artifacts can contain personal data or secrets, so access, retention, and redaction belong in the framework design.

Interview Questions

Q: What’s the practical difference between a screenshot and a trace, in terms of what each one can actually tell you about a failure?

Ans: A screenshot is a single frozen image at one specific moment — useful for a quick check of the page’s final visual state, but with no information about what happened before it. A trace is a full, interactive reconstruction of the entire test’s execution, including a DOM snapshot, network activity, and console logs at every individual step — letting you actually walk through and inspect exactly what happened, and in what order, leading up to the failure, not just see its final result.

Q: Why does retain-on-failure (for video) and on-first-retry (for trace) exist as configuration options, rather than always capturing this data unconditionally?

Ans: Because capturing detailed video and trace data has a real cost — in execution time and storage — and the overwhelming majority of tests in a healthy suite pass without needing this data ever reviewed. These settings ensure the rich debugging information is captured and retained specifically for tests that actually failed, where it’s genuinely useful, without paying that same cost for every test that succeeded and will never actually be investigated.

Q: Why is trace generally considered a more powerful debugging tool than video, despite video also showing the test’s full execution?

Ans: Trace includes a genuine DOM snapshot at each step, meaning you can actually inspect the real, live page structure at that moment — not just a flat visual recording — alongside network requests, responses, and console logs happening at that exact same point in time. Video shows you what the page visually looked like over time, but doesn’t let you interactively inspect the underlying page state or correlate it directly with network and console activity the way a trace does.

Q: A test fails intermittently, and a screenshot taken at the moment of failure shows a completely blank, empty page. What would trace or video help you determine that the screenshot alone can’t?

Ans: The screenshot alone only shows the final, blank state — it can’t tell you why the page is blank: whether it never loaded any content in the first place, whether it loaded correctly and then something caused it to clear, or whether a network request failed silently partway through. Trace or video would let you see the sequence of events leading up to that blank state, including network activity and earlier DOM snapshots, revealing whether the problem happened at load time, or was some later state change that emptied an otherwise correctly loaded page.

---

Exercises — Part 23

Understand: Explain, in your own words, why a screenshot alone is often insufficient to diagnose an intermittent, timing-related failure, and what specifically trace adds that a screenshot cannot provide.

Simple Practice: Configure screenshot: 'only-on-failure', video: 'retain-on-failure', and trace: 'on-first-retry' in a Playwright project, deliberately write a test with an incorrect assertion so it fails, run it, and open the resulting HTML report to locate and review all three artifacts.

Real-World Scenario: Open a trace file (from the exercise above, or any failed test run) using npx playwright show-trace, and walk through it action by action. Write down, in your own words, what you can see at each step that you wouldn’t be able to see from a screenshot alone.

Challenge: Deliberately write a test with a subtle timing issue (for instance, asserting on content before a mocked, artificially delayed API response — using Part 19’s techniques — actually resolves), causing an intermittent failure. Use the trace viewer to identify exactly where in the timeline the assertion checked too early, and explain what you observed.

---

Next: Part 24 — Debugging

— a full, systematic debugging methodology using Playwright Inspector, breakpoints, and everything covered in this part, applied to real, confusing failures.