Drive the Servo web engine from Elixir.
Rover runs each browser as its own OS process, isolated from the BEAM and from other browsers — so every browser has its own proxy, cookie jar, and network state, and a renderer crash can never take down your VM.
The API is modelled after Req: small, composable,
and sensible by default.
One-shot
{:ok, result} = Rover.fetch("https://example.com")
result.body # rendered HTML
result.title # document.title
result.url # final URL after redirectsWith options
{:ok, result} =
Rover.fetch("https://example.com",
proxy: "http://eu.proxy.example:8080",
timeout: 15_000,
wait_for: ".content",
evaluate: "JSON.stringify(window.__NEXT_DATA__)"
)Long-lived browser
{:ok, browser} = Rover.start_link(proxy: "http://proxy:8080")
:ok = Rover.navigate(browser, "https://example.com/login")
:ok = Rover.fill(browser, "#email", "user@example.com")
:ok = Rover.fill(browser, "#password", "hunter2")
:ok = Rover.click(browser, "button[type=submit]")
:ok = Rover.wait_for(browser, ".dashboard")
{:ok, html} = Rover.content(browser)
{:ok, png} = Rover.screenshot(browser)
Rover.stop(browser)See fetch/2 for the full option list.
Summary
Functions
Clear all cookies.
Click the element (center of its bounding box).
Return the rendered outerHTML of the document element.
Return the document URL after redirects.
Evaluate a JavaScript expression in the page context and return its value.
Fetch a URL and return a Rover.Result.
Fill an input/textarea with value and dispatch input/change events.
Return the value of the named attribute on the first match.
Return every cookie visible at the current document URL.
Return the first matching element's innerText.
Return every matching element's innerText as a list.
Hover the mouse cursor over the element.
Navigate to a URL and wait for load.
Capture a screenshot of the page.
Select an option in a <select> by its value.
Parse and set a cookie for the current document URL.
Start a long-lived browser linked to the caller.
Gracefully stop a browser.
Return document.title.
Block until a CSS selector matches at least one element, or :timeout ms elapse.
Functions
@spec clear_cookies(GenServer.server()) :: {:ok, :ok} | {:error, Rover.Error.t()}
Clear all cookies.
@spec click(GenServer.server(), String.t()) :: {:ok, :ok} | {:error, Rover.Error.t()}
Click the element (center of its bounding box).
@spec content(GenServer.server()) :: {:ok, String.t()} | {:error, Rover.Error.t()}
Return the rendered outerHTML of the document element.
@spec current_url(GenServer.server()) :: {:ok, String.t()} | {:error, Rover.Error.t()}
Return the document URL after redirects.
@spec evaluate(GenServer.server(), String.t()) :: {:ok, term()} | {:error, Rover.Error.t()}
Evaluate a JavaScript expression in the page context and return its value.
Simple values (string/number/boolean/null) round-trip as Elixir terms. Arrays and objects become lists and maps.
@spec fetch( String.t(), keyword() ) :: {:ok, Rover.Result.t()} | {:error, Rover.Error.t()}
Fetch a URL and return a Rover.Result.
Spins up a fresh browser, navigates, applies any requested extraction or
evaluation, and tears the browser down. For anything more than a handful of
pages or where startup cost matters, use start_link/1 and reuse a browser.
Options
:proxy— HTTP/HTTPS proxy URI ("http://host:port"or"http://user:pass@host:port"). Default: direct.:timeout— page-load timeout in ms. Default:30_000.:wait_for— CSS selector to wait for before reading content.:wait_timeout— timeout for:wait_forspecifically. Default:10_000.:evaluate— JavaScript expression to evaluate after load; the result is placed inresult.evaluated.:extract— keyword list of[key: "css selector"]. Each selector'sinnerTextis captured intoresult.extracted.<key>. Multi-match selectors return a list.:screenshot—true/:pngfor PNG,:jpegfor JPEG. The image bytes are placed inresult.screenshot.:user_agent— custom User-Agent string.:viewport—{width, height}in CSS pixels. Default:{1280, 720}.:runtime_path— override path to therover_runtimebinary.
Returns:
{:ok, %Rover.Result{status: :ok, body: _, ...}}on success.{:error, %Rover.Error{}}on failure. Never raises.
Example
iex> {:ok, result} = Rover.fetch("https://example.com")
iex> result.status
:ok@spec fill(GenServer.server(), String.t(), String.t()) :: {:ok, :ok} | {:error, Rover.Error.t()}
Fill an input/textarea with value and dispatch input/change events.
@spec get_attribute(GenServer.server(), String.t(), String.t()) :: {:ok, term()} | {:error, Rover.Error.t()}
Return the value of the named attribute on the first match.
@spec get_cookies(GenServer.server()) :: {:ok, [map()]} | {:error, Rover.Error.t()}
Return every cookie visible at the current document URL.
@spec get_text(GenServer.server(), String.t()) :: {:ok, String.t()} | {:error, Rover.Error.t()}
Return the first matching element's innerText.
@spec get_texts(GenServer.server(), String.t()) :: {:ok, [String.t()]} | {:error, Rover.Error.t()}
Return every matching element's innerText as a list.
@spec hover(GenServer.server(), String.t()) :: {:ok, :ok} | {:error, Rover.Error.t()}
Hover the mouse cursor over the element.
@spec screenshot( GenServer.server(), keyword() ) :: {:ok, binary()} | {:error, Rover.Error.t()}
Capture a screenshot of the page.
Options:
:format—:png(default) or:jpeg.:quality— JPEG quality 1..100, ignored for PNG. Default: 85.
@spec select_option(GenServer.server(), String.t(), String.t()) :: {:ok, :ok} | {:error, Rover.Error.t()}
Select an option in a <select> by its value.
@spec set_cookie(GenServer.server(), String.t()) :: {:ok, :ok} | {:error, Rover.Error.t()}
Parse and set a cookie for the current document URL.
cookie is a Set-Cookie header value, e.g. "sid=abc; path=/; HttpOnly".
@spec start_link(keyword()) :: GenServer.on_start()
Start a long-lived browser linked to the caller.
See Rover.Browser.start_link/1 for the full list of options.
@spec stop(GenServer.server(), timeout()) :: :ok
Gracefully stop a browser.
@spec title(GenServer.server()) :: {:ok, String.t()} | {:error, Rover.Error.t()}
Return document.title.
@spec wait_for(GenServer.server(), String.t(), keyword()) :: {:ok, :ok} | {:error, Rover.Error.t()}
Block until a CSS selector matches at least one element, or :timeout ms elapse.