CDPEx.Browser (CDPEx v0.2.0)

Copy Markdown View Source

A GenServer owning a headless Chrome OS process and its CDP connections.

CDPEx.Browser launches Chrome (via CDPEx.Chrome), opens a browser-level CDPEx.Connection, and creates pages on demand. It is the lifecycle owner:

  • It traps exits and links every connection, so a page connection crash is isolated (the page is dropped; the browser and other pages survive), while a browser-connection or Chrome death stops the browser cleanly.
  • terminate/2 always runs CDPEx.Chrome.stop/1 — the no-orphan guarantee. Because that relies on terminate/2, supervise this with a :shutdown timeout, not :brutal_kill.

Most callers use the CDPEx facade rather than this module directly.

Summary

Types

t()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

close_page(browser, page)

Closes a page opened with new_page/2.

new_page(browser, opts \\ [])

Opens a new page (tab) and returns a CDPEx.Page handle.

start_link(opts \\ [])

Starts a browser. See CDPEx.Chrome for launch options.

stop(browser)

Stops the browser, closing all pages and killing Chrome.

Types

t()

@type t() :: %CDPEx.Browser{
  browser_conn: term(),
  chrome: term(),
  host: term(),
  opts: term(),
  pages: term(),
  parent: term(),
  port: term(),
  sessions: term()
}

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

close_page(browser, page)

@spec close_page(GenServer.server(), CDPEx.Page.t()) :: :ok | {:error, :unknown_page}

Closes a page opened with new_page/2.

Returns {:error, :unknown_page} if the page does not belong to this browser (a handle from a different browser, or one that was already closed).

new_page(browser, opts \\ [])

@spec new_page(
  GenServer.server(),
  keyword()
) :: {:ok, CDPEx.Page.t()} | {:error, term()}

Opens a new page (tab) and returns a CDPEx.Page handle.

Options:

  • :transport — :dedicated (default, one WebSocket per page, strong crash isolation) or :session (multiplexed over the browser socket via a flattened CDP session — fewer sockets, but all session pages share the browser connection's fate: if it drops, they all go). Any other value returns {:error, {:invalid_transport, value}}.
  • :prevent_alerts — inject no-op alert/confirm/prompt (default true)

start_link(opts \\ [])

@spec start_link(keyword()) :: GenServer.on_start()

Starts a browser. See CDPEx.Chrome for launch options.

stop(browser)

@spec stop(GenServer.server()) :: :ok

Stops the browser, closing all pages and killing Chrome.