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

server

string

Proxy server URL

username

string

Proxy authentication username

password

string

Proxy authentication password

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

status

number

HTTP status code

body

string

Response body

contentType

string

Content-Type header

headers

Record<string, string>

Additional headers

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';

Node.js API

CLI Reference

​BrowserManager

​Constructor

​Launch & Connection

​launch()

​isLaunched()

​close()

​Page & Frame Management

​getPage()

​getPages()

​hasPages()

​ensurePage()

​getFrame()

​switchToFrame()

​switchToMainFrame()

​Snapshots & Element Refs

​getSnapshot()

​getRefMap()

​getLocatorFromRef()

​getLocator()

​isRef()

​getLastSnapshot()

​setLastSnapshot()

​Browser Context & Settings

​getContext()

​getBrowser()

​getActiveIndex()

​setColorScheme()

​setViewport()

​setDeviceScaleFactor()

​clearDeviceMetricsOverride()

​getDevice()

​listDevices()

​Dialogs & Handlers

​setDialogHandler()

​clearDialogHandler()

​Request Tracking & Routing

​startRequestTracking()

​getRequests()

​clearRequests()

​addRoute()

​removeRoute()

​Headers

​setExtraHeaders()

​setScopedHeaders()

​clearScopedHeaders()

​Geolocation & Permissions

​setGeolocation()

​setPermissions()

​setOffline()

​Console & Error Tracking

​startConsoleTracking()

​getConsoleMessages()

​clearConsoleMessages()

​startErrorTracking()

​getPageErrors()

​clearPageErrors()

​Recording & Tracing

​startHarRecording()

​isHarRecording()

​startTracing()

​stopTracing()

​Storage State

​saveStorageState()

​getAndClearWarnings()

​Domain Filtering

​checkDomainAllowed()

​Utility Functions

​getDefaultTimeout()

​TypeScript Types

Build docs developers (and LLMs) love

BrowserManager

Constructor

Launch & Connection

launch()

isLaunched()

close()

Page & Frame Management

getPage()

getPages()

hasPages()

ensurePage()

getFrame()

switchToFrame()

switchToMainFrame()

Snapshots & Element Refs

getSnapshot()

getRefMap()

getLocatorFromRef()

getLocator()

isRef()

getLastSnapshot()

setLastSnapshot()

Browser Context & Settings

getContext()

getBrowser()

getActiveIndex()

setColorScheme()

setViewport()

setDeviceScaleFactor()

clearDeviceMetricsOverride()

getDevice()

listDevices()

Dialogs & Handlers

setDialogHandler()

clearDialogHandler()

Request Tracking & Routing

startRequestTracking()

getRequests()

clearRequests()

addRoute()

removeRoute()

Headers

setExtraHeaders()

setScopedHeaders()

clearScopedHeaders()

Geolocation & Permissions

setGeolocation()

setPermissions()

setOffline()

Console & Error Tracking

startConsoleTracking()

getConsoleMessages()

clearConsoleMessages()

startErrorTracking()

getPageErrors()

clearPageErrors()

Recording & Tracing

startHarRecording()

isHarRecording()

startTracing()

stopTracing()

Storage State

saveStorageState()

getAndClearWarnings()

Domain Filtering

checkDomainAllowed()

Utility Functions

getDefaultTimeout()

TypeScript Types