Playwright: Debugging, Tracing & Codegen

With PWDEBUG=console and a page.pause() in the test, Playwright adds a playwright object to the page’s developer-tools console. It uses the real selector engine, so you can try locators without touching the test:

In WebKit, opening the WebKit Inspector during the run stops the Playwright script from executing further and resets the configured user agent and device emulation, so use the Playwright Inspector there.

Playwright is headless by default. --headed (or use: { headless: false }) shows the browser, and in library mode chromium.launch({ headless: false, slowMo: 100 }) slows every operation by 100 ms so you can follow along. In the test runner, slowMo is set through launchOptions in use. Headed runs are for local debugging; on CI, a trace gives you the same information without a display.

Set trace in use (or pass --trace on the command line). Playwright creates one trace per test run and keeps it according to the mode. "First run" is the initial attempt of a test and "retries" are the attempts caused by retries:

Which runs end up with a trace file is easy to verify. The deliberately broken test in failing/broken.spec.ts fails on every attempt, with one retry allowed. After each run, the output directory contains:

Source: Playwright: Recording a trace

A passing test with --trace on leaves a trace.zip in its directory as well. On the command line, npx playwright test --trace on forces the mode for one run and wins over the configuration; locally, UI Mode records traces automatically, so trace: 'on-first-retry' is mainly a CI setting. The trace of a failed test is also attached to the test result, so the list reporter prints the show-trace command to open it and the HTML report links it.

For more control, trace accepts an object. The mode takes any of the values above and the other keys choose what is captured:

A configuration that keeps richer traces for failures only (it extends the base config shown earlier):

Source: Playwright: testOptions.trace

With this configuration the failing test’s trace.zip contained aria/ entries (one JSON aria snapshot per action phase), screenshots/ and screencast/ images, the test source under src/ and the attachments, in addition to the usual trace.trace and trace.network files. The extra snapshots make the archive larger, so enable them where you need them, not everywhere.

Outside the test runner (library mode, or a test that manages its own context), use context.tracing. Its main methods are:

The runner already traces every context it creates when trace is on, and starting a second recording on such a context throws tracing.start: Tracing has been already started. A test that wants to drive tracing itself therefore turns the runner’s tracing off for that file:

Source: Playwright: Tracing

The official guidance is to prefer the configuration option in tests, because traces made with context.tracing do not record the test’s expect calls; the manual API is for scripts and for contexts that you create yourself. In this run the trace of the example contained the Search for a book group with the fill, click and a toHaveText expectation under it.

Source: Playwright: Trace viewer introduction

show-trace opens the viewer on a local file or a URL, so a trace stored as a CI artifact can be opened without downloading it first. show-report serves the last HTML report, where every test that recorded a trace has a trace icon next to it (and a Traces tab in the detail view). The viewer is also hosted at https://trace.playwright.dev/, a static progressive web app: drop a trace.zip on it or use the Select file button. The page loads the trace entirely in your browser and transmits nothing externally. To open a remote trace there, pass its URL as a query parameter, for example https://trace.playwright.dev/?trace=https://example.com/trace.zip; the usual CORS rules apply to the server that hosts the file.

The viewer shows the same panels as UI Mode (a trace is exactly what UI Mode shows live). For each selected action:

Since 1.59, npx playwright trace explores a trace from the terminal, which is useful over SSH, in CI logs and for coding agents that cannot open a window. The installed 1.64.1 lists these subcommands:

Running them on the trace of the flaky test’s first attempt (the one that failed):

Source: Playwright release notes: version 1.59

(Rows 3, 4 and 6 to 9, the fixture setup lines, were dropped from the excerpt.) The failing action is marked with the cross, and --errors-only lists just that row. Then ask for the action’s details, the requests, and the page at that moment:

Source: Playwright: Trace viewer

The listing of requests omits the Route column and the snapshot excerpt shows only part of the aria tree. One difference to note: the release notes for 1.59 pass the phase as trace snapshot 9 --name after, but the 1.64.1 command takes --phase before|action|after, as its --help shows; --name failed with an error. Trust npx playwright trace snapshot --help for the installed version. A trace recorded with context.tracing and the aria option opens the same way, and its snapshot output is the aria tree of the page at that action.

npx playwright codegen --help in 1.64.1 lists these options:

Source: Playwright: Emulation in codegen

Examples of the emulation flags from the official guide, for the Bookshelf:

Source: Playwright: Emulation in codegen

Note the viewport option’s name: the guide’s text calls it --viewport, but the command accepts --viewport-size, as the help output above shows.

Record the sign-in once, save the storage state, and load it in later sessions so you do not record the login again:

Source: Playwright: Preserve authenticated state

The first command saves cookies, localStorage and IndexedDB when you close the browser; the second restores them so the recording starts signed in. The file contains session credentials, so keep it out of version control (add it to .gitignore) and delete it when you finish. The same file works as the storageState of a test project, as described in Authentication & Test Isolation. These commands open a browser and so were not run for this page.

When the recording needs a context you configure yourself (for example browserContext.route() mocks), start a headed browser from a script and call page.pause(); the paused page opens the same Inspector with the codegen controls:

Source: Playwright: Record using custom setup

This script needs a display and was not run for this page. Two further sources of generated tests exist: the Record new and Record at cursor buttons in VS Code (which use the same generator and insert the code at your cursor) and, since 1.56, the generator agent described in Playwright Test Agents.

