@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 (term/0) - Cookie domain override. The default value is nil.

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

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

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

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

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

@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().

@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 (pos_integer/0) - Wait timeout in milliseconds for dialog lifecycle events.

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

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

Removes all cookies from the active browser context.

Options

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

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

Returns the cookie by name or nil when not present.

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

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

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

Returns all browser cookies visible to the active page.

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

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

@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 (non_neg_integer/0) - Browser action timeout in milliseconds.

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

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

@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 (boolean/0) - When true, returns the computed value instead of the session. The default value is false.

@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 (non_neg_integer/0) - Browser action timeout in milliseconds.

@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 (term/0) - Optional file path for the screenshot output. The default value is nil.

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

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

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

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

Returns the session cookie (commonly _app_key) when present.

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

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

@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 (boolean/0) - Clears the field before typing. The default value is false.

• :timeout (non_neg_integer/0) - Browser action timeout in milliseconds.

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

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

@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)

@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 (pos_integer/0) - Wait timeout in milliseconds for popup capture. The default value is 1500.