Debugging Failures

When a fix comes back as needs attention — or you just want to see what happened yourself — everything the fixer saw is available to you too.

Start local

Every failure writes artifacts to local disk before any upload is attempted (default ./autowright-artifacts/, configurable via localArtifactDir). If storage or the service was down, this directory is your complete record.

What’s in the evidence

File	Use it to
screenshot-*.png	See the page as it looked in the last 3 moments before failure
dom.html	Search for the selector that failed — and what replaced it
network.json	Spot failed requests, redirects to login pages, 429s
console.json	Catch JS errors the page threw before your action failed
actions.json	Replay the run: every action, its arguments, and duration
browser-state.json	Check context state at failure time
trace.zip	Open in Playwright’s trace viewer (only if tracing was enabled)

Read the action log first

actions.json is the fastest orientation: scan to the last entry — that’s the failing action, with its selector, arguments, duration, and the error. Then open dom.html and search for that selector. Nine times out of ten the story is right there: the element is gone, renamed, or behind a new overlay.

Use the dashboard

The dashboard’s fix detail page assembles the same investigation for you: classification, failed step, page URL, error message, the agent’s summary of what it found, files it changed, and a link to the artifact bundle. For a needs-attention outcome, the agent’s summary usually names exactly what a human needs to decide.

When to enable tracing

autowright: {
  scriptId: 'portal-scraper',
  capture: { tracing: true },
}

Traces are the heaviest artifact, so they’re off by default. Turn them on when screenshots and the DOM aren’t enough — timing-sensitive failures, races with dynamic content, or anything where you need to scrub through the run step-by-step in Playwright’s trace viewer.

Manual snapshots mid-script

For diagnostics at a point of your choosing — not just at failure — grab the observer:

import { chromium, getObserver } from '@autowright/browser';

const page = await browser.newPage();
const observer = getObserver(page);

await page.goto('https://portal.example.com');
// suspicious state? capture it now, while things still "work"
await observer.captureSnapshot();

This is useful for intermittent failures: snapshot at checkpoints on every run, and when the failure finally happens you have the healthy runs to diff against.