Playwright Browser Context | BCTRL

All Browser Context methods available when using the Playwright driver.

Access via runtime.browserContext after launching a Playwright runtime.

How these methods work over HTTP

Every method below is a remote call. The SDK translates it into a structured step sent to a single endpoint:

POST /v1/workspaces/{workspaceId}/execute

1 {
2   "runtime": "my-browser",
3   "steps": [
4     {
5       "call": "context.goto",
6       "args": ["https://example.com"]
7     }
8   ]
9 }

The call field maps directly to the method name. args is a JSON array of the method’s arguments. You can batch multiple steps in one request.

Waiting

waitForEvent(event, optionsOrPredicate?)

Waits for event to fire and passes its value into the predicate function.

Returns when the predicate returns truthy value. Will throw an error if the context closes before the event is fired.

1 await runtime.browserContext.waitForEvent('...');

Parameter	Type	Required	Description
`event`	`string`	Yes	—
`optionsOrPredicate`	`PlaywrightWaitForEventOptions \| ((event: unknown) => boolean)`	No	—

Returns T

Upstream docs

Cookies

addCookies(cookies)

Adds cookies into this browser context. All pages within this context will have these cookies installed.

1 await runtime.browserContext.addCookies(/* PlaywrightCookie[] */);

Parameter	Type	Required	Description
`cookies`	`PlaywrightCookie[]`	Yes	—

Upstream docs

cookies(urls?)

Returns cookies for the specified URLs, or all cookies if no URLs are specified.

1 await runtime.browserContext.cookies();

Parameter	Type	Required	Description
`urls`	`string \| string[]`	No	—

Returns PlaywrightCookie[]

Upstream docs

clearCookies(options?)

Removes cookies from context. Accepts optional filter to remove specific cookies.

If no options are provided, removes all cookies from the context.

1 await runtime.browserContext.clearCookies();

Parameter	Type	Required	Description
`options`	`PlaywrightClearCookiesOptions`	No	—

Upstream docs

Lifecycle

pages()

Returns all open pages in the context.

1 await runtime.browserContext.pages();

Returns RemotePlaywrightPage[]

Upstream docs

newPage()

Creates a new page in the browser context.

1 await runtime.browserContext.newPage();

Returns RemotePlaywrightPage

Upstream docs

close(options?)

Closes the browser context. All the pages that belong to the browser context will be closed.

The default browser context cannot be closed.

1 await runtime.browserContext.close();

Parameter	Type	Required	Description
`options`	`{ reason?: string }`	No	—

Upstream docs

Other

browser()

Returns the browser this context belongs to.

1 runtime.browserContext.browser();

Returns RemotePlaywrightBrowser \| null

Upstream docs

serviceWorkers()

Returns all service workers in the context.

Service workers are only available on Chromium-based browsers.

1 await runtime.browserContext.serviceWorkers();

Returns Array<{ url: string; workerId: string }>

Upstream docs

newCDPSession(page)

Returns the newly created CDP session attached to the given page.

CDP Sessions are only supported on Chromium-based browsers.

1 await runtime.browserContext.newCDPSession(/* RemotePlaywrightPage */);

Parameter	Type	Required	Description
`page`	`HasHandleId`	Yes	Target page to create CDP session for.

Returns { sessionId: string }

Upstream docs

grantPermissions(permissions, options?)

Grants specified permissions to the browser context.

Only grants corresponding permissions to the given origin if specified.

1 await runtime.browserContext.grantPermissions(/* PlaywrightPermission[] */);

Parameter	Type	Required	Description
`permissions`	`PlaywrightPermission[]`	Yes	—
`options`	`PlaywrightGrantPermissionsOptions`	No	—

Upstream docs

clearPermissions()

Clears all permission overrides for the browser context.

1 await runtime.browserContext.clearPermissions();

Upstream docs

addInitScript(script, arg?)

Adds a script which would be evaluated in one of the following scenarios: whenever a page is created in the context or navigated.

The script is evaluated before any page script. Use when you want to inject JavaScript before the page loads.

1 await runtime.browserContext.addInitScript(/* script */);

Parameter	Type	Required	Description
`script`	`Function \| string \| { path?: string; content?: string }`	Yes	—
`arg`	`unknown`	No	—

Upstream docs

exposeBinding(name, callback, options?)

Adds a function called name on the window object of every frame in every page in the context.

When called, the function executes callback and returns a Promise which resolves to the return value of callback. The first argument of the callback function contains information about the caller.

1 await runtime.browserContext.exposeBinding('...', '...');

