# `Cerberus.Browser`
[🔗](https://github.com/ftes/cerberus/blob/v0.1.7/lib/cerberus/browser.ex#L1)

Browser-only extensions for richer real-browser workflows.

These helpers are intentionally scoped to browser sessions.

# `cookie`

```elixir
@type cookie() :: %{
  name: String.t() | nil,
  value: term(),
  domain: String.t() | nil,
  path: String.t() | nil,
  http_only: boolean(),
  secure: boolean(),
  same_site: String.t() | nil,
  session: boolean()
}
```

# `add_cookie`

```elixir
@spec add_cookie(
  session,
  String.t(),
  String.t(),
  Cerberus.Options.browser_add_cookie_opts()
) :: session
when session: var
```

Adds a cookie to the active browser context.

## Options

* `:domain` (`t:term/0`) - Cookie domain override. The default value is `nil`.

* `:path` (`t:term/0`) - Cookie path override. The default value is `"/"`.

* `:http_only` (`t:boolean/0`) - Marks cookie as HttpOnly. The default value is `false`.

* `:secure` (`t:boolean/0`) - Marks cookie as Secure. The default value is `false`.

* `:same_site` (`t:term/0`) - Cookie sameSite policy (:strict, :lax, :none). The default value is `:lax`.

# `add_cookies`

```elixir
@spec add_cookies(session, [Cerberus.Options.browser_cookie_arg()]) :: session
when session: var
```

Adds cookies to the active browser context.

This follows Playwright's bulk cookie shape: each cookie is a keyword list with
`:name`, `:value`, and optional `:url` or `:domain`/`:path` fields.
When `:url`/`:domain` are omitted, Cerberus falls back to the browser session base URL.

# `add_session_cookie`

```elixir
@spec add_session_cookie(
  session,
  Cerberus.Options.browser_session_cookie_arg(),
  keyword()
) :: session
when session: var
```

Adds a Phoenix `Plug.Session` cookie to the active browser context.

`session_options` must match the options used by `plug Plug.Session` in your endpoint
or router. For example: `MyAppWeb.Endpoint.session_options()`.

# `assert_dialog`

```elixir
@spec assert_dialog(
  session,
  Cerberus.Locator.t(),
  Cerberus.Options.browser_assert_dialog_opts()
) ::
  session
when session: var
```

Asserts that a dialog matching the text locator was observed.

`assert_dialog/3` matches dialog text from the active dialog or recently observed
dialog events, then auto-accepts the observed dialog. Prompt dialogs are
auto-accepted with an empty string input.

## Options

* `:timeout` (`t:pos_integer/0`) - Wait timeout in milliseconds for dialog lifecycle events.

* `:browser` (`t:keyword/0`) - Per-call browser config overrides used for timeout defaults. The default value is `[]`.

# `clear_cookies`

```elixir
@spec clear_cookies(session, Cerberus.Options.browser_clear_cookies_opts()) :: session
when session: var
```

Removes all cookies from the active browser context.

## Options

* `:timeout` (`t:non_neg_integer/0`) - Maximum wait time in milliseconds. The default value is `0`.

# `cookie`

```elixir
@spec cookie(Cerberus.Session.t(), String.t()) :: cookie() | nil
```

Returns the cookie by `name` or `nil` when not present.

# `cookie`

```elixir
@spec cookie(session, String.t(), (cookie() | nil -> term())) :: session
when session: var
```

Passes the cookie by `name` (or `nil`) to `callback` and returns `session`.

# `cookies`

```elixir
@spec cookies(Cerberus.Session.t()) :: [cookie()]
```

Returns all browser cookies visible to the active page.

# `cookies`

```elixir
@spec cookies(session, ([cookie()] -> term())) :: session when session: var
```

Passes all browser cookies visible to the active page to `callback` and returns `session`.

# `drag`

```elixir
@spec drag(session, String.t(), String.t(), Cerberus.Options.browser_drag_opts()) ::
  session
when session: var
```

Drags from `source_selector` to `target_selector`.

## Options

* `:timeout` (`t:non_neg_integer/0`) - Browser action timeout in milliseconds.

# `evaluate_js`

```elixir
@spec evaluate_js(Cerberus.Session.t(), String.t()) :: Cerberus.Session.t()
```

Evaluates JavaScript and ignores the result, returning the original session.

# `evaluate_js`

```elixir
@spec evaluate_js(
  Cerberus.Session.t(),
  String.t(),
  Cerberus.Options.return_result_opts()
) ::
  Cerberus.Session.t() | term()
@spec evaluate_js(Cerberus.Session.t(), String.t(), (term() -> term())) ::
  Cerberus.Session.t()
```

Evaluates JavaScript and controls result handling.

Use either:
- callback form (`evaluate_js(session, expression, fn value -> ... end)`) to keep piping
- `return_result: true` (`evaluate_js(session, expression, return_result: true)`) to return the JS value

## Options

* `:return_result` (`t:boolean/0`) - When true, returns the computed value instead of the session. The default value is `false`.

# `press`

```elixir
@spec press(
  session,
  Cerberus.Locator.t(),
  String.t(),
  Cerberus.Options.browser_press_opts()
) :: session
when session: var
```

Presses a keyboard key on a matched element.

## Options

* `:timeout` (`t:non_neg_integer/0`) - Browser action timeout in milliseconds.

# `screenshot`

```elixir
@spec screenshot(session, String.t() | Cerberus.Options.screenshot_opts()) ::
  session | binary()
when session: var
```

Captures a browser screenshot.

`opts_or_path` accepts either a path string or keyword options.

Use either:
- callback form (`screenshot(session, opts, fn png_binary -> ... end)`) to keep piping
- `return_result: true` to return the PNG binary

`open: true` opens the saved screenshot path in the default system image viewer.

## Options

* `:path` (`t:term/0`) - Optional file path for the screenshot output. The default value is `nil`.

* `:full_page` (`t:boolean/0`) - Captures the full document instead of only the viewport.

* `:open` (`t:boolean/0`) - Opens the saved screenshot with the default system viewer. The default value is `false`.

* `:return_result` (`t:boolean/0`) - Returns the screenshot PNG binary instead of the session. The default value is `false`.

# `screenshot`

```elixir
@spec screenshot(
  session,
  String.t() | Cerberus.Options.screenshot_opts(),
  (binary() -> term())
) ::
  session
when session: var
```

# `session_cookie`

```elixir
@spec session_cookie(Cerberus.Session.t()) :: cookie() | nil
```

Returns the session cookie (commonly `_app_key`) when present.

# `session_cookie`

```elixir
@spec session_cookie(session, (cookie() | nil -> term())) :: session when session: var
```

Passes the session cookie (or `nil`) to `callback` and returns `session`.

# `type`

```elixir
@spec type(
  session,
  Cerberus.Locator.t(),
  String.t(),
  Cerberus.Options.browser_type_opts()
) :: session
when session: var
```

Types text into a matched element.

## Options

* `:clear` (`t:boolean/0`) - Clears the field before typing. The default value is `false`.

* `:timeout` (`t:non_neg_integer/0`) - Browser action timeout in milliseconds.

# `user_agent_for_sandbox`

```elixir
@spec user_agent_for_sandbox(map()) :: String.t()
```

Returns encoded SQL sandbox metadata for the configured Cerberus Ecto repos.

# `user_agent_for_sandbox`

```elixir
@spec user_agent_for_sandbox(module() | [module()], map()) :: String.t()
```

Returns encoded SQL sandbox metadata for browser `user_agent` session wiring.

This helper is intended for browser-session sandbox wiring:

    import Cerberus
    import Cerberus.Browser

    metadata = user_agent_for_sandbox(MyApp.Repo, context)
    session(:browser, user_agent: metadata)

# `with_popup`

```elixir
@spec with_popup(
  session,
  (session -> term()),
  (session, session -> term()),
  Cerberus.Options.browser_with_popup_opts()
) :: session
when session: var
```

Runs a popup flow, yielding both main and popup sessions to `callback_fun`.

## Options

* `:timeout` (`t:pos_integer/0`) - Wait timeout in milliseconds for popup capture. The default value is `1500`.

---

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