@spec attribute(t(), String.t(), String.t(), keyword()) ::
  {:ok, String.t() | nil} | {:error, term()}

Returns attribute name of the first element matching css, or nil when the element or attribute is absent.

@spec call_function(t(), String.t(), [term()], keyword()) ::
  {:ok, term()} | {:error, term()}

Calls a JavaScript function with args and returns its value.

function_declaration is a JS function expression (e.g. "(a, b) => a + b"). It is interpolated into the page script verbatim, so treat it as trusted code — never build it from untrusted input. args, by contrast, are JSON-encoded (not string-interpolated) before being applied, so passing data values through them is safe. A thrown exception is {:error, {:evaluate_exception, details}}; non-serializable args return {:error, {:invalid_args, reason}}.

Options: :timeout (default 15_000), :await_promise (default false).

@spec clear_cookies(
  t(),
  keyword()
) :: :ok | {:error, term()}

Clears all browser cookies. Lazily enables Network. Options: :timeout.

@spec click(t(), String.t(), keyword()) :: :ok | {:error, term()}

Clicks the first element matching css (a synthetic JS .click()).

Returns :ok, or {:error, {:selector_not_found, css}} when nothing matches.

@spec cookies(
  t(),
  keyword()
) :: {:ok, [map()]} | {:error, term()}

Returns all browser cookies as a list of CDP cookie maps.

Lazily enables the Network domain. Options: :timeout (default 10_000).

@spec evaluate(t(), String.t(), keyword()) :: {:ok, term()} | {:error, term()}

Evaluates a JavaScript expression and returns its value (returnByValue).

A thrown JS exception is {:error, {:evaluate_exception, details}}.

Options: :timeout (default 15_000), :await_promise (default false).

@spec html(
  t(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Returns the page's full serialized HTML (document.documentElement.outerHTML).

@spec navigate(t(), String.t(), keyword()) :: {:ok, t()} | {:error, term()}

Navigates to url and (by default) waits until the network is almost idle.

Returns {:ok, page} so it pipelines with with. The readiness wait is best-effort: if it times out, navigation still returns {:ok, page} (the page may simply be slow); a hard navigation error returns {:error, _}.

Options:

• :wait_until — :network_almost_idle (default), :load, or :none
• :timeout — ms (default 30_000)

@spec pdf(
  t(),
  keyword()
) :: {:ok, binary()} | {:error, term()}

Renders the page to PDF (Page.printToPDF).

Returns {:ok, data} where data is the PDF bytes — or, when :path is given, the written file path (also a binary). Options: :path, :landscape (default false), :print_background (default true), :timeout (default 30_000).

@spec screenshot(
  t(),
  keyword()
) :: {:ok, binary()} | {:error, term()}

Captures a PNG screenshot.

Returns {:ok, data} where data is the PNG bytes — or, when :path is given, the written file path (also a binary).

Options: :path (write to file), :full_page (capture beyond the viewport, default false), :timeout (default 30_000).

@spec set_cookies(t(), [map()], keyword()) :: :ok | {:error, term()}

Sets cookies. Each is a CDP CookieParam map — at least "name", "value", and a "url" or "domain". Lazily enables Network. Options: :timeout.

@spec set_extra_headers(t(), %{optional(String.t()) => String.t()}, keyword()) ::
  :ok | {:error, term()}

Sets extra HTTP headers sent with every subsequent request on this page.

headers is a map of header name => value; set them before navigating for them to apply to that navigation. Lazily enables Network. Options: :timeout.

@spec set_user_agent(t(), String.t(), keyword()) :: :ok | {:error, term()}

Overrides the page's User-Agent (Emulation.setUserAgentOverride).

Options: :timeout (default 10_000).

@spec set_viewport(t(), pos_integer(), pos_integer(), keyword()) ::
  :ok | {:error, term()}

Overrides the viewport via Emulation.setDeviceMetricsOverride.

width/height are CSS pixels. Options: :device_scale_factor (default 1), :mobile (default false), :timeout. Returns :ok.

@spec text(t(), String.t(), keyword()) :: {:ok, String.t() | nil} | {:error, term()}

Returns the textContent of the first element matching css, or nil when no element matches.

@spec visible?(t(), String.t(), keyword()) :: {:ok, boolean()} | {:error, term()}

Returns {:ok, true} when the first element matching css is rendered and visible (has layout boxes, not display: none / visibility: hidden), {:ok, false} otherwise — including when no element matches.

@spec wait_for_function(t(), String.t(), keyword()) :: :ok | {:error, term()}

Polls a JavaScript expression until it is truthy, or timeout elapses.

The expression is coerced with !!(...), so JS truthiness applies. Returns :ok, {:error, :timeout}, or {:error, reason} if a non-transient evaluate error occurs (e.g. a thrown exception or a dropped connection). Options: :timeout (default 5_000), :interval (poll interval ms, default 100).

@spec wait_for_navigation(
  t(),
  keyword()
) :: :ok | {:error, term()}

Waits for a navigation lifecycle milestone, without issuing a navigation.

Useful after a click/3 (or other in-page action) that triggers navigation.

Options:

• :wait_until — :network_almost_idle (default), :load, or :none
• :timeout — ms (default 30_000)

Returns :ok, {:error, :timeout}, or {:error, reason} if the connection drops while waiting.

@spec wait_for_selector(t(), String.t(), keyword()) :: :ok | {:error, term()}

Polls until css matches an element, or timeout elapses.

Returns :ok, {:error, :timeout}, or {:error, reason} if a non-transient evaluate error occurs (e.g. the connection drops). Options: :timeout (default 5_000), :interval (poll interval ms, default 100).