list prints one line per test as it finishes, with a tick or cross, the project, file, title and duration; retries appear as separate lines marked (retry #1). The excerpt below is the real output for the example project with one retry:

Source: Playwright: List reporter

(The failure details are printed after the list.) Its options are printSteps (print every test.step on its own line), printFailuresInline (show the failure right after the failed test instead of at the end) and omitTags (hide tags added to titles); each also has an environment variable (PLAYWRIGHT_LIST_PRINT_STEPS, PLAYWRIGHT_LIST_PRINT_FAILURES_INLINE, PLAYWRIGHT_LIST_OMIT_TAGS).

line is for large suites: it keeps a single, updating line with the last finished test and prints failures as they occur. When not attached to a terminal (as in the capture below) every progress line is printed:

Source: Playwright: Line reporter

dot prints one character per test run, which keeps CI logs short. The symbols are · passed, F failed, × failed or timed out and will be retried, ± passed on retry (flaky), T timed out and ° skipped. The run above printed:

Source: Playwright: Dot reporter

The cross followed by the plus-minus sign is the flaky test: it failed once and passed on the retry. The summary classifies it as flaky rather than passed or failed, which is exactly the information to watch in CI (see Running in CI/CD). --fail-on-flaky-tests (or failOnFlakyTests in the configuration) turns a flaky run into a failing one.

The HTML reporter writes a self-contained report folder. It lists every test by file and project with filters for passed, failed, flaky and skipped, shows each test’s errors, steps, attachments and trace, and, for tests that were retried, lists every attempt. By default it opens in the browser when a test failed (open: 'on-failure'); in CI set open: 'never'.

Source: Playwright: HTML reporter

The run wrote index.html, a data folder with attachments and a trace folder with the trace viewer assets to ex-debugging/my-report. show-report serves a report folder (or, since 1.60, a .zip archive of one, such as a CI artifact) on a local port. Options and their environment variables:

Treat a report folder like the traces inside it: it can contain page content, request bodies and screenshots, so publish it only where the same people may see the application’s data.

json writes one object with the configuration, the suites, specs and per-attempt results, and the aggregate statistics. junit writes JUnit-style XML for build servers that parse it. Both print to standard output unless you set a file:

Source: Playwright: JSON reporter

Or in the configuration, reporter: [['json', { outputFile: 'results.json' }], ['junit', { outputFile: 'results.xml' }]]. The relative path is resolved against the configuration’s directory. The stats object of the JSON file for the run above reported 4 expected, 0 unexpected, 0 skipped and 1 flaky test in a duration of about 3.8 seconds, and the flaky spec inside the file has status: "flaky" with two results, the first failed (retry 0) and the second passed (retry 1). The head of the JUnit file:

Source: Playwright: JUnit reporter

A flaky test is reported as passed (it has no failure element) with its attachments in system-out, so a JUnit-based dashboard does not show flakiness; use the JSON or HTML report for that. Since 1.59 the JUnit reporter distinguishes types of errors, so failures that used to be failure elements may now be error elements. The JUnit options are outputFile, stripANSIControlSequences, includeProjectInTestName, omitTags, plus the environment variables PLAYWRIGHT_JUNIT_OUTPUT_DIR, PLAYWRIGHT_JUNIT_OUTPUT_NAME, PLAYWRIGHT_JUNIT_OUTPUT_FILE, PLAYWRIGHT_JUNIT_SUITE_ID and PLAYWRIGHT_JUNIT_SUITE_NAME. For JSON, PLAYWRIGHT_JSON_OUTPUT_DIR, PLAYWRIGHT_JSON_OUTPUT_NAME and PLAYWRIGHT_JSON_OUTPUT_FILE do the same job; the full-file-path variable wins over the other two.

The blob reporter writes a zip with every detail of the run so that reports from several machines can be merged into any other report later. It exists for sharded runs:

Source: Playwright: Blob reporter

The run wrote blob-report/report.zip (about 37 KB for this suite) in the package directory. With sharding the file is named report-<hash>-<shard>.zip; the hash comes from --grep, --project and file filters so different invocations do not clash. Options: outputDir (PLAYWRIGHT_BLOB_OUTPUT_DIR; existing content is deleted before writing), fileName (PLAYWRIGHT_BLOB_OUTPUT_NAME) and outputFile (PLAYWRIGHT_BLOB_OUTPUT_FILE, which overrides the other two). When you run the same tests in different environments, set the top-level tag option (for example from a CI variable) so each merged report is labelled. The merge itself, and the CI recipe for it, are in Parallelism, Sharding & Retries; the merge-reports command above was not run on this page.

A custom reporter is a class that implements some of the Reporter methods, exported as the default export of a module:

Source: Playwright: Custom reporters

Use it by path, in the configuration (reporter: './my-reporter.ts') or on the command line. Run alone, it printed:

Source: Playwright: Reporter API

Note that onTestEnd fires once per attempt (the flaky test appears twice) and that status is the status of that attempt; the test’s overall outcome is test.outcome(). A custom reporter prints nothing unless it logs, and Playwright assumes it prints to the terminal, so no line reporter is added. To keep the usual console output and add your reporter on top, use --add-reporter:

Source: Playwright: Custom reporters

Other Reporter hooks exist for steps (onStepBegin, onStepEnd), standard output (onStdOut, onStdErr), errors outside tests (onError), printsToStdio() and, since 1.62, a preprocess() hook that runs before onBegin and can mark tests as skipped, excluded, fixed or failing. Steps carry subtitle and params (added in 1.63), which the trace viewer and the HTML report show next to the step title. Community reporters worth reading as examples include the Allure, GitHub Actions, Mail, ReportPortal and Monocart reporters.