BrowserManager

Core class for managing Playwright browser instances and page interactions

BrowserManager

The BrowserManager class manages the Playwright browser lifecycle with support for multiple tabs/windows, element refs, snapshots, and advanced browser automation features.

Constructor

import { BrowserManager } from '@agentic-labs/browser';

const manager = new BrowserManager();

Launch & Connection

launch()

Launches a browser instance or connects to an existing one.

await manager.launch({
  headless: true,
  browser: 'chromium',
  viewport: { width: 1280, height: 720 }
});

options · LaunchCommand

Launch configuration options

headless · boolean

Run browser in headless mode (default: true)

browser · 'chromium' | 'firefox' | 'webkit'

Browser engine to launch (default: ‘chromium’)

viewport · { width: number; height: number } | null

Initial viewport size. Set to null to disable viewport emulation

cdpPort · number

Connect to Chrome DevTools Protocol on this port

cdpUrl · string

Connect to CDP via WebSocket URL (ws:// or wss://)

autoConnect · boolean

Auto-discover and connect to running Chrome instance

provider · 'browserbase' | 'browseruse' | 'kernel'

Cloud browser provider

extensions · string[]

Chrome extension paths to load (Chromium only)

profile · string

Path to persistent browser profile directory

storageState · string

Path to storage state JSON file for session persistence

proxy · object

Proxy configuration

headers · Record<string, string>

Extra HTTP headers to send with every request

userAgent · string

Custom user agent string

colorScheme · 'light' | 'dark' | 'no-preference'

Persistent color scheme preference

downloadPath · string

Directory for browser downloads

allowedDomains · string[]

Domain allowlist for navigation (blocks other domains)

allowFileAccess · boolean

Enable file:// URL access (Chromium only)

ignoreHTTPSErrors · boolean

Ignore HTTPS certificate errors

args · string[]

Additional browser launch arguments

isLaunched()

Check if the browser is currently launched.

const launched = manager.isLaunched();

return · boolean

True if browser is launched

close()

Close the browser and cleanup resources.

await manager.close();

Page & Frame Management

getPage()

Get the current active page. Throws if browser is not launched.

const page = manager.getPage();

return · Page

The active Playwright Page instance

getPages()

Get all open pages.

const pages = manager.getPages();

return · Page[]

Array of all Page instances

hasPages()

Check if the browser has any usable pages.

const hasPagesOpen = manager.hasPages();

return · boolean

True if pages exist

ensurePage()

Ensure at least one page exists. Creates a new page if all were closed.

await manager.ensurePage();

getFrame()

Get the current frame (or page’s main frame if no frame is selected).

const frame = manager.getFrame();

return · Frame

Current Frame instance

switchToFrame()

Switch to a frame by selector, name, or URL.

await manager.switchToFrame({ selector: 'iframe#myframe' });
await manager.switchToFrame({ name: 'payment' });
await manager.switchToFrame({ url: /checkout/ });

options · object

selector · string

CSS selector for frame element

name · string

Frame name attribute

url · string

Frame URL pattern

switchToMainFrame()

Switch back to the main frame.

manager.switchToMainFrame();

Snapshots & Element Refs

getSnapshot()

Get an enhanced accessibility snapshot with element refs.

const snapshot = await manager.getSnapshot({
  interactive: true,
  cursor: true,
  maxDepth: 5,
  compact: true
});

console.log(snapshot.tree);
console.log(snapshot.refs);

options · object

interactive · boolean

Only include interactive elements (buttons, links, inputs)

cursor · boolean

Include cursor-interactive elements (cursor:pointer, onclick)

maxDepth · number

Maximum depth of tree to include

compact · boolean

Remove structural elements without meaningful content

selector · string

CSS selector to scope the snapshot

return · EnhancedSnapshot

tree · string

Accessibility tree as formatted text

refs · RefMap

Map of element refs to locator data

getRefMap()

Get the cached ref map from the last snapshot.

const refs = manager.getRefMap();

return · RefMap

Ref map with element locator information

getLocatorFromRef()

Get a Playwright locator from a ref (e.g., “e1”, “@e1”, “ref=e1”).

const locator = manager.getLocatorFromRef('@e5');
if (locator) {
  await locator.click();
}

refArg · string

Element ref string (e1, @e1, or ref=e1)

return · Locator | null

Playwright Locator or null if ref doesn’t exist

getLocator()

Get a locator - supports both refs and regular selectors.

const locator = manager.getLocator('@e3'); // by ref
const locator2 = manager.getLocator('#submit-button'); // by CSS

selectorOrRef · string

Element ref or CSS selector

return · Locator

Playwright Locator instance

isRef()

Check if a selector looks like a ref.

const isElementRef = manager.isRef('@e1'); // true
const isCss = manager.isRef('.button'); // false

selector · string

Selector string to check

return · boolean

True if string is a ref format

getLastSnapshot()

Get the last snapshot tree text (empty string if no snapshot has been taken).

const lastTree = manager.getLastSnapshot();

return · string

Last snapshot tree text

setLastSnapshot()

Update the stored snapshot (used by diff to keep the baseline current).

manager.setLastSnapshot(newSnapshotTree);

snapshot · string

Snapshot tree text to store

Browser Context & Settings

getContext()

Get the current browser context.

const context = manager.getContext();

return · BrowserContext | null

Playwright BrowserContext or null

getBrowser()

Get the current browser instance.

const browser = manager.getBrowser();

return · Browser | null

Playwright Browser instance or null

getActiveIndex()

Get the current active page index.

const index = manager.getActiveIndex();

return · number

Zero-based index of active page

setColorScheme()

Set the persistent color scheme preference. Applied to all new pages and contexts.

manager.setColorScheme('dark');

scheme · 'light' | 'dark' | 'no-preference' | null

Color scheme to apply

setViewport()

Set the viewport size.

await manager.setViewport(1920, 1080);

width · number

Viewport width in pixels

height · number

Viewport height in pixels

setDeviceScaleFactor()

Set device scale factor (devicePixelRatio) via CDP.

await manager.setDeviceScaleFactor(2, 1920, 1080, false);

deviceScaleFactor · number

Device pixel ratio (e.g., 2 for Retina)

width · number

Viewport width

height · number

Viewport height

mobile · boolean

Enable mobile emulation (default: false)

clearDeviceMetricsOverride()

Clear device metrics override to restore default devicePixelRatio.

await manager.clearDeviceMetricsOverride();

getDevice()

Get device descriptor by name.

const device = manager.getDevice('iPhone 13 Pro');

deviceName · string

Device name (e.g., “iPhone 13 Pro”)

return · DeviceDescriptor | undefined

Playwright device descriptor or undefined

listDevices()

List all available device names.

const devices = manager.listDevices();

return · string[]

Array of device names

Dialogs & Handlers

setDialogHandler()

Set up automatic dialog (alert/confirm/prompt) handler.

manager.setDialogHandler('accept', 'My prompt text');
manager.setDialogHandler('dismiss');

response · 'accept' | 'dismiss'

How to respond to dialogs

promptText · string

Text to enter for prompt dialogs (when accepting)

clearDialogHandler()

Remove the dialog handler.

manager.clearDialogHandler();

Request Tracking & Routing

startRequestTracking()

Start tracking all network requests.

manager.startRequestTracking();

getRequests()

Get tracked requests, optionally filtered.

const allRequests = manager.getRequests();
const apiRequests = manager.getRequests('/api/');

filter · string

Optional URL substring filter

return · TrackedRequest[]

Array of tracked request data

clearRequests()

Clear all tracked requests.

manager.clearRequests();

addRoute()

Add a route to intercept and mock requests.

await manager.addRoute('**/api/user', {
  response: {
    status: 200,
    body: JSON.stringify({ name: 'Test User' }),
    contentType: 'application/json'
  }
});

await manager.addRoute('**/analytics', { abort: true });

url · string

URL pattern to intercept

options · object

response · object

Mock response configuration

abort · boolean

Abort the request instead of mocking

removeRoute()

Remove a route by URL pattern (or all routes if no URL provided).

await manager.removeRoute('**/api/user');
await manager.removeRoute(); // remove all

url · string

Optional URL pattern to remove (omit to remove all)

Headers

setExtraHeaders()

Set extra HTTP headers for all requests.

await manager.setExtraHeaders({
  'Authorization': 'Bearer token123',
  'X-Custom-Header': 'value'
});

headers · Record<string, string>

Headers to set

setScopedHeaders()

Set headers only for requests matching an origin.

await manager.setScopedHeaders('api.example.com', {
  'Authorization': 'Bearer token123'
});

origin · string

Origin hostname or URL

headers · Record<string, string>

Headers to add for matching requests

clearScopedHeaders()

Clear scoped headers for an origin (or all if no origin specified).

await manager.clearScopedHeaders('api.example.com');
await manager.clearScopedHeaders(); // clear all

origin · string

Optional origin to clear (omit to clear all)

Geolocation & Permissions

setGeolocation()

Set geolocation coordinates.

await manager.setGeolocation(37.7749, -122.4194, 100);

latitude · number

Latitude coordinate

longitude · number

Longitude coordinate

accuracy · number

Optional accuracy in meters

setPermissions()

Grant or deny browser permissions.

await manager.setPermissions(['geolocation', 'notifications'], true);
await manager.setPermissions([], false); // revoke all

permissions · string[]

Permission names to grant/deny

grant · boolean

True to grant, false to revoke

setOffline()

Set offline mode.

await manager.setOffline(true); // go offline
await manager.setOffline(false); // go online

offline · boolean

Enable/disable offline mode

Console & Error Tracking

startConsoleTracking()

Start tracking console messages.

manager.startConsoleTracking();

getConsoleMessages()

Get all tracked console messages.

const messages = manager.getConsoleMessages();

return · ConsoleMessage[]

Array of console messages with type, text, and timestamp

clearConsoleMessages()

Clear all tracked console messages.

manager.clearConsoleMessages();

startErrorTracking()

Start tracking page errors.

manager.startErrorTracking();

getPageErrors()

Get all tracked page errors.

const errors = manager.getPageErrors();

return · PageError[]

Array of page errors with message and timestamp

clearPageErrors()

Clear all tracked page errors.

manager.clearPageErrors();

Recording & Tracing

startHarRecording()

Start HAR (HTTP Archive) recording.

await manager.startHarRecording();

isHarRecording()

Check if HAR recording is active.

const recording = manager.isHarRecording();

return · boolean

True if recording

startTracing()

Start Playwright tracing.

await manager.startTracing({
  screenshots: true,
  snapshots: true
});

options · object

screenshots · boolean

Include screenshots

snapshots · boolean

Include DOM snapshots

stopTracing()

Stop tracing and save to file.

await manager.stopTracing('./trace.zip');

path · string

Optional output path for trace file

Storage State

saveStorageState()

Save storage state (cookies, localStorage) to file.

await manager.saveStorageState('./state.json');

path · string

Output file path

getAndClearWarnings()

Get and clear launch warnings (e.g., decryption failures).

const warnings = manager.getAndClearWarnings();

return · string[]

Array of warning messages

Domain Filtering

checkDomainAllowed()

Check if a URL is allowed by the domain allowlist. Throws if blocked.

try {
  manager.checkDomainAllowed('https://example.com');
} catch (error) {
  console.error('Domain blocked:', error.message);
}

url · string

URL to check

Utility Functions

getDefaultTimeout()

Get the default Playwright timeout in milliseconds.

import { getDefaultTimeout } from '@agentic-labs/browser';

const timeout = getDefaultTimeout(); // 25000 by default

return · number

Timeout in milliseconds (configurable via AGENT_BROWSER_DEFAULT_TIMEOUT env var)

TypeScript Types

import type {
  LaunchCommand,
  ScreencastFrame,
  ScreencastOptions,
  EnhancedSnapshot,
  RefMap
} from '@agentic-labs/browser';