Tracing startHar and stopHar example
Example showing HAR recording: await context.tracing.startHar('trace.har'); const page = await context.newPage(); await page.goto('https://playwright.dev'); await context.tracing.stopHar();
Playwright · API reference · all subjects
tracing
22 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Tracing.groupEnd method
Tracing.groupEnd() is an async method available since v1.49 that closes the last group created by Tracing.group().
Tracing context.tracing API limitation
The context.tracing API captures browser operations and network activity, but it does not record test assertions like expect() calls. For a more complete trace that includes assertions, use Playwright Test configuration to enable tracing instead of the context.tracing API.
Tracing snapshots option for JavaScript
In JavaScript, the snapshots option for Tracing.start() can be a boolean or an object. When an object, it has optional fields: dom (boolean) to capture DOM snapshot on every action and record network activity; aria (boolean) to capture ARIA snapshot of the page on every action; screen (boolean) to capture a screenshot of the page on every action. Passing true is a shortcut for {dom: true}.
Tracing sources option with Java environment variable
For Java, the sources option (boolean, v1.17) specifies whether to include source files for trace actions. The list of directories with source code must be provided via the PLAYWRIGHT_JAVA_SRC environment variable, with paths separated by ';' on Windows and ':' on other platforms.
Tracing example basic flow
Example showing basic tracing flow: const browser = await chromium.launch(); const context = await browser.newContext(); await context.tracing.start({ screenshots: true, snapshots: true }); const page = await context.newPage(); await page.goto('https://playwright.dev'); expect(page.url()).toBe('https://playwright.dev'); await context.tracing.stop({ path: 'trace.zip' });
Tracing startChunk and stopChunk example
Example showing multiple trace chunks: await context.tracing.start({ screenshots: true, snapshots: true }); const page = await context.newPage(); await page.goto('https://playwright.dev'); await context.tracing.startChunk(); await page.getByText('Get Started').click(); await context.tracing.stopChunk({ path: 'trace1.zip' }); await context.tracing.startChunk(); await page.goto('http://example.com'); await context.tracing.stopChunk({ path: 'trace2.zip' });
Tracing HAR recording constraint
Only one HAR recording can be active at a time per Tracing instance.
Tracing class overview
The Tracing class is an API for collecting and saving Playwright traces that can be opened in Trace Viewer after a Playwright script runs. It is accessed via context.tracing and has been available since v1.12.
Tracing.start method signature and options
Tracing.start() is an async method that accepts an options object with the following parameters: screenshots (boolean, v1.12) to capture screenshots during tracing; snapshots (boolean or object with dom, aria, screen fields for JS/csharp/python, v1.12) to capture snapshots on every action; sources (boolean, v1.17) to include source files for trace actions; name (string, v1.12) to specify intermediate trace file name prefix inside tracesDir; title (string, v1.17) to show trace name in Trace Viewer; live (boolean, v1.59) to write trace to unarchived file updated in real time instead of caching into zip.
Tracing.stop method signature and options
Tracing.stop() is an async method that accepts an options object with path (path type) to export trace into the file with the given path.
Tracing.startChunk method signature and options
Tracing.startChunk() is an async method available since v1.15 that starts a new trace chunk. It accepts an options object with title (string, v1.17) to show trace name in Trace Viewer and name (string, v1.32) to specify intermediate trace file name prefix inside tracesDir. Used to record multiple traces on the same BrowserContext by calling Tracing.start() once and then creating multiple chunks with startChunk() and stopChunk().
Tracing.stopChunk method signature and options
Tracing.stopChunk() is an async method available since v1.15 that stops the current trace chunk. It accepts an options object with path (path type) to export trace collected since the last startChunk() call into the file with the given path.
Tracing.startHar method signature and options
Tracing.startHar() is an async method available since v1.60 that starts recording HTTP Archive (HAR) of network activity. It takes a path parameter (path type) for the filesystem location to write the HAR file. Returns a Disposable. It accepts an options object with: content (HarContentPolicy with values 'omit', 'embed', or 'attach', defaults to 'attach' for .zip files and 'embed' otherwise); mode (HarMode with values 'full' or 'minimal', defaults to 'full'); urlFilter (string or RegExp pattern to filter stored requests, defaults to none); resourcesDir (path, JS only, v1.60) to place response bodies in a directory instead of next to HAR file when content is 'attach'.
Tracing.stopHar method
Tracing.stopHar() is an async method available since v1.60 that stops HAR recording and saves the HAR file to the path given to Tracing.startHar().
Tracing.group method signature and options
Tracing.group() is an async method available since v1.49 that creates a new group within the trace, assigning subsequent API calls to this group until Tracing.groupEnd() is called. Returns a Disposable. It accepts a name parameter (string) for the group name shown in trace viewer and an optional location object (with file string, line int, and column int) to specify custom location for the group in the trace viewer. Groups can be nested and will be visible in the trace viewer. The recommended alternative is to use test.step() when available.
Trace output files generated by Playwright
When tracing starts, Playwright creates a traces/ directory with three types of files: trace-{timestamp}.trace contains the action log with every action performed, DOM snapshots before and after each action, screenshots, timing information, console messages, and source locations; trace-{timestamp}.network contains the network log with all HTTP requests and responses, headers, bodies, timing details (DNS, connect, TLS, TTFB, download), resource sizes, and failed requests; resources/ directory caches images, fonts, stylesheets, scripts, response bodies for replay, and assets needed to reconstruct page state.
What traces capture - categories
Traces capture five main categories: Actions (clicks, fills, hovers, keyboard input, navigations); DOM (full DOM snapshot before and after each action); Screenshots (visual state at each step); Network (all requests, responses, headers, bodies, timing); Console (all console.log, warn, error messages); Timing (precise timing for each operation).
Trace vs Video vs Screenshot comparison
Traces use .trace file format and support DOM inspection, network details, step-by-step replay, with medium file size and are best for debugging. Videos use .webm format without DOM inspection or network details, have continuous replay instead of step-by-step, are large file size and best for demos. Screenshots use .png/.jpeg format without DOM or network details, capture only a single frame, are small file size and best for quick capture.
Tracing best practices
Start tracing before the problem occurs and trace the entire flow, not just the failing step, to capture full context. Clean up old traces regularly as they can consume significant disk space; example command: find .playwright-cli/traces -mtime +7 -delete removes traces older than 7 days.
Tracing limitations and overhead
Traces add overhead to automation execution. Large traces can consume significant disk space. Some dynamic content may not replay perfectly.
Tracing basic workflow with playwright-cli
The basic workflow for tracing is: start with playwright-cli tracing-start, perform actions like open, click, and fill, then stop with playwright-cli tracing-stop. This captures the entire execution flow for debugging and analysis.