# What Is a Playwright Trace? — trace.zip, Trace Modes and What It Records

Canonical: https://commareports.com/glossary/playwright-trace
Published: 2026-11-05

> A Playwright trace is a zip recording every action of a test with DOM snapshots, screenshots, network and console. What is inside trace.zip, the trace modes, how to open one, and why it is sensitive.

# Playwright trace

**A Playwright trace is a zip file that records a test action by
action** — every click, fill and navigation, with the page's DOM before
and after it, a screencast, the network traffic, the console output and
the line of test code that ran. The trace viewer replays it as a
timeline after the fact, which is why it is the main evidence for a
failure you cannot reproduce.

## What is inside `trace.zip`

| Part          | What it holds                                                              |
| ------------- | -------------------------------------------------------------------------- |
| Actions       | Each Playwright call, its arguments, duration and result                   |
| DOM snapshots | The page before, during and after each action — inspectable, not a picture |
| Screencast    | Frames used for the filmstrip at the top of the viewer                     |
| Network       | Requests and responses, including headers and bodies                       |
| Console       | Page `console.*` output and errors                                         |
| Sources       | The test files, so each action maps back to a line                         |

Snapshots are the part that makes traces useful: you can open the DOM
at the moment an assertion failed and inspect the element that was
there instead of the one the test expected.

## Recording one

In the test runner, set the mode in the config:

```ts
// playwright.config.ts
use: {
  trace: "retain-on-failure",
},
```

or per run with `npx playwright test --trace on`. The modes are `off`,
`on`, `retain-on-failure`, `on-first-retry` and `on-all-retries`. The
generated config uses `on-first-retry` with `retries: 0` outside CI —
which is why a local failure often has no trace
([fix](/fix/playwright-trace-viewer-not-opening)).

With the library API:

```ts
await context.tracing.start({ screenshots: true, snapshots: true, sources: true });
// … actions …
await context.tracing.stop({ path: "trace.zip" });
```

## Opening one

```bash
npx playwright show-trace trace.zip
```

Or drop the zip on [trace.playwright.dev](https://trace.playwright.dev),
a static build of the same viewer that reads the file in your browser.
Both need a normal `http(s)` origin because the viewer runs on a
service worker — it will not start from `file://` or inside a
sandboxed iframe with an opaque origin.

## Why traces are sensitive

A trace is a recording of everything the browser saw. That includes
response bodies, `Cookie` and `Authorization` headers, and text typed
into password fields. Three rules:

- Run suites against **test accounts**, never personal ones.
- Store traces like any artifact that can hold credentials — not on a
  public bucket, not on a public link.
- Prefer `retain-on-failure` over `on`, so passing tests do not leave
  recordings behind.

## Traces and the HTML report

The HTML reporter links each test's trace from the report, copying the
zips into `playwright-report/data/`. The report and the trace are two
different things to share: the report is what reviewers read and argue
about; the trace is what one person opens to work out why. Publishing
the report to a stable link with the trace attached keeps both in one
place — see [share a Playwright report](/share-playwright-report).

## Try it

Comma is free — unlimited reports, unlimited commenters, unlimited
revision history.

**[Publish a Playwright report →](https://commareports.com/)**

### Related

- [Playwright trace viewer won't open](/fix/playwright-trace-viewer-not-opening)
- [Playwright report is blank](/fix/playwright-report-blank)
- [Flaky test](/glossary/flaky-test) · [Test quarantine](/glossary/test-quarantine)
- [Glossary](/glossary)