# `PlaywrightEx.BrowserContext`
[🔗](https://github.com/probably-not/playwright_ex/blob/v0.5.0-fork.2/lib/playwright_ex/channels/browser_context.ex#L1)

Interact with a Playwright `BrowserContext`.

There is no official documentation, since this is considered Playwright internal.

Reference: https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/client/browserContext.ts

# `add_cookies_opt`

```elixir
@type add_cookies_opt() ::
  {:connection, GenServer.name()} | {:timeout, timeout()} | {:cookies, [term()]}
```

# `add_init_script_opt`

```elixir
@type add_init_script_opt() ::
  {:connection, GenServer.name()} | {:timeout, timeout()} | {:source, binary()}
```

# `clear_cookies_opt`

```elixir
@type clear_cookies_opt() ::
  {:connection, GenServer.name()}
  | {:timeout, timeout()}
  | {:domain, term()}
  | {:name, term()}
  | {:path, term()}
```

# `clock_fast_forward_opt`

```elixir
@type clock_fast_forward_opt() ::
  {:connection, GenServer.name()}
  | {:timeout, timeout()}
  | {:ticks, non_neg_integer() | binary()}
```

# `clock_install_opt`

```elixir
@type clock_install_opt() ::
  {:connection, GenServer.name()}
  | {:timeout, timeout()}
  | {:time, non_neg_integer() | binary() | struct()}
```

# `close_opt`

```elixir
@type close_opt() ::
  {:connection, GenServer.name()} | {:timeout, timeout()} | {:reason, binary()}
```

# `cookies_opt`

```elixir
@type cookies_opt() ::
  {:connection, GenServer.name()} | {:timeout, timeout()} | {:urls, [binary()]}
```

# `new_page_opt`

```elixir
@type new_page_opt() :: {:connection, GenServer.name()} | {:timeout, timeout()}
```

# `register_selector_engine_opt`

```elixir
@type register_selector_engine_opt() ::
  {:connection, GenServer.name()}
  | {:timeout, timeout()}
  | {:selector_engine, keyword()}
```

# `set_storage_state_opt`

```elixir
@type set_storage_state_opt() ::
  {:connection, GenServer.name()}
  | {:timeout, timeout()}
  | {:cookies, [term()]}
  | {:origins, [term()]}
```

# `storage_state_opt`

```elixir
@type storage_state_opt() ::
  {:connection, GenServer.name()}
  | {:timeout, timeout()}
  | {:indexedDB, boolean()}
```

# `add_cookies`

```elixir
@spec add_cookies(PlaywrightEx.guid(), [
  add_cookies_opt() | PlaywrightEx.unknown_opt()
]) ::
  {:ok, any()} | {:error, any()}
```

Adds cookies into this browser context.

Reference: https://playwright.dev/docs/api/class-browsercontext#browser-context-add-cookies

## Options
* `:connection` (`t:term/0`) - The Connection process name. Defaults to `PlaywrightEx.Supervisor.Connection`. The default value is `PlaywrightEx.Supervisor.Connection`.

* `:timeout` (`t:timeout/0`) - Required. Maximum time for the operation (milliseconds).

* `:cookies` (list of `t:term/0`) - Required. Adds cookies into this browser context. All pages within this context will have these cookies installed.

# `add_init_script`

```elixir
@spec add_init_script(PlaywrightEx.guid(), [
  add_init_script_opt() | PlaywrightEx.unknown_opt()
]) ::
  {:ok, any()} | {:error, any()}
```

Adds a script which would be evaluated in one of the following scenarios:

- Whenever a page is created in the browser context or is navigated.
- Whenever a child frame is attached or navigated in any page in the browser context. In this case, the script is evaluated in the context of the newly attached frame.

The script is evaluated after the document was created but before any of its scripts were run.
This is useful to amend the JavaScript environment, e.g. to seed `Math.random`.

Reference: https://playwright.dev/docs/api/class-browsercontext#browser-context-add-init-script

> ### Script Execution Order Is Not Defined {: .info}
>
> The order of evaluation of multiple scripts installed via
> `PlaywrightEx.BrowserContext.add_init_script/2` and
> `PlaywrightEx.Page.add_init_script/2` is not defined.

## Options
* `:connection` (`t:term/0`) - The Connection process name. Defaults to `PlaywrightEx.Supervisor.Connection`. The default value is `PlaywrightEx.Supervisor.Connection`.

* `:timeout` (`t:timeout/0`) - Required. Maximum time for the operation (milliseconds).

* `:source` (`t:String.t/0`) - Required. Raw JavaScript code to be evaluated in all pages before any scripts run.

# `clear_cookies`

```elixir
@spec clear_cookies(PlaywrightEx.guid(), [
  clear_cookies_opt() | PlaywrightEx.unknown_opt()
]) ::
  {:ok, any()} | {:error, any()}
```

Removes cookies from this browser context.

Reference: https://playwright.dev/docs/api/class-browsercontext#browser-context-clear-cookies

## Options
* `:connection` (`t:term/0`) - The Connection process name. Defaults to `PlaywrightEx.Supervisor.Connection`. The default value is `PlaywrightEx.Supervisor.Connection`.

* `:timeout` (`t:timeout/0`) - Required. Maximum time for the operation (milliseconds).

* `:domain` (`t:term/0`) - Only removes cookies with the given domain.

* `:name` (`t:term/0`) - Only removes cookies with the given name.

* `:path` (`t:term/0`) - Only removes cookies with the given path.

# `clock_fast_forward`

```elixir
@spec clock_fast_forward(PlaywrightEx.guid(), [
  clock_fast_forward_opt() | PlaywrightEx.unknown_opt()
]) ::
  {:ok, any()} | {:error, any()}
```

Advance the clock by jumping forward in time. Only fires due timers at most once. This is equivalent to user closing the laptop lid for a while and reopening it later, after given time..

Reference: https://playwright.dev/docs/api/class-clock#clock-fast-forward

## Options
* `:connection` (`t:term/0`) - The Connection process name. Defaults to `PlaywrightEx.Supervisor.Connection`. The default value is `PlaywrightEx.Supervisor.Connection`.

* `:timeout` (`t:timeout/0`) - Required. Maximum time for the operation (milliseconds).

* `:ticks` - Required. Time to advance, in milliseconds or in `ss` / `mm:ss` / `hh:mm:ss` string format.

# `clock_install`

```elixir
@spec clock_install(PlaywrightEx.guid(), [
  clock_install_opt() | PlaywrightEx.unknown_opt()
]) ::
  {:ok, any()} | {:error, any()}
```

Install fake implementations for the other time-related functions (e.g. `clock_fast_forward/2`).

Reference: https://playwright.dev/docs/api/class-clock#clock-install

## Options
* `:connection` (`t:term/0`) - The Connection process name. Defaults to `PlaywrightEx.Supervisor.Connection`. The default value is `PlaywrightEx.Supervisor.Connection`.

* `:timeout` (`t:timeout/0`) - Required. Maximum time for the operation (milliseconds).

* `:time` - Optional base time to install, as milliseconds since epoch, an ISO8601 datetime, or a string accepted by Playwright.

# `close`

```elixir
@spec close(PlaywrightEx.guid(), [close_opt() | PlaywrightEx.unknown_opt()]) ::
  {:ok, any()} | {:error, any()}
```

Closes the browser context.

Reference: https://playwright.dev/docs/api/class-browsercontext#browser-context-close

## Options
* `:connection` (`t:term/0`) - The Connection process name. Defaults to `PlaywrightEx.Supervisor.Connection`. The default value is `PlaywrightEx.Supervisor.Connection`.

* `:timeout` (`t:timeout/0`) - Required. Maximum time for the operation (milliseconds).

* `:reason` (`t:String.t/0`) - The reason to be reported to the operations interrupted by the context closure.

# `cookies`

```elixir
@spec cookies(PlaywrightEx.guid(), [cookies_opt() | PlaywrightEx.unknown_opt()]) ::
  {:ok, [map()]} | {:error, any()}
```

Returns cookies from this browser context.

Reference: https://playwright.dev/docs/api/class-browsercontext#browser-context-cookies

## Options
* `:connection` (`t:term/0`) - The Connection process name. Defaults to `PlaywrightEx.Supervisor.Connection`. The default value is `PlaywrightEx.Supervisor.Connection`.

* `:timeout` (`t:timeout/0`) - Required. Maximum time for the operation (milliseconds).

* `:urls` (list of `t:String.t/0`) - If specified, returns cookies for the given URLs. The default value is `[]`.

# `new_page`

```elixir
@spec new_page(PlaywrightEx.guid(), [new_page_opt() | PlaywrightEx.unknown_opt()]) ::
  {:ok, %{guid: PlaywrightEx.guid(), main_frame: %{guid: PlaywrightEx.guid()}}}
  | {:error, any()}
```

Creates a new page in the browser context.

Reference: https://playwright.dev/docs/api/class-browsercontext#browser-context-new-page

## Options
* `:connection` (`t:term/0`) - The Connection process name. Defaults to `PlaywrightEx.Supervisor.Connection`. The default value is `PlaywrightEx.Supervisor.Connection`.

* `:timeout` (`t:timeout/0`) - Required. Maximum time for the operation (milliseconds).

# `register_selector_engine`

```elixir
@spec register_selector_engine(PlaywrightEx.guid(), [
  register_selector_engine_opt() | PlaywrightEx.unknown_opt()
]) :: {:ok, any()} | {:error, any()}
```

Registers a custom selector engine.

Reference: https://playwright.dev/docs/api/class-selectors#selectors-register

## Options
* `:connection` (`t:term/0`) - The Connection process name. Defaults to `PlaywrightEx.Supervisor.Connection`. The default value is `PlaywrightEx.Supervisor.Connection`.

* `:timeout` (`t:timeout/0`) - Required. Maximum time for the operation (milliseconds).

* `:selector_engine` (non-empty `t:keyword/0`) - Required.

  * `:name` (`t:String.t/0`) - Required. Name that is used in selectors as a prefix.

  * `:source` (`t:String.t/0`) - Required. Script that evaluates to a selector engine instance.

# `set_storage_state`

```elixir
@spec set_storage_state(PlaywrightEx.guid(), [
  set_storage_state_opt() | PlaywrightEx.unknown_opt()
]) ::
  {:ok, any()} | {:error, any()}
```

Clears the existing cookies, local storage and IndexedDB entries for all origins and sets the new storage state.

Reference: https://playwright.dev/docs/api/class-browsercontext#browser-context-set-storage-state

## Options
* `:connection` (`t:term/0`) - The Connection process name. Defaults to `PlaywrightEx.Supervisor.Connection`. The default value is `PlaywrightEx.Supervisor.Connection`.

* `:timeout` (`t:timeout/0`) - Required. Maximum time for the operation (milliseconds).

* `:cookies` (list of `t:term/0`) - List of cookies to set as the current cookies on the context.
  Defaults to an empty list to clear all cookies on the context. The default value is `[]`.

* `:origins` (list of `t:term/0`) - List of origins and their local storage to set as the current local storage data on the context.
  Defaults to an empty list to clear all local storage on the context. The default value is `[]`.

# `storage_state`

```elixir
@spec storage_state(PlaywrightEx.guid(), [
  storage_state_opt() | PlaywrightEx.unknown_opt()
]) ::
  {:ok, [map()]} | {:error, any()}
```

Returns storage state for this browser context, contains current cookies, local storage snapshot and IndexedDB snapshot.

Reference: https://playwright.dev/docs/api/class-browsercontext#browser-context-storage-state

## Options
* `:connection` (`t:term/0`) - The Connection process name. Defaults to `PlaywrightEx.Supervisor.Connection`. The default value is `PlaywrightEx.Supervisor.Connection`.

* `:timeout` (`t:timeout/0`) - Required. Maximum time for the operation (milliseconds).

* `:indexedDB` (`t:boolean/0`) - Set to true to include IndexedDB in the storage state snapshot.
  If your application uses IndexedDB to store authentication tokens, like Firebase Authentication, enable this. The default value is `false`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*