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