***

title: Playwright Browser Context
description: Complete Browser Context method reference for the Playwright driver.
---------------------------------------------------------------------------------

All `Browser Context` methods available when using the **Playwright** driver.

Access via `runtime.browserContext` after launching a Playwright runtime.

<Accordion title="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
  ```

  ```json
  {
    "runtime": "my-browser",
    "steps": [
      {
        "call": "context.goto",
        "args": ["https://example.com"]
      }
    ]
  }
  ```

  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.
</Accordion>

## Waiting

### waitForEvent(event, optionsOrPredicate?)

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

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

```ts
await runtime.browserContext.waitForEvent('...');
```

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

**Returns** `T`

[Upstream docs](https://playwright.dev/docs/api/class-browsercontext#browser-context-wait-for-event)

***

## Cookies

### addCookies(cookies)

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

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

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

[Upstream docs](https://playwright.dev/docs/api/class-browsercontext#browser-context-add-cookies)

***

### cookies(urls?)

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

```ts
await runtime.browserContext.cookies();
```

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

**Returns** `PlaywrightCookie[]`

[Upstream docs](https://playwright.dev/docs/api/class-browsercontext#browser-context-cookies)

***

### clearCookies(options?)

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

<Note>
  If no options are provided, removes all cookies from the context.
</Note>

```ts
await runtime.browserContext.clearCookies();
```

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

[Upstream docs](https://playwright.dev/docs/api/class-browsercontext#browser-context-clear-cookies)

***

## Lifecycle

### pages()

Returns all open pages in the context.

```ts
await runtime.browserContext.pages();
```

**Returns** `RemotePlaywrightPage[]`

[Upstream docs](https://playwright.dev/docs/api/class-browsercontext#browser-context-pages)

***

### newPage()

Creates a new page in the browser context.

```ts
await runtime.browserContext.newPage();
```

**Returns** `RemotePlaywrightPage`

[Upstream docs](https://playwright.dev/docs/api/class-browsercontext#browser-context-new-page)

***

### close(options?)

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

<Note>
  The default browser context cannot be closed.
</Note>

```ts
await runtime.browserContext.close();
```

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

[Upstream docs](https://playwright.dev/docs/api/class-browsercontext#browser-context-close)

***

## Other

### browser()

Returns the browser this context belongs to.

```ts
runtime.browserContext.browser();
```

**Returns** `RemotePlaywrightBrowser \| null`

[Upstream docs](https://playwright.dev/docs/api/class-browsercontext#browser-context-browser)

***

### serviceWorkers()

Returns all service workers in the context.

<Note>
  Service workers are only available on Chromium-based browsers.
</Note>

```ts
await runtime.browserContext.serviceWorkers();
```

**Returns** `Array&lt;{ url: string; workerId: string }&gt;`

[Upstream docs](https://playwright.dev/docs/api/class-browsercontext#browser-context-service-workers)

***

### newCDPSession(page)

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

<Note>
  CDP Sessions are only supported on Chromium-based browsers.
</Note>

```ts
await runtime.browserContext.newCDPSession(/* RemotePlaywrightPage */);
```

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

**Returns** `{ sessionId: string }`

[Upstream docs](https://playwright.dev/docs/api/class-browsercontext#browser-context-new-cdp-session)

***

### grantPermissions(permissions, options?)

Grants specified permissions to the browser context.

<Note>
  Only grants corresponding permissions to the given origin if specified.
</Note>

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

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

[Upstream docs](https://playwright.dev/docs/api/class-browsercontext#browser-context-grant-permissions)

***

### clearPermissions()

Clears all permission overrides for the browser context.

```ts
await runtime.browserContext.clearPermissions();
```

[Upstream docs](https://playwright.dev/docs/api/class-browsercontext#browser-context-clear-permissions)

***

### 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.

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

```ts
await runtime.browserContext.addInitScript(/* script */);
```

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

[Upstream docs](https://playwright.dev/docs/api/class-browsercontext#browser-context-add-init-script)

***

### exposeBinding(name, callback, options?)

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

<Note>
  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.
</Note>

```ts
await runtime.browserContext.exposeBinding('...', '...');
```

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

[Upstream docs](https://playwright.dev/docs/api/class-browsercontext#browser-context-expose-binding)

***

### route(url, handler, options?)

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

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

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

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

[Upstream docs](https://playwright.dev/docs/api/class-browsercontext#browser-context-route)

***

### routeFromHAR(har, options?)

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

<Note>
  Read more about Replaying from HAR.
</Note>

```ts
await runtime.browserContext.routeFromHAR('...');
```

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

[Upstream docs](https://playwright.dev/docs/api/class-browsercontext#browser-context-route-from-har)

***

### unroute(url, handler?)

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

```ts
await runtime.browserContext.unroute(/* url */);
```

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

[Upstream docs](https://playwright.dev/docs/api/class-browsercontext#browser-context-unroute)

***

### unrouteAll(options?)

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

```ts
await runtime.browserContext.unrouteAll();
```

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

[Upstream docs](https://playwright.dev/docs/api/class-browsercontext#browser-context-unroute-all)

***

### setExtraHTTPHeaders(headers)

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

<Note>
  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.
</Note>

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

| Parameter | Type                           | Required | Description |
| --------- | ------------------------------ | -------- | ----------- |
| `headers` | `Record&lt;string, string&gt;` | Yes      | —           |

[Upstream docs](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-extra-http-headers)

***

### setHTTPCredentials(httpCredentials)

Sets HTTP credentials for HTTP authentication.

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

```ts
await runtime.browserContext.setHTTPCredentials(/* httpCredentials */);
```

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

[Upstream docs](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-http-credentials)

***

### setOffline(offline)

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

```ts
await runtime.browserContext.setOffline(true);
```

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

[Upstream docs](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-offline)

***

### setGeolocation(geolocation)

Sets the contexts geolocation. Passing null clears geolocation.

<Note>
  Requires the geolocation permission to be granted.
</Note>

```ts
await runtime.browserContext.setGeolocation(/* geolocation */);
```

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

[Upstream docs](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-geolocation)

***

### setDefaultNavigationTimeout(timeout)

Sets the default maximum navigation timeout for this context.

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

```ts
await runtime.browserContext.setDefaultNavigationTimeout(0);
```

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

[Upstream docs](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-navigation-timeout)

***

### setDefaultTimeout(timeout)

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

```ts
await runtime.browserContext.setDefaultTimeout(0);
```

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

[Upstream docs](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout)

***

### storageState(options?)

Returns storage state for this browser context.

<Note>
  Contains current cookies and local storage snapshot.
</Note>

```ts
await runtime.browserContext.storageState();
```

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

**Returns** `PlaywrightStorageState`

[Upstream docs](https://playwright.dev/docs/api/class-browsercontext#browser-context-storage-state)

***

### routeWebSocket(url, handler)

Allows modifying WebSocket connections made by pages in the context.

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

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

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

[Upstream docs](https://playwright.dev/docs/api/class-browsercontext#browser-context-route-web-socket)

***

### backgroundPages()

Returns all background pages in the context.

<Note>
  Deprecated. Background pages are only supported on Chromium-based browsers.
</Note>

```ts
await runtime.browserContext.backgroundPages();
```

**Returns** `RemotePlaywrightPage[]`

[Upstream docs](https://playwright.dev/docs/api/class-browsercontext#browser-context-background-pages)

***