Automator.Client (automator v0.1.3)

Low-level WebSocket client for sending raw Chrome DevTools Protocol (CDP) commands.

Connects to a Chromium WebSocket debugger URL and sends commands using the JSON-RPC protocol. Use this when you need direct access to CDP methods not exposed by Automator.Scraper.

Example

# Connect to a browser-level WebSocket
{:ok, client} = Automator.Client.start_link(ws_url)

# Send any CDP command
{:ok, result} = Automator.Client.send_command(client, "Browser.getVersion")
IO.inspect(result["product"])
# => "Chrome/145.0.7632.159"

# Connect to a page target for page-level commands
{:ok, page_client} = Automator.Client.start_link(page_ws_url)
{:ok, _} = Automator.Client.send_command(page_client, "Page.navigate", %{url: "https://example.com"})

Protocol

Commands follow the Chrome DevTools Protocol JSON-RPC format:

{"id": 1, "method": "Page.navigate", "params": {"url": "https://example.com"}}

Responses are matched to callers by the id field. See the CDP protocol reference for all available domains and methods.

Common CDP Domains

Domain	Use case
`Page`	Navigation, screenshots, lifecycle events
`Runtime`	JavaScript evaluation, object inspection
`DOM`	DOM tree traversal, node manipulation
`Network`	Request interception, cookies
`Input`	Mouse/keyboard simulation
`Emulation`	Device emulation, viewport, geolocation
`Browser`	Browser info, window management
`Target`	Tab/page management

When to Use

Use Client directly when you need:

CDP domains not exposed by Automator.Scraper (e.g., DOM, Network, Input)
Fine-grained control over command parameters
Browser-level commands (via the browser WebSocket URL)
Multiple concurrent page connections to the same browser

For most scraping tasks, Automator.Scraper is simpler and handles connection management automatically.

Summary

Types

t()

Functions

send_command(pid, method, params \\ %{}, timeout \\ 30000)

Sends a Automator command and blocks until the response arrives.

start_link(ws_url)

Connects to a Chromium WebSocket debugger URL.

Types

t()

@type t() :: %Automator.Client{
  callers: %{required(non_neg_integer()) => {pid(), reference()}},
  next_id: non_neg_integer()
}

Functions

send_command(pid, method, params \\ %{}, timeout \\ 30000)

Sends a Automator command and blocks until the response arrives.

Commands follow the Automator JSON-RPC format. See the Automator protocol documentation for available methods and parameters.

Parameters

pid - The client process returned by start_link/1
method - The Automator method name (e.g., "Page.navigate", "Runtime.evaluate")
params - A map of parameters for the command (defaults to %{})
timeout - Milliseconds to wait for a response (default: 30000)

Returns

{:ok, result} - The Automator response body
{:error, error} - If Automator returned an error response
{:error, :timeout} - If no response arrived within the timeout

Example

{:ok, result} = Automator.Client.send_command(client, "Page.navigate", %{url: "https://example.com"})
# => {:ok, %{"frameId" => "...", "loaderId" => "..."}}

{:ok, result} = Automator.Client.send_command(client, "Runtime.evaluate", %{
  expression: "document.title",
  returnByValue: true
})
# => {:ok, %{"result" => %{"type" => "string", "value" => "Example Domain"}}}

start_link(ws_url)

Connects to a Chromium WebSocket debugger URL.

Returns {:ok, pid} where pid is the client process.

Parameters

ws_url - The WebSocket URL from Automator.Chromium.spawn().ws_url or from the /json HTTP endpoint for a specific page target.

Example

{:ok, client} = Automator.Client.start_link("ws://localhost:9222/devtools/browser/...")