CDPEx.Page (CDPEx v0.1.0)

A page (tab) handle and the operations you run against it.

A CDPEx.Page is a lightweight struct — not a process — holding the page's CDPEx.Connection pid and target id. Operations are functions over that connection, so the OTP properties (supervision, crash isolation) live in the connection/browser layer while page calls stay ergonomic.

Obtain one with CDPEx.new_page/2. If the underlying page dies (navigation to a new target, a crash), operations return {:error, :noproc} and you should open a fresh page.

Summary

Types

t()

Functions

click(page, css, opts \\ [])

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

evaluate(page, js, opts \\ [])

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

html(page, opts \\ [])

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

navigate(page, url, opts \\ [])

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

screenshot(page, opts \\ [])

Captures a PNG screenshot.

wait_for_selector(page, css, opts \\ [])

Polls until css matches an element, or timeout elapses.

Types

t()

@type t() :: %CDPEx.Page{browser: pid(), conn: pid(), target_id: String.t()}

Functions

click(page, css, opts \\ [])

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

evaluate(page, js, opts \\ [])

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

html(page, opts \\ [])

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

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

navigate(page, url, opts \\ [])

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

screenshot(page, opts \\ [])

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

Captures a PNG screenshot.

Returns {:ok, png_binary}, or {:ok, path} when :path is given (the file is written and the path returned).

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

wait_for_selector(page, css, opts \\ [])

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

Polls until css matches an element, or timeout elapses.

Returns :ok or {:error, :timeout}. Options: :timeout (default 5_000), :interval (poll interval ms, default 100).