CDPEx.Chrome (CDPEx v0.1.0)

Copy Markdown View Source

Launches, discovers, and stops the headless Chrome OS process.

launch/1 opens Chrome via a Port with --remote-debugging-port=0, reads the chosen DevTools WebSocket URL from Chrome's stderr (falling back to the DevToolsActivePort file), and returns a handle. stop/1 kills the process and removes the temp profile.

The argument and discovery helpers (build_args/2, default_args/2, resolve_binary/1) are pure and unit-testable without launching anything.

Launch options

  • :headless — run headless (default true); false drops --headless
  • :chrome_binary — path to the Chrome/Chromium executable
  • :window_size — {width, height} (default {1280, 1024})
  • :user_data_dir — profile dir; a fresh temp dir is created (and removed on stop) when omitted. A caller-supplied dir is left in place.
  • :extra_args — extra flags appended to the defaults
  • :args — full flag list that replaces the defaults entirely
  • :launch_timeout — ms to wait for the DevTools URL (default 15_000)

Default flags

Defaults are deliberately neutral (stability + headless), not scraping-tuned. Anti-bot flags (spoofed user-agent, --disable-web-security, --disable-blink-features=AutomationControlled, …) are not included — add them via :extra_args if you need them.

Sandbox

The defaults include --no-sandbox / --disable-setuid-sandbox so Chrome starts in the common container/CI setup (running as root), where the sandbox can't initialize. That is a security reduction when visiting untrusted pages — to keep the sandbox, run as a non-root user and override the flag list via :args (omitting the two sandbox flags).

Summary

Types

handle()

Functions

build_args(user_data_dir, opts \\ [])

Builds the full Chrome argument list for a profile dir.

default_args(user_data_dir, opts \\ [])

The neutral default flag list (stability + headless), with --user-data-dir, --window-size, and the conditional --headless applied from opts.

launch(opts \\ [])

Launches headless Chrome and returns {:ok, handle} once its DevTools endpoint is reachable, or {:error, reason}.

resolve_binary(opts)

Resolves the Chrome binary path from (in order) the :chrome_binary option, the CDP_EX_CHROME_BINARY env var, the CHROME_BINARY env var, then an OS-specific default.

stop(handle)

Stops Chrome: kills the OS process, closes the port, and removes the temp profile dir (only when cdp_ex created it). Idempotent and crash-safe — it is the cleanup run from CDPEx.Browser's terminate/2 callback.

Types

handle()

@type handle() :: %{
  port: port(),
  os_pid: non_neg_integer() | nil,
  debug_url: String.t(),
  user_data_dir: String.t(),
  owns_data_dir: boolean()
}

Functions

build_args(user_data_dir, opts \\ [])

@spec build_args(
  String.t(),
  keyword()
) :: [String.t()]

Builds the full Chrome argument list for a profile dir.

Returns opts[:args] verbatim when given (full override); otherwise the neutral defaults plus opts[:extra_args].

default_args(user_data_dir, opts \\ [])

@spec default_args(
  String.t(),
  keyword()
) :: [String.t()]

The neutral default flag list (stability + headless), with --user-data-dir, --window-size, and the conditional --headless applied from opts.

launch(opts \\ [])

@spec launch(keyword()) :: {:ok, handle()} | {:error, term()}

Launches headless Chrome and returns {:ok, handle} once its DevTools endpoint is reachable, or {:error, reason}.

The Port is owned by the calling process, which therefore receives the {port, {:exit_status, _}} message if Chrome dies.

resolve_binary(opts)

@spec resolve_binary(keyword()) :: String.t()

Resolves the Chrome binary path from (in order) the :chrome_binary option, the CDP_EX_CHROME_BINARY env var, the CHROME_BINARY env var, then an OS-specific default.

stop(handle)

@spec stop(handle()) :: :ok

Stops Chrome: kills the OS process, closes the port, and removes the temp profile dir (only when cdp_ex created it). Idempotent and crash-safe — it is the cleanup run from CDPEx.Browser's terminate/2 callback.