Module: Browserctl::Driver::PageDriver

Included in:
FerrumPageDriver
Defined in:
lib/browserctl/driver/page_driver.rb

Overview

PageDriver is the interface every handler in ‘lib/browserctl/server/handlers/` talks to instead of touching a raw Ferrum page. It exists so unit tests can swap in a `FakePageDriver` (see `spec/support/fake_page_driver.rb`) without spawning a real browser.

This module is intentionally a thin contract: Ruby has no real interfaces, so the implementation is duck-typed. The method list below is the entire public surface handlers may use. New entries here require a corresponding implementation in FerrumPageDriver and the test double, plus a handler that justifies them — do not add methods speculatively.

Element-returning methods (currently only #at_css) return whatever the underlying driver returns. The fake driver returns stub objects with matching duck-typed methods (‘focus`, `type`, `click`, `evaluate`, `select_file`). Handlers should treat these as opaque element handles.

PageDriver lives in the Extension zone of the public surface (see ‘docs/reference/api-stability.md`). It is a testing seam, not an invitation to ship a non-Ferrum backend — that path is explicitly a non-goal of v0.15 (`docs/plans/v0.15-lock.md`).

Instance Method Summary collapse

Instance Method Details

#activate ⇒ Object

Bring the page tab to the foreground (headed mode only).

Raises:

  • (NotImplementedError) 


53
 
# File 'lib/browserctl/driver/page_driver.rb', line 53

def activate = raise NotImplementedError

#at_css(selector) ⇒ Object?

Find the first element matching the CSS selector.

Parameters:

  • selector (String)

Returns:

  • (Object, nil) —

    an element handle (duck-typed: ‘focus`, `type`, `click`, `evaluate`, `select_file`) or nil if no match

Raises:

  • (NotImplementedError) 


45
 
# File 'lib/browserctl/driver/page_driver.rb', line 45

def at_css(selector) = raise NotImplementedError

#body ⇒ String

Returns the current page body HTML.

Returns:

  • (String) —

    the current page body HTML

Raises:

  • (NotImplementedError) 


34
 
# File 'lib/browserctl/driver/page_driver.rb', line 34

def body = raise NotImplementedError

#close ⇒ Object

Close the underlying page/tab.

Raises:

  • (NotImplementedError) 


56
 
# File 'lib/browserctl/driver/page_driver.rb', line 56

def close = raise NotImplementedError

#cookies_all ⇒ Hash{String => Object}

Returns all cookies for the page, keyed by cookie name, with each value responding to ‘to_h`.

Returns:

  • (Hash{String => Object}) —

    all cookies for the page, keyed by cookie name, with each value responding to ‘to_h`.

Raises:

  • (NotImplementedError) 


76
 
# File 'lib/browserctl/driver/page_driver.rb', line 76

def cookies_all = raise NotImplementedError

#cookies_clear ⇒ Object

Clear every cookie on the page.

Raises:

  • (NotImplementedError) 


83
 
# File 'lib/browserctl/driver/page_driver.rb', line 83

def cookies_clear = raise NotImplementedError

#cookies_set ⇒ Object

Set a cookie. Accepts ‘name:`, `value:`, `domain:`, `path:`, and any of `httponly:`, `secure:`, `expires:`.

Raises:

  • (NotImplementedError) 


80
 
# File 'lib/browserctl/driver/page_driver.rb', line 80

def cookies_set(**) = raise NotImplementedError

#current_url ⇒ String

Returns the current top-frame URL.

Returns:

  • (String) —

    the current top-frame URL

Raises:

  • (NotImplementedError) 


31
 
# File 'lib/browserctl/driver/page_driver.rb', line 31

def current_url = raise NotImplementedError

#evaluate(expression) ⇒ Object

Evaluate a JS expression in the page context.

Parameters:

  • expression (String)

Returns:

  • (Object) —

    the JSON-decoded result

Raises:

  • (NotImplementedError) 


39
 
# File 'lib/browserctl/driver/page_driver.rb', line 39

def evaluate(expression) = raise NotImplementedError

#go_to(url) ⇒ Object

Navigate the page to the given URL. Blocks until load completes.

Parameters:

  • url (String)

Raises:

  • (NotImplementedError) 


28
 
# File 'lib/browserctl/driver/page_driver.rb', line 28

def go_to(url) = raise NotImplementedError

#keyboard_down(key) ⇒ Object

Press a key down. Pair with #keyboard_up.

Raises:

  • (NotImplementedError) 


66
 
# File 'lib/browserctl/driver/page_driver.rb', line 66

def keyboard_down(key) = raise NotImplementedError

#keyboard_up(key) ⇒ Object

Release a key.

Raises:

  • (NotImplementedError) 


69
 
# File 'lib/browserctl/driver/page_driver.rb', line 69

def keyboard_up(key) = raise NotImplementedError

#mouse_move(x:, y:) ⇒ Object

Move the mouse pointer to viewport coordinates.

Raises:

  • (NotImplementedError) 


72
 
# File 'lib/browserctl/driver/page_driver.rb', line 72

def mouse_move(x:, y:) = raise NotImplementedError # rubocop:disable Naming/MethodParameterName

#off(event, id) ⇒ Object

Remove a subscription created by #on.

Raises:

  • (NotImplementedError) 


63
 
# File 'lib/browserctl/driver/page_driver.rb', line 63

def off(event, id) = raise NotImplementedError

#on(event) ⇒ Object

Subscribe to a page event (currently only ‘:dialog`).

Returns:

  • (Object) —

    a subscription id usable with #off

Raises:

  • (NotImplementedError) 


60
 
# File 'lib/browserctl/driver/page_driver.rb', line 60

def on(event, &) = raise NotImplementedError

#screenshot(path:, full: false) ⇒ Object

Capture a screenshot to disk.

Parameters:

  • path (String)
  • full (Boolean) (defaults to: false)

Raises:

  • (NotImplementedError) 


50
 
# File 'lib/browserctl/driver/page_driver.rb', line 50

def screenshot(path:, full: false) = raise NotImplementedError

#target_id ⇒ Object

Underlying CDP target id; used by the devtools handler. Backends that do not expose CDP should raise.

Raises:

  • (NotImplementedError) 


87
 
# File 'lib/browserctl/driver/page_driver.rb', line 87

def target_id = raise NotImplementedError