Skip to content
Autowright

Browser API

@autowright/browser is designed to be your only browser import. It exposes a drop-in chromium, two helpers for advanced use, and re-exports Playwright’s types so you never need import ... from 'playwright' alongside it.

chromium.launch(options)

Drop-in replacement for Playwright’s chromium.launch(). Accepts every Playwright LaunchOptions field plus one extra key:

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


const browser = await chromium.launch({
  headless: true,                    // any Playwright launch option
  autowright: {                      // the one Autowright addition
    scriptId: 'portal-scraper',
    serviceUrl: 'http://localhost:4400',
    repoUrl: 'https://github.com/your-org/scrapers',
    scriptPath: 'src/scraper.ts',
  },
});

Returns a standard Playwright Browser — newPage(), newContext(), contexts(), isConnected(), version() all work as usual. Under the hood:

  • browser.newPage() and context.newPage() return a proxied Page. The proxy is a Playwright Page — it intercepts action methods for capture and passes everything else through.
  • browser.close() first captures a final DOM snapshot and screenshot from every open page, then closes — so evidence survives even when your own error handler closes the browser.
  • If autowright.scriptId is omitted, it falls back to the AUTOWRIGHT_SCRIPT_ID env var; serviceUrl falls back to AUTOWRIGHT_SERVICE_URL, then http://localhost:4400.
  • Registration with the service is best-effort — if the service is down, the script still runs.

See Configuration for every autowright field.

getObserver(page)

Returns the PageObserver attached to a wrapped page (or undefined for a plain Playwright page). Useful for diagnostics and manual capture:

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


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


observer?.getActionLog();      // ActionEntry[] — every action so far
observer?.getNetworkLog();     // NetworkEntry[] — rolling network buffer
observer?.getConsoleLog();     // ConsoleEntry[] — rolling console buffer
await observer?.captureSnapshot();  // force a DOM + screenshot capture now

reportError(page, error, classification?, metadata?)

Manually report an error through the full Autowright pipeline — for failures Autowright can’t see, like a data-validation check in your own code:

import { reportError } from '@autowright/browser';


const rows = await page.locator('table tr').count();
if (rows === 0) {
  const err = new Error('Expected loan rows, table is empty');
  await reportError(page, err, 'DATA_VALIDATION', { portal: 'example' });
  throw err;   // reportError never throws for you — you stay in control
}

It captures a fresh DOM snapshot and screenshot, classifies the error (or uses the classification you pass), bundles and uploads artifacts, and POSTs the ErrorContext to the service — exactly like an automatic capture. If the page isn’t an Autowright-wrapped page, it logs a warning and returns without throwing.

Re-exported Playwright types

All common Playwright types come straight through, so this compiles with no playwright import:

import { chromium, type Page, type Locator, type LaunchOptions } from '@autowright/browser';


async function scrape(page: Page): Promise<void> { /* ... */ }

Re-exported: Browser, BrowserContext, BrowserType, Page, Frame, Locator, ElementHandle, JSHandle, Route, Request, Response, WebSocket, Worker, Dialog, Download, ConsoleMessage, FileChooser, Selectors, BrowserServer, CDPSession, Coverage, Video, Tracing, LaunchOptions, BrowserContextOptions, ViewportSize, Geolocation, HTTPCredentials.

Lower-level exports

For building on top of Autowright, the internals are exported too: wrapPage, PageObserver, classifyError, buildErrorContext, computeErrorHash, Reporter, TraceCapture, processArtifacts, saveArtifactsLocally, bundleArtifacts. Most scripts never need these — see Types for the data shapes they produce.