Skip to main content
Browser handles expose resource helpers for the things a real browser session produces: files, downloads, dialogs, permissions, recordings, events, pages, and blockers.
const browser = await web.browser.create({ recording: true });

await browser.playwright.execute({
  code: `await page.goto("https://example.com/report");`,
});

const downloads = await browser.downloads.list();
const events = await browser.events({ limit: 50 });

Files

Use files to stage host-provided bytes for browser-side upload workflows.
const file = await browser.files.createFromPath("./invoice.csv", {
  mimeType: "text/csv",
});
MethodSignatureDescription
browser.files.create(input: CreateBrowserFileOptions) => Promise<BrowserFileSummary>Stage a file from memory.
browser.files.createFromPath(path: string, options?: CreateBrowserFileFromPathOptions) => Promise<BrowserFileSummary>Stage a file from a local path.
browser.files.list(options?: BrowserArtifactListOptions) => Promise<ListBrowserFilesResponse>List staged files.
browser.files.get(fileId: FileId, options?: { signal?: AbortSignal }) => Promise<BrowserFileSummary>Fetch staged file metadata.
browser.files.content(fileId: FileId, options?: { signal?: AbortSignal }) => Promise<Uint8Array>Download staged file bytes.
browser.files.delete(fileId: FileId, options?: { signal?: AbortSignal }) => Promise<void>Delete a staged file.
CreateBrowserFileOptions fields:
FieldDescription
nameFile name. Required.
mimeTypeOptional MIME type.
base64Base64-encoded contents.
bytesRaw bytes.
signalAbort signal.

Downloads

const list = await browser.downloads.list();
const [first] = list.data;

if (first) {
  await browser.downloads.save(first.id, "./downloads/report.pdf", {
    overwrite: true,
    maxBytes: 25_000_000,
  });
}
MethodSignatureDescription
browser.downloads.list(options?: BrowserArtifactListOptions) => Promise<ListBrowserDownloadsResponse>List browser downloads.
browser.downloads.get(downloadId: DownloadId, options?: { signal?: AbortSignal }) => Promise<BrowserDownloadSummary>Fetch download metadata.
browser.downloads.content(downloadId: DownloadId, options?: { signal?: AbortSignal; maxBytes?: number }) => Promise<Uint8Array>Fetch download bytes, optionally capped by maxBytes.
browser.downloads.save(downloadId: DownloadId, outputPath: string, options?: BrowserDownloadSaveOptions) => Promise<BrowserDownloadSaveResult>Save download bytes to a local file.
BrowserDownloadSaveOptions:
FieldDescription
overwriteReplace an existing output file. Defaults to false.
maxBytesMaximum bytes to save.
signalAbort signal.

Dialogs

const dialogs = await browser.dialogs.list({ status: "open" });

for (const dialog of dialogs.data) {
  await browser.dialogs.dismiss(dialog.id);
}
MethodSignatureDescription
browser.dialogs.list(options?: { pageId?: PageId; status?: "open" | "recent"; cursor?: string; limit?: number; signal?: AbortSignal }) => Promise<ListBrowserDialogsResponse>List JavaScript dialogs.
browser.dialogs.accept(dialogId: DialogId, options?: { promptText?: string; includeState?: "auto" | "never" | "none" | "compact" | "full"; maxStateChars?: number; signal?: AbortSignal }) => Promise<BrowserDialogResponse>Accept a dialog. promptText applies to prompt dialogs.
browser.dialogs.dismiss(dialogId: DialogId, options?: { includeState?: "auto" | "never" | "none" | "compact" | "full"; maxStateChars?: number; signal?: AbortSignal }) => Promise<BrowserDialogResponse>Dismiss a dialog.

Permissions

Use permission helpers when a workflow needs explicit browser permissions such as geolocation.
MethodSignatureDescription
browser.permissions.grant(request: BrowserPermissionGrant & { geolocation?: BrowserGeolocation; signal?: AbortSignal }) => Promise<BrowserPermissionsResponse>Grant permissions.
browser.permissions.deny(request: BrowserPermissionGrant & { signal?: AbortSignal }) => Promise<BrowserPermissionsResponse>Deny permissions.
browser.permissions.clear(request?: BrowserClearPermissionsRequest & { signal?: AbortSignal }) => Promise<BrowserPermissionsResponse>Clear permission overrides.
browser.permissions.reset(request?: BrowserClearPermissionsRequest & { signal?: AbortSignal }) => Promise<BrowserPermissionsResponse>Alias for clearing permission overrides.

Recordings

Recording methods are useful only for browsers created with recording: true.
const recording = await browser.recordings.get();
const segments = await browser.recordings.segments();
await browser.recordings.download("wc_rec_...", "./recordings", { overwrite: true });
MethodSignatureDescription
browser.recordings.get(options?: { signal?: AbortSignal }) => Promise<BrowserRecordingResponse>Fetch recording summary.
browser.recordings.segments(options?: RecordingListOptions) => Promise<ListRecordingSegmentsResponse>List recording segments.
browser.recordings.segment(segmentId: RecordingSegmentId, options?: { signal?: AbortSignal }) => Promise<RecordingSegmentManifestResponse>Fetch a segment manifest.
browser.recordings.events(segmentId: RecordingSegmentId, options?: RecordingEventsOptions) => Promise<ListRecordingEventsResponse>List events for one segment.
browser.recordings.frame(segmentId: RecordingSegmentId, frameKey: string, options?: { signal?: AbortSignal }) => Promise<Uint8Array>Fetch a recorded frame.
browser.recordings.download(segmentId: RecordingSegmentId, outputDir: string, options?: RecordingDownloadOptions) => Promise<RecordingDownloadResult>Download manifest, events, and frames to local files.
RecordingDownloadResult contains segmentId, outputDir, manifestPath, eventsPath, and framePaths.

Events

for await (const event of browser.streamEvents({ pollIntervalMs: 1000 })) {
  console.log(event.type, event.severity);
}
MethodSignatureDescription
browser.events(options?: BrowserEventsOptions) => Promise<ListBrowserEventsResponse>Fetch browser events.
browser.streamEvents(options?: BrowserEventStreamOptions) => AsyncIterable<BrowserEvent>Poll events as an async stream.
BrowserEventsOptions fields:
FieldDescription
cursorPagination cursor.
limitResults per page.
sinceLower time bound.
untilUpper time bound.
typeEvent type filter.
categoryEvent category filter.
pageIdPage filter.
severityEvent severity filter.
visibilityEvent visibility filter.
signalAbort signal.
BrowserEventStreamOptions also accepts pollIntervalMs.

Pages

const pages = await browser.pages();
const active = pages.find((page) => page.active);
browser.pages(options?) returns page summaries with:
FieldDescription
idPage ID.
browserIdBrowser ID.
urlCurrent page URL.
titleCurrent page title.
activeWhether this page is the active page.

CAPTCHA and blockers

MethodSignatureDescription
browser.captcha.status(options?: { signal?: AbortSignal }) => Promise<BrowserStatusResponse>Fetch compact blocker status.
browser.captcha.resolve(options?: BrowserCaptchaResolveOptions) => Promise<ResolveCaptchaResponse>Ask the runtime to resolve a detected CAPTCHA blocker.
BrowserCaptchaResolveOptions accepts resolver options plus signal.