Class: Browserctl::Client

Inherits:

Object

• Object
• Browserctl::Client

Defined in:

lib/browserctl/client.rb,
lib/browserctl/client/recording_interceptor.rb

Overview

Thin IPC client that wraps each browserd command as a Ruby method call.

Defined Under Namespace

Classes: RecordingInterceptor

Instance Method Summary

• #auth_check(name, include_cookies: false, state: nil, suggested_flow: nil) ⇒ Object

  Runs the auth_required detector against a named page.

• #call(cmd, **params) ⇒ Object
• #click(name, selector = nil, ref: nil) ⇒ Hash

  Clicks an element identified by CSS selector or snapshot ref.

• #cookies(name) ⇒ Hash

  Returns all cookies for a named page.

• #data_delete(name, scope:) ⇒ Hash

  Clears every entry in the given browser-side scope.

• #data_get(name, key, scope:) ⇒ Hash

  Reads a single key from the given browser-side scope.

• #data_list(name, scope:) ⇒ Hash

  Lists every entry in the given browser-side scope.

• #data_set(name, key, value, scope:, domain: nil, path: "/") ⇒ Hash

  Writes a single key/value into the given browser-side scope.

• #delete_cookies(name) ⇒ Hash

  Deletes all cookies for a named page.

• #devtools(name) ⇒ Hash

  Returns the Chrome DevTools URL for a named page.

• #dialog_accept(name, text: nil) ⇒ Hash

  Pre-registers a one-shot handler to accept the next JS dialog on a page.

• #dialog_dismiss(name) ⇒ Hash

  Pre-registers a one-shot handler to dismiss the next JS dialog on a page.

• #evaluate(name, expression) ⇒ Hash

  Evaluates a JavaScript expression and returns the result.

• #export_cookies(name, path) ⇒ Hash

  Exports all cookies for a named page to a JSON file.

• #fetch(key) ⇒ Hash

  Retrieves a value from the daemon-scoped key-value store.

• #fill(name, selector = nil, value = nil, ref: nil) ⇒ Hash

  Fills an input element with a value.

• #hover(name, selector = nil, ref: nil) ⇒ Hash

  Moves the mouse to the centre of the element matched by selector.

• #import_cookies(name, path) ⇒ Hash

  Imports cookies from a JSON file into a named page.

• #initialize(socket_path = nil, recording_interceptor: nil) ⇒ Client constructor

  A new instance of Client.

• #navigate(name, url) ⇒ Hash

  Navigates a page to a URL.

• #page_close(name) ⇒ Hash

  Closes a named page and removes it from the session.

• #page_focus(name) ⇒ Hash

  Brings the named page's tab to front.

• #page_list ⇒ Hash

  Lists all open page names.

• #page_open(name, url: nil) ⇒ Hash

  Opens or focuses a named browser page.

• #pause(name, message: nil) ⇒ Hash

  Pauses automation on a page so a human can interact directly.

• #ping ⇒ Hash

  Checks if browserd is alive.

• #press(name, key) ⇒ Hash

  Fires a keydown + keyup event for the given key name on a page.

• #resume(name) ⇒ Hash

  Resumes automation on a paused page.

• #screenshot(name, path: nil, full: false) ⇒ Hash

  Takes a screenshot of a named page.

• #select(name, selector = nil, value = nil, ref: nil) ⇒ Hash

  Sets a element's value and fires a change event.

  #set_cookie(name, cookie_name, value, domain, path: "/") ⇒ Hash

  Sets a cookie on a named page.

  #shutdown ⇒ Hash

  Shuts down browserd gracefully.

  #snapshot(name, format: "elements", diff: false) ⇒ Hash

  Takes a DOM snapshot.

  #state_delete(name) ⇒ Object

  Permanently deletes a state bundle.

  #state_info(name) ⇒ Object

  Reads a single bundle's manifest.

  #state_list ⇒ Object

  Lists all stored state bundles (manifest only — no payload decryption).

  #state_load(name, passphrase: nil, skip_auth_check: false) ⇒ Object

  Restores a .bctl bundle into the running daemon.

  #state_save(name, origins: nil, flow: nil, flow_version: nil, passphrase: nil) ⇒ Hash

  Saves browser state (cookies + storage) into a single .bctl bundle.

  #storage_delete(name, stores: "all") ⇒ Hash

  Clears localStorage and/or sessionStorage for the page.

  #storage_export(name, path, stores: "all") ⇒ Hash

  Exports localStorage and/or sessionStorage to a JSON file.

  #storage_get(name, key, store: "local") ⇒ Hash

  Returns the value of a localStorage or sessionStorage key.

  #storage_import(name, path) ⇒ Hash

  Imports storage keys from a JSON file into the page's localStorage.

  #storage_set(name, key, value, store: "local") ⇒ Hash

  Sets a localStorage or sessionStorage key.

  #store(key, value) ⇒ Hash

  Stores a value in the daemon-scoped key-value store.

  #upload(name, selector = nil, path = nil, ref: nil) ⇒ Hash

  Sets a file-input element to the given file path.

  #url(name) ⇒ Hash

  Returns the current URL of a named page.

  #wait(name, selector, timeout: 30) ⇒ Hash

  Waits for a CSS selector to appear within the given timeout.

  Constructor Details

  #initialize(socket_path = nil, recording_interceptor: nil) ⇒ Client

  Returns a new instance of Client.

  # File 'lib/browserctl/client.rb', line 12
  
  def initialize(socket_path = nil, recording_interceptor: nil)
    @socket_path = socket_path || auto_discover_socket
    @recording_interceptor = recording_interceptor
  end
  

  Instance Method Details

  #auth_check(name, include_cookies: false, state: nil, suggested_flow: nil) ⇒ Object

  Runs the auth_required detector against a named page. Returns either { ok: true, auth_required: false } or an AUTH_REQUIRED error response.

  Parameters:

  • name (String) —

    page name

  • include_cookies (Boolean) (defaults to: false) —

    also feed the page's current cookies into the detector (catches expired-cookie auth)

  • state (String, nil) (defaults to: nil) —

    bundle name the caller was working with; passed back verbatim so callers can recover without bookkeeping

  • suggested_flow (String, nil) (defaults to: nil) —

    flow name to surface when triggered

  # File 'lib/browserctl/client.rb', line 392
  
  def auth_check(name, include_cookies: false, state: nil, suggested_flow: nil)
    call("auth_check",
         name: name,
         include_cookies: include_cookies,
         state: state,
         suggested_flow: suggested_flow)
  end
  

  #call(cmd, **params) ⇒ Object

  # File 'lib/browserctl/client.rb', line 17
  
  def call(cmd, **params)
    result = communicate(JSON.generate({ cmd: cmd }.merge(params)))
    recording_interceptor.append(cmd, response: result, params: params)
    result
  rescue Errno::ENOENT, Errno::ECONNREFUSED
    raise DaemonUnavailableError, "browserd is not running — start it with: browserd"
  end
  

  #click(name, selector = nil, ref: nil) ⇒ Hash

  Clicks an element identified by CSS selector or snapshot ref.

  Parameters:

  • name (String) —

    logical page name

  • selector (String, nil) (defaults to: nil) —

    CSS selector

  • ref (String, nil) (defaults to: nil) —

    snapshot ref (e.g. "e3")

  Returns:

  • (Hash) —

    { ok: true } or { error: }

  # File 'lib/browserctl/client.rb', line 51
  
  def click(name, selector = nil, ref: nil)
    unless selector || ref
      raise Browserctl::Error.new(
        "click: provide selector or ref",
        code: Browserctl::Error::Codes::INVALID_SELECTOR_REF,
        context: { method: :click, name: name }
      )
    end
  
    call("click", name: name, selector: selector, ref: ref,
                  capture_post_snapshot: recording_interceptor.capture_post_snapshot_flag)
  end
  

  #cookies(name) ⇒ Hash

  Returns all cookies for a named page.

  Parameters:

  • name (String) —

    logical page name

  Returns:

  • (Hash) —

    { ok: true, cookies: [Hash] } or { error: }

  # File 'lib/browserctl/client.rb', line 160
  
  def cookies(name)              = call("cookies", name: name)
  

  #data_delete(name, scope:) ⇒ Hash

  Clears every entry in the given browser-side scope.

  Parameters:

  • name (String) —

    logical page name

  • scope (String) —

    one of "cookies", "localStorage", "sessionStorage"

  Returns:

  • (Hash) —

    { ok: true, scope:, deleted: N } or { error:, code: }

  # File 'lib/browserctl/client.rb', line 277
  
  def data_delete(name, scope:)
    call("data_delete", name: name, scope: scope)
  end
  

  #data_get(name, key, scope:) ⇒ Hash

  Reads a single key from the given browser-side scope. Introduced in v0.15 as the unified replacement for storage_get / cookies (see ADR-0021).

  Parameters:

  • name (String) —

    logical page name

  • key (String) —

    storage key (n/a for scope: "cookies"; use #data_list)

  • scope (String) —

    one of "cookies", "localStorage", "sessionStorage"

  Returns:

  • (Hash) —

    { ok: true, scope:, key:, value: } or { error:, code: }

  # File 'lib/browserctl/client.rb', line 255
  
  def data_get(name, key, scope:)
    call("data_get", name: name, key: key, scope: scope)
  end
  

  #data_list(name, scope:) ⇒ Hash

  Lists every entry in the given browser-side scope.

  Parameters:

  • name (String) —

    logical page name

  • scope (String) —

    one of "cookies", "localStorage", "sessionStorage"

  Returns:

  • (Hash) —

    { ok: true, scope:, entries: [...], count: N } or { error:, code: }

  # File 'lib/browserctl/client.rb', line 285
  
  def data_list(name, scope:)
    call("data_list", name: name, scope: scope)
  end
  

  #data_set(name, key, value, scope:, domain: nil, path: "/") ⇒ Hash

  Writes a single key/value into the given browser-side scope. For scope: "cookies", domain: is required and path: defaults to "/".

  Parameters:

  • name (String) —

    logical page name

  • key (String) —

    storage key (cookie name when scope is cookies)

  • value (String) —

    value to store

  • scope (String) —

    one of "cookies", "localStorage", "sessionStorage"

  • domain (String, nil) (defaults to: nil) —

    cookie domain (required when scope is cookies)

  • path (String) (defaults to: "/") —

    cookie path (default: "/")

  Returns:

  • (Hash) —

    { ok: true, scope:, key: } or { error:, code: }

  # File 'lib/browserctl/client.rb', line 268
  
  def data_set(name, key, value, scope:, domain: nil, path: "/") # rubocop:disable Metrics/ParameterLists
    call("data_set", name: name, key: key, value: value,
                     scope: scope, domain: domain, path: path)
  end
  

  #delete_cookies(name) ⇒ Hash

  Deletes all cookies for a named page.

  Parameters:

  • name (String) —

    logical page name

  Returns:

  • (Hash) —

    { ok: true } or { error: }

  # File 'lib/browserctl/client.rb', line 177
  
  def delete_cookies(name) = call("delete_cookies", name: name)
  

  #devtools(name) ⇒ Hash

  Returns the Chrome DevTools URL for a named page.

  Parameters:

  • name (String) —

    logical page name

  Returns:

  • (Hash) —

    { ok: true, devtools_url: } or { error: }

  # File 'lib/browserctl/client.rb', line 139
  
  def devtools(name)             = call("devtools", name: name)
  

  #dialog_accept(name, text: nil) ⇒ Hash

  Pre-registers a one-shot handler to accept the next JS dialog on a page.

  Parameters:

  • name (String) —

    logical page name

  • text (String, nil) (defaults to: nil) —

    prompt text for window.prompt dialogs (ignored for alert/confirm)

  Returns:

  • (Hash) —

    { ok: true } or { error: }

  # File 'lib/browserctl/client.rb', line 351
  
  def dialog_accept(name, text: nil) = call("dialog_accept", name: name, text: text)
  

  #dialog_dismiss(name) ⇒ Hash

  Pre-registers a one-shot handler to dismiss the next JS dialog on a page.

  Parameters:

  • name (String) —

    logical page name

  Returns:

  • (Hash) —

    { ok: true } or { error: }

  # File 'lib/browserctl/client.rb', line 356
  
  def dialog_dismiss(name)           = call("dialog_dismiss", name: name)
  

  #evaluate(name, expression) ⇒ Hash

  Evaluates a JavaScript expression and returns the result.

  Parameters:

  • name (String) —

    logical page name

  • expression (String) —

    JavaScript expression

  Returns:

  • (Hash) —

    { ok: true, result: } or { error: }

  # File 'lib/browserctl/client.rb', line 115
  
  def evaluate(name, expression) = call("evaluate", name: name, expression: expression)
  

  #export_cookies(name, path) ⇒ Hash

  Exports all cookies for a named page to a JSON file. File I/O is client-side; daemon provides the cookie data.

  Parameters:

  • name (String) —

    logical page name

  • path (String) —

    file path to write cookies to

  Returns:

  • (Hash) —

    { ok: true, path:, count: } or { error: }

  # File 'lib/browserctl/client.rb', line 184
  
  def export_cookies(name, path)
    result = call("cookies", name: name)
    return result unless result[:ok]
  
    FileUtils.mkdir_p(File.dirname(path))
    File.open(path, "w", 0o600) { |f| f.write(JSON.generate(result[:cookies])) }
    { ok: true, path: path, count: result[:cookies].length }
  end
  

  #fetch(key) ⇒ Hash

  Retrieves a value from the daemon-scoped key-value store.

  Parameters:

  • key (String) —

    storage key

  Returns:

  • (Hash) —

    { ok: true, value: } or { error:, code: "key_not_found" }

  # File 'lib/browserctl/client.rb', line 155
  
  def fetch(key)                 = call("fetch", key: key)
  

  #fill(name, selector = nil, value = nil, ref: nil) ⇒ Hash

  Fills an input element with a value.

  Parameters:

  • name (String) —

    logical page name

  • selector (String, nil) (defaults to: nil) —

    CSS selector

  • value (String, nil) (defaults to: nil) —

    text to type

  • ref (String, nil) (defaults to: nil) —

    snapshot ref

  Returns:

  • (Hash) —

    { ok: true } or { error: }

  # File 'lib/browserctl/client.rb', line 70
  
  def fill(name, selector = nil, value = nil, ref: nil)
    unless selector || ref
      raise Browserctl::Error.new(
        "fill: provide selector or ref",
        code: Browserctl::Error::Codes::INVALID_SELECTOR_REF,
        context: { method: :fill, name: name }
      )
    end
  
    call("fill", name: name, selector: selector, ref: ref, value: value,
                 capture_post_snapshot: recording_interceptor.capture_post_snapshot_flag)
  end
  

  #hover(name, selector = nil, ref: nil) ⇒ Hash

  Moves the mouse to the centre of the element matched by selector.

  Parameters:

  • name (String) —

    logical page name

  • selector (String) (defaults to: nil) —

    CSS selector

  Returns:

  • (Hash) —

    { ok: true } or { error: }

  # File 'lib/browserctl/client.rb', line 299
  
  def hover(name, selector = nil, ref: nil)
    unless selector || ref
      raise Browserctl::Error.new(
        "hover: provide selector or ref",
        code: Browserctl::Error::Codes::INVALID_SELECTOR_REF,
        context: { method: :hover, name: name }
      )
    end
  
    call("hover", name: name, selector: selector, ref: ref)
  end
  

  #import_cookies(name, path) ⇒ Hash

  Imports cookies from a JSON file into a named page.

  Parameters:

  • name (String) —

    logical page name

  • path (String) —

    file path to read cookies from

  Returns:

  • (Hash) —

    { ok: true, count: } or { error: }

  Raises:

  • (Browserctl::Error)

  # File 'lib/browserctl/client.rb', line 197
  
  def import_cookies(name, path)
    raise Browserctl::Error, "cookie file not found: #{path}" unless File.exist?(path)
  
    cookies = JSON.parse(File.read(path), symbolize_names: true)
    call("import_cookies", name: name, cookies: cookies)
  end
  

  #navigate(name, url) ⇒ Hash

  Navigates a page to a URL. Returns challenge: true when Cloudflare is detected.

  Parameters:

  • name (String) —

    logical page name

  • url (String) —

    destination URL

  Returns:

  • (Hash) —

    { ok: true, url:, challenge: } or { error: }

  # File 'lib/browserctl/client.rb', line 44
  
  def navigate(name, url)        = call("navigate", name: name, url: url)
  

  #page_close(name) ⇒ Hash

  Closes a named page and removes it from the session.

  Parameters:

  • name (String) —

    logical page name

  Returns:

  • (Hash) —

    { ok: true } or { error: }

  # File 'lib/browserctl/client.rb', line 34
  
  def page_close(name)           = call("page_close", name: name)
  

  #page_focus(name) ⇒ Hash

  Brings the named page's tab to front. Only works when browserd was started with --headed.

  Parameters:

  • name (String) —

    logical page name

  Returns:

  • (Hash) —

    { ok: true } or { error: }

  # File 'lib/browserctl/client.rb', line 144
  
  def page_focus(name) = call("page_focus", name: name)
  

  #page_list ⇒ Hash

  Lists all open page names.

  Returns:

  • (Hash) —

    { pages: [String] }

  # File 'lib/browserctl/client.rb', line 38
  
  def page_list                  = call("page_list")
  

  #page_open(name, url: nil) ⇒ Hash

  Opens or focuses a named browser page.

  Parameters:

  • name (String) —

    logical page name

  • url (String, nil) (defaults to: nil) —

    optional URL to navigate to after opening

  Returns:

  • (Hash) —

    { ok: true, name: } or { error: }

  # File 'lib/browserctl/client.rb', line 29
  
  def page_open(name, url: nil)  = call("page_open",  name: name, url: url)
  

  #pause(name, message: nil) ⇒ Hash

  Pauses automation on a page so a human can interact directly.

  Parameters:

  • name (String) —

    logical page name

  • message (String, nil) (defaults to: nil) —

    optional message displayed to the human

  Returns:

  • (Hash) —

    { ok: true, paused: true, message: } or { error: }

  # File 'lib/browserctl/client.rb', line 129
  
  def pause(name, message: nil)  = call("pause",  name: name, message: message)
  

  #ping ⇒ Hash

  Checks if browserd is alive.

  Returns:

  • (Hash) —

    { ok: true, pid: } or raises if daemon is not running

  # File 'lib/browserctl/client.rb', line 119
  
  def ping                       = call("ping")
  

  #press(name, key) ⇒ Hash

  Fires a keydown + keyup event for the given key name on a page.

  Parameters:

  • name (String) —

    logical page name

  • key (String) —

    key name e.g. "Enter", "Tab", "Escape", "ArrowDown"

  Returns:

  • (Hash) —

    { ok: true } or { error: }

  # File 'lib/browserctl/client.rb', line 293
  
  def press(name, key) = call("press", name: name, key: key)
  

  #resume(name) ⇒ Hash

  Resumes automation on a paused page.

  Parameters:

  • name (String) —

    logical page name

  Returns:

  • (Hash) —

    { ok: true, paused: false } or { error: }

  # File 'lib/browserctl/client.rb', line 134
  
  def resume(name)               = call("resume", name: name)
  

  #screenshot(name, path: nil, full: false) ⇒ Hash

  Takes a screenshot of a named page.

  Parameters:

  • name (String) —

    logical page name

  • path (String, nil) (defaults to: nil) —

    output path (default: ~/.browserctl/screenshots/)

  • full (Boolean) (defaults to: false) —

    capture full page (default: false)

  Returns:

  • (Hash) —

    { ok: true, path: } or { error: }

  # File 'lib/browserctl/client.rb', line 88
  
  def screenshot(name, path: nil, full: false) = call("screenshot", name: name, path: path, full: full)
  

  #select(name, selector = nil, value = nil, ref: nil) ⇒ Hash

  Sets a

  element's value and fires a change event.