Class: Browserctl::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/browserctl/client.rb

Overview

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

Instance Method Summary collapse

Constructor Details

#initialize(socket_path = Browserctl.socket_path) ⇒ Client

Returns a new instance of Client.



11
12
13
 
# File 'lib/browserctl/client.rb', line 11

def initialize(socket_path = Browserctl.socket_path)
  @socket_path = socket_path
end

Instance Method Details

#call(cmd, **params) ⇒ Object 



15
16
17
18
19
20
21
 
# File 'lib/browserctl/client.rb', line 15

def call(cmd, **params)
  result = communicate(JSON.generate({ cmd: cmd }.merge(params)))
  Recording.append(cmd, **params) if result[:ok]
  result
rescue Errno::ENOENT, Errno::ECONNREFUSED
  raise "browserd is not running — start it with: browserd"
end

#clear_cookies(name) ⇒ Hash

Clears all cookies for a named page.

Parameters:

  • name (String) —

    logical page name

Returns:

  • (Hash) —

    ‘{ ok: true }` or `{ error: }`



153
 
# File 'lib/browserctl/client.rb', line 153

def clear_cookies(name) = call("clear_cookies", name: name)

#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: }`

Raises:

  • (ArgumentError) 


49
50
51
52
53
 
# File 'lib/browserctl/client.rb', line 49

def click(name, selector = nil, ref: nil)
  raise ArgumentError, "click: provide selector or ref:" unless selector || ref

  call("click", name: name, selector: selector, ref: ref)
end

#close_page(name) ⇒ Hash

Closes a named page and removes it from the session.

Parameters:

  • name (String) —

    logical page name

Returns:

  • (Hash) —

    ‘{ ok: true }` or `{ error: }`



32
 
# File 'lib/browserctl/client.rb', line 32

def close_page(name)           = call("close_page", name: name)

#cookies(name) ⇒ Hash

Returns all cookies for a named page.

Parameters:

  • name (String) —

    logical page name

Returns:

  • (Hash) —

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



136
 
# File 'lib/browserctl/client.rb', line 136

def cookies(name) = call("cookies", 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: }`



108
 
# File 'lib/browserctl/client.rb', line 108

def evaluate(name, expression) = call("evaluate",    name: name, expression: expression)

#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: }`

Raises:

  • (ArgumentError) 


61
62
63
64
65
 
# File 'lib/browserctl/client.rb', line 61

def fill(name, selector = nil, value = nil, ref: nil)
  raise ArgumentError, "fill: provide selector or ref:" unless selector || ref

  call("fill", name: name, selector: selector, ref: ref, value: value)
end

#goto(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: }`



42
 
# File 'lib/browserctl/client.rb', line 42

def goto(name, url)            = call("goto", name: name, url: url)

#inspect_page(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: }`



131
 
# File 'lib/browserctl/client.rb', line 131

def inspect_page(name)         = call("inspect", name: name)

#list_pages ⇒ Hash

Lists all open page names.

Returns:

  • (Hash) —

    ‘{ pages: [String] }`



36
 
# File 'lib/browserctl/client.rb', line 36

def list_pages                 = call("list_pages")

#open_page(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: }`



27
 
# File 'lib/browserctl/client.rb', line 27

def open_page(name, url: nil)  = call("open_page",  name: name, url: url)

#pause(name) ⇒ Hash

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

Parameters:

  • name (String) —

    logical page name

Returns:

  • (Hash) —

    ‘{ ok: true, paused: true }` or `{ error: }`



121
 
# File 'lib/browserctl/client.rb', line 121

def pause(name)                = call("pause",   name: name)

#ping ⇒ Hash

Checks if browserd is alive.

Returns:

  • (Hash) —

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



112
 
# File 'lib/browserctl/client.rb', line 112

def ping                       = call("ping")

#resume(name) ⇒ Hash

Resumes automation on a paused page.

Parameters:

  • name (String) —

    logical page name

Returns:

  • (Hash) —

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



126
 
# File 'lib/browserctl/client.rb', line 126

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: }`



72
 
# File 'lib/browserctl/client.rb', line 72

def screenshot(name, path: nil, full: false) = call("screenshot", name: name, path: path, full: full)

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

Sets a cookie on a named page.

Parameters:

  • name (String) —

    logical page name

  • cookie_name (String) —

    cookie name (e.g. “cf_clearance”)

  • value (String) —

    cookie value

  • domain (String) —

    cookie domain (e.g. “.example.com”)

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

    cookie path (default: “/”)

Returns:

  • (Hash) —

    ‘{ ok: true }` or `{ error: }`



145
146
147
148
 
# File 'lib/browserctl/client.rb', line 145

def set_cookie(name, cookie_name, value, domain, path: "/")
  call("set_cookie", name: name, cookie_name: cookie_name,
                     value: value, domain: domain, path: path)
end

#shutdown ⇒ Hash

Shuts down browserd gracefully.

Returns:

  • (Hash) —

    ‘{ ok: true }`



116
 
# File 'lib/browserctl/client.rb', line 116

def shutdown                   = call("shutdown")

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

Takes a DOM snapshot. Returns ‘challenge: true` when Cloudflare is detected.

Parameters:

  • name (String) —

    logical page name

  • format (String) (defaults to: "ai") —

    “ai” (token-efficient JSON) or “html” (raw HTML)

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

    return only elements changed since last snapshot

Returns:

  • (Hash) —

    ‘{ ok: true, snapshot:, challenge: }` or `{ ok: true, html:, challenge: }` or `{ error: }`



79
80
81
 
# File 'lib/browserctl/client.rb', line 79

def snapshot(name, format: "ai", diff: false)
  call("snapshot", name: name, format: format, diff: diff)
end

#url(name) ⇒ Hash

Returns the current URL of a named page.

Parameters:

  • name (String) —

    logical page name

Returns:

  • (Hash) —

    ‘{ ok: true, url: }` or `{ error: }`



102
 
# File 'lib/browserctl/client.rb', line 102

def url(name)                  = call("url",         name: name)

#wait_for(name, selector, timeout: 10) ⇒ Hash

Waits for a CSS selector to appear (short timeout).

Parameters:

  • name (String) —

    logical page name

  • selector (String) —

    CSS selector to wait for

  • timeout (Numeric) (defaults to: 10) —

    seconds before giving up (default: 10)

Returns:

  • (Hash) —

    ‘{ ok: true }` or `{ error: }`



88
 
# File 'lib/browserctl/client.rb', line 88

def wait_for(name, selector, timeout: 10) = call("wait_for", name: name, selector: selector, timeout: timeout)

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

Polls for a CSS selector with a longer timeout (suitable for async operations).

Parameters:

  • name (String) —

    logical page name

  • selector (String) —

    CSS selector to poll for

  • timeout (Numeric) (defaults to: 30) —

    seconds before giving up (default: 30)

Returns:

  • (Hash) —

    ‘{ ok: true, selector: }` or `{ error: }`



95
96
97
 
# File 'lib/browserctl/client.rb', line 95

def watch(name, selector, timeout: 30)
  call("watch", name: name, selector: selector, timeout: timeout)
end