Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
When an AI agent fails in a browser, the final error usually marks only the stopping point. A browser session trace gives you the missing timeline: what the page looked like, which action ran, what the browser logged, and which network requests succeeded or failed. Use that evidence to locate the divergence, then pair it with the agent’s model and tool trace to understand why the agent chose that action.
What a browser session trace records
A trace is a time-ordered record of an automation run. In Playwright’s agent CLI tracing, the recorded evidence can include action records, DOM snapshots before and after actions, screenshots, console messages, timing information, and a separate log of network requests and responses. The agent CLI tracing documentation describes these capture categories and the commands that produce them.
This is more useful than a screenshot taken at the end. A screenshot shows one visual state; a trace can show that a button existed before a click, disappeared after navigation, produced a console error, or triggered a request that returned an unexpected status. The trace narrows the cause, but it does not automatically explain it. You still need to interpret the evidence and verify a fix against the live system or a controlled reproduction.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Evidence you can inspect per step
- Action and timing: the navigation, click, fill, wait, or other operation and how long it took.
- DOM snapshots: the page structure immediately before and after an action, useful when locators stop matching.
- Screenshots: visual confirmation of overlays, redirects, empty states, or responsive-layout changes.
- Console output: JavaScript errors and warnings that may explain a broken interaction.
- Network activity: request and response details that reveal failed APIs, redirects, authentication problems, or blocked resources.
How to capture a Playwright trace
For a Node.js automation project, start and stop tracing around the run you need to diagnose. This example records screenshots, snapshots, and source files, then writes a ZIP archive for the viewer.
#1 Best Overall
import { chromium } from 'playwright';
const browser = await chromium.launch();
const context = await browser.newContext();
await context.tracing.start({
screenshots: true,
snapshots: true,
sources: true
});
try {
const page = await context.newPage();
await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
await page.getByRole('link', { name: 'More information...' }).click();
await page.waitForLoadState('domcontentloaded');
} finally {
await context.tracing.stop({ path: 'trace.zip' });
await browser.close();
}Open the resulting archive with Playwright Trace Viewer. The official Trace Viewer documentation explains the GUI, including selecting an action, inspecting snapshots and screenshots, and viewing console messages and filtered logs around that action.
Capture failed tests through Playwright Test
The lower-level context.tracing API captures browser operations and network activity, but it does not record test assertions such as expect calls, as Playwright states in its tracing API documentation. If you are debugging tests, enable tracing in Playwright Test configuration so the failure artifact includes the test-run context recommended by Playwright.
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
trace: 'retain-on-failure'
}
});retain-on-failure keeps traces for failed tests while avoiding an archive for every successful run. For a particularly intermittent defect, use an always-on mode temporarily, but budget for larger files and more sensitive data.
Recommended Free Tools
Reading a trace to find the real failure
- Start at the first unexpected state. Select actions in order and compare the before/after DOM snapshots. The first divergence is usually more informative than the final timeout.
- Check the visual layer. Look for cookie dialogs, newsletter prompts, chat bubbles, modal backdrops, responsive breakpoints, or a redirect to a sign-in page covering the intended control.
- Inspect locator evidence. If a click timed out, determine whether the target was absent, hidden, covered, detached, or duplicated. A changed accessible name often indicates a product-copy or localization change rather than a timing problem.
- Read console messages at that timestamp. A client-side exception can prevent a menu or form from rendering even though navigation itself succeeded.
- Filter the network log. Find the request initiated by the action, then check its URL, status, redirect chain, response body, and relevant headers. A 401, 403, 429, 5xx response, CORS error, or stalled request points to a different fix than a bad locator.
- Compare the agent’s intended action. Record the model response and tool arguments separately, then ask whether the agent selected a wrong element, acted before a required wait, or received an ambiguous page.
- Reproduce and verify. Run the smallest deterministic script that reaches the suspected step. A trace is evidence from one configured run; a missing event is not proof that the event never occurred.
Browser traces versus agent traces
These two trace types answer different questions and should not be treated as interchangeable.
| Trace layer | Primary question | Typical evidence | Common gap |
|---|---|---|---|
| Browser or page trace | What happened in the website and network? | Actions, DOM snapshots, screenshots, console messages, timings, requests and responses | It may not contain the model’s reasoning, prompt, or tool-selection decision |
| Agent trace | What did the model and orchestration workflow decide? | Turns, model responses, tool calls, arguments, results, handoffs, guardrails, and custom events | It may not show the exact rendered page or network failure |
OpenAI’s Agents API tracing guide models sessions as turns and spans, with model responses and tool calls recorded under the agent. The Agents SDK tracing guide documents generations, tool calls, handoffs, guardrails, and custom events. If both systems record timestamps and step identifiers, align their timelines: a tool call at 10:02:14 can be compared with the browser click and resulting request at the same point. That alignment is an engineering practice, not an automatic correlation supplied by either product.
Instrumentation choices that change your diagnosis
Snapshots, screenshots, or both?
DOM snapshots are best for locator and content questions; screenshots expose visual obstruction and layout issues. Enable both for failures involving consent banners, canvas content, responsive design, or overlays. Screenshots alone cannot reveal a hidden DOM state, while snapshots may not show a pixel-level obstruction.
How much network detail?
Request and response logs are invaluable for API failures, but they can include headers and bodies. The CLI documentation describes those network records, so treat the archive as potentially sensitive. Define who may download traces, where they are stored, how long they are retained, and how your team redacts credentials or personal data. Do not assume a universal redaction policy.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Assertions and application telemetry
Because the raw tracing API does not capture expect assertions, add assertion results, business identifiers, and agent step IDs to your own test or agent logs. Keep those identifiers stable enough to join with browser timestamps without putting secrets into the trace.
Sampling and performance
Tracing adds disk I/O and archive size, especially with frequent screenshots, source files, and large response bodies. Use failure-only retention in routine CI, capture a short window around a suspected step, and run an always-on capture only while reproducing an intermittent issue. Measure your own pipeline’s overhead; the documentation does not establish one universal performance cost.
Privacy and security checklist
- Assume cookies, authorization headers, form values, and response bodies may be present.
- Keep trace archives out of public issue attachments and unrestricted object-storage buckets.
- Restrict viewer access to the engineers investigating the incident.
- Set a retention period and delete archives after the bug is resolved.
- Use test accounts and synthetic data where possible; never place production secrets in a reproduction script.
- Review a trace before sharing it with a vendor or an external contractor.
Behavioral traces can also reveal information beyond page content. A 2026 paper, “Known By Their Actions: Fingerprinting LLM Browser Agents via UI Traces,” reported up to 96% F1 identification of the underlying model from actions and interaction timings across 14 frontier LLMs and four web environments. That is a study-specific result, not a guarantee about every agent or trace system, but it is a reason to treat action timing and sequences as potentially identifying data. See the paper at arXiv.
Common failures and practical fixes
“The trace file is missing”
Confirm that the stop call runs in a finally block and that the process has permission to write the destination. In parallel tests, use a unique path per worker so one run does not overwrite another.
The archive opens but has no useful snapshots
Check that snapshots: true and screenshots: true were enabled before the actions. A trace can contain only the events captured after tracing started; it cannot reconstruct earlier page states.
A click times out even though the screenshot shows the button
Inspect the DOM snapshot for duplicate elements, an iframe boundary, a disabled state, or an overlay intercepting pointer events. Use a role- or label-based locator, switch to the correct frame, and wait for the application’s readiness condition rather than adding an arbitrary long delay.
The page is blank or unexpectedly logged out
Use the network log to distinguish a failed document request, an authentication redirect, a blocked resource, and an application exception. Reproduce with the same context configuration, cookies, headers, user agent, timezone, and geolocation before changing the script.
The agent keeps repeating a wrong action
Compare the agent trace’s tool arguments with the browser snapshot supplied to the model. If the page changed after the snapshot, provide a fresh observation after each navigation or mutation. Add a guard that stops after a bounded number of retries and records the current URL, title, and visible error text.
Or skip the browser setup
If you only need a clean visual record of a page rather than a full interactive trace, ScreenshotNeo provides a single-call screenshot API at ScreenshotNeo. A GET request returns PNG, JPEG, WebP, or PDF output. Before capture it accepts the cookie or consent banner like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each cleanup step can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and whether it was billed. It also offers an MCP server for AI agents with take_screenshot, get_page_info, and capture_pdf tools.
See the full parameter list in the ScreenshotNeo documentation. This runnable cURL example captures Stripe as WebP:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython:
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)Node.js:
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);For automation workflows, options include full-page capture with lazy images loaded, CSS-selector element capture, dark mode, 12 device presets or any viewport, retina scale, PDF paper size and page ranges, custom CSS and JavaScript, clicks, selector or network-idle waits, ad and tracker blocking, custom headers and cookies, timezone and geolocation, transparent backgrounds, resizing, chosen cache TTLs, signed public-image links, asynchronous jobs with signed webhooks, bulk capture of up to 100 URLs per call, a usage API, and an OpenAPI specification. Existing parameter names used by other screenshot APIs also work, which can simplify migration.
Best Value
The Free plan includes 1,000 shots per month with no card. Paid plans start at $5 for 3,000 shots; yearly billing provides two months free. Create a free ScreenshotNeo account to start.
Free tools Windows power users keep installed
One-click scans. No signup required.
Using traces in an incident workflow
- Give every agent run a unique run ID and record it in the agent span and browser test output.
- Capture a trace only after the browser context is fully configured, including authentication and locale.
- On failure, preserve the trace, the agent tool/model log, the commit, and the environment details as one incident bundle.
- In Trace Viewer, mark the first divergent action and copy the exact URL, locator, console error, and request status into the incident ticket.
- Reproduce with a minimal script, apply one change, and capture a new trace to verify that the divergence is gone.
- Delete or restrict the artifacts according to your retention policy when the investigation closes.
This workflow keeps the layers distinct: the browser trace proves what was observed and executed, while the agent trace explains the model and orchestration decisions that led there.
Frequently Asked Questions
Can a browser trace prove the root cause of an agent failure?
No. It supplies recorded evidence from one run. You must interpret the snapshots, console, network records, and agent log, then verify the suspected cause in a controlled reproduction.
Do Playwright traces include test assertions?
The Playwright context.tracing API does not record assertions such as expect calls. Playwright recommends Playwright Test tracing configuration for fuller failure context.
Should I share a trace in a public bug report?
Only after reviewing it. Network records may contain headers and bodies, and traces can expose cookies, form data, or behavioral patterns. Restrict access and redact or replace sensitive data first.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