Parameter	Type	Required	Description
`name`	`string`	Yes	—
`callback`	`Function`	Yes	—
`options`	`{ handle?: boolean }`	No	—

Upstream docs

route(url, handler, options?)

Routing provides the capability to modify network requests that are made by any page in the browser context.

Once routing is enabled, every request matching the url pattern will stall unless it is continued, fulfilled, or aborted.

1 await runtime.browserContext.route(/* url */, '...');

Parameter	Type	Required	Description
`url`	`string \| RegExp \| ((url: URL) => boolean)`	Yes	—
`handler`	`Function`	Yes	—
`options`	`PlaywrightRouteOptions`	No	—

Upstream docs

routeFromHAR(har, options?)

If specified, network requests that are made in the context will be served from the HAR file.

Parameter	Type	Required	Description
`har`	`string`	Yes	Path to a HAR file with recorded network data.
`options`	`PlaywrightRouteFromHAROptions`	No	—

unroute(url, handler?)

Removes a route created with browserContext.route(). When handler is not specified, removes all routes for the url.

1 await runtime.browserContext.unroute(/* url */);

Parameter	Type	Required	Description
`url`	`string \| RegExp \| ((url: URL) => boolean)`	Yes	—
`handler`	`Function`	No	—

Upstream docs

unrouteAll(options?)

Removes all routes created with browserContext.route() and browserContext.routeFromHAR().

1 await runtime.browserContext.unrouteAll();

Parameter	Type	Required	Description
`options`	`PlaywrightUnrouteAllOptions`	No	—

Upstream docs

setExtraHTTPHeaders(headers)

Sets extra HTTP headers that will be sent with every request in the context.

These headers are merged with page-specific extra HTTP headers set with page.setExtraHTTPHeaders(). If page overrides a particular header, page-specific header value will be used instead of the browser context header value.

1 await runtime.browserContext.setExtraHTTPHeaders(/* Record<string, string> */);

Parameter	Type	Required	Description
`headers`	`Record<string, string>`	Yes	—

Upstream docs

setHTTPCredentials(httpCredentials)

Sets HTTP credentials for HTTP authentication.

Deprecated: Browsers may cache credentials after successful authentication. Create a new browser context instead.

1 await runtime.browserContext.setHTTPCredentials(/* httpCredentials */);

Parameter	Type	Required	Description
`httpCredentials`	`PlaywrightHttpCredentials \| null`	Yes	—

Upstream docs

setOffline(offline)

Sets whether to emulate network being offline for the browser context.

1 await runtime.browserContext.setOffline(true);

Parameter	Type	Required	Description
`offline`	`boolean`	Yes	—

Upstream docs

setGeolocation(geolocation)

Sets the contexts geolocation. Passing null clears geolocation.

Requires the geolocation permission to be granted.

1 await runtime.browserContext.setGeolocation(/* geolocation */);

Parameter	Type	Required	Description
`geolocation`	`PlaywrightGeolocation \| null`	Yes	—

Upstream docs

setDefaultNavigationTimeout(timeout)

Sets the default maximum navigation timeout for this context.

This setting will change the default maximum navigation time for page.goto(), page.reload(), page.goBack(), page.goForward(), page.waitForNavigation().

1 await runtime.browserContext.setDefaultNavigationTimeout(0);

Parameter	Type	Required	Description
`timeout`	`number`	Yes	—

Upstream docs

setDefaultTimeout(timeout)

Sets the default maximum time for all methods accepting timeout option.

1 await runtime.browserContext.setDefaultTimeout(0);

Parameter	Type	Required	Description
`timeout`	`number`	Yes	—

Upstream docs

storageState(options?)

Returns storage state for this browser context.

Contains current cookies and local storage snapshot.

1 await runtime.browserContext.storageState();

Parameter	Type	Required	Description
`options`	`{ path?: string }`	No	—

Returns PlaywrightStorageState

Upstream docs

routeWebSocket(url, handler)

Allows modifying WebSocket connections made by pages in the context.

Only WebSockets created after this method was called will be routed. It is recommended to call this method before creating any pages.

1 await runtime.browserContext.routeWebSocket(/* url */, '...');

Parameter	Type	Required	Description
`url`	`string \| RegExp \| ((url: URL) => boolean)`	Yes	URL pattern to match WebSocket connections.
`handler`	`Function`	Yes	Handler function to route the WebSocket.

Upstream docs

backgroundPages()

Returns all background pages in the context.

Deprecated. Background pages are only supported on Chromium-based browsers.

1 await runtime.browserContext.backgroundPages();

Returns RemotePlaywrightPage[]

Upstream docs