Marionette
1 Introduction
2 Limitations
3 Reference
start-marionette!
call-with-marionette!
call-with-browser!
call-with-page!
3.1 Browser
browser?
browser-connect!
browser-disconnect!
browser-timeouts
set-browser-timeouts!
browser-viewport-size
set-browser-viewport-size!
make-browser-page!
browser-capabilities
browser-pages
browser-focus!
3.2 Page
page?
page=?
page-close!
page-refresh!
page-goto!
page-go-back!
page-go-forward!
page-execute-async!
page-interactive?
page-loaded?
page-title
page-url
page-content
set-page-content!
page-wait-for!
page-query-selector!
page-query-selector-all!
page-alert-text
page-alert-accept!
page-alert-dismiss!
page-alert-type!
call-with-page-screenshot!
3.3 Element
element?
element=?
element-click!
element-clear!
element-type!
element-query-selector!
element-query-selector-all!
element-enabled?
element-selected?
element-visible?
element-handle
element-tag
element-text
element-rect
element-attribute
element-property
call-with-element-screenshot!
3.4 Capabilities
capabilities
make-capabilities
3.5 Timeouts
timeouts
make-timeouts
3.6 Rect
rect
7.4

Marionette

Bogdan Popa <bogdan@defn.io>

1 Introduction

Marionette lets you control the Firefox web browser via the Marionette Protocol.

To use this library, you need to have a running Firefox instance with the marionette protocol enabled. To do this, all you have to do is run the firefox binary with the -marionette flag.

2 Limitations

The protocol doesn’t (seem to) support operating on more than one page concurrently within one browser session. To get around this, simply initiate multiple browser sessions via call-with-browser!.

3 Reference

 (require marionette) package: marionette-lib

procedure

(start-marionette! [#:command command    
  #:profile profile    
  #:safe-mode? safe-mode?    
  #:headless? headless?    
  #:timeout timeout])  (-> void?)
  command : absolute-path? = "/usr/local/bin/firefox"
  profile : (or/c false/c absolute-path?) = #f
  safe-mode? : boolean? = #t
  headless? : boolean? = #t
  timeout : exact-nonnegative-integer? = 5

procedure

(call-with-marionette! p)  any

  p : (-> any)
Start a marionette-enabled instance of the Firefox browser using profile. The return value is a procedure that can be used to stop the browser.

The command argument controls the path to the firefox binary. If not provided, the system PATH is searched along with the /Applications folder on macOS.

If profile is #f, then a temporary path si created for the profile and it it subsequently removed when the browser is stopped.

call-with-marionette! accepts the same keyword arguments that start-marionette! does. It starts the browser, applies its p argument then immediately stops the browser.

procedure

(call-with-browser! p    
  [#:host host    
  #:port port    
  #:capabilities capabilities])  any
  p : (-> browser? any)
  host : non-empty-string? = "127.0.0.1"
  port : (integer-in 1 65535) = 2828
  capabilities : capabilities? = (make-capabilities)
Calls p after initiating a new browser session and disconnects after p finishes executing.

procedure

(call-with-page! b p)  any

  b : browser?
  p : (-> page? any)
Calls p after creating a new page and closes said page after p finishes executing.

3.1 Browser

 (require marionette/browser) package: marionette-lib

procedure

(browser? b)  boolean?

  b : any/c
Returns #t when b is a browser.

procedure

(browser-connect! [#:host host    
  #:port port    
  #:capabilities capabilities])  browser?
  host : non-empty-string? = "127.0.0.1"
  port : (integer-in 1 65535) = 2828
  capabilities : capabilities? = (make-capabilities)
Connects to the marionette server at host and port and returns a browser? session.

procedure

(browser-disconnect! b)  void?

  b : browser?
Disconnects b from its server.

procedure

(browser-timeouts b)  timeouts?

  b : browser?

procedure

(set-browser-timeouts! b t)  void?

  b : browser?
  t : timeouts?
Get or set the b’s current timeout settings.

Get or set b’s current viewport size.

procedure

(make-browser-page! b)  page?

  b : browser?
Open a new page in b and return it.

procedure

(browser-capabilities b)  capabilities?

  b : browser?
Retrieve the capabilities? for b.

procedure

(browser-pages b)  (listof page?)

  b : browser?
Lists all the pages belonging to b.

procedure

(browser-focus! b p)  void?

  b : browser?
  p : page?
Makes p the currently active page.

3.2 Page

 (require marionette/page) package: marionette-lib

procedure

(page? p)  boolean?

  p : any/c
Returns #t when p is a page.

procedure

(page=? p1 p2)  boolean?

  p1 : page?
  p2 : page?
Returns #t when p1 and p2 represent the same page (i.e. they have the same id but are not necessarily the same object in memory).

procedure

(page-close! p)  void?

  p : page?
Tells the browser to close p.

procedure

(page-refresh! p)  void?

  p : page?
Tells the browser to refresh p.

procedure

(page-goto! p location)  void?

  p : page?
  location : (or/c string? url?)
Navigates p to location.

procedure

(page-go-back! p)  void?

  p : page?

procedure

(page-go-forward! p)  void?

  p : page?
Moves p backward and forward through its history.

procedure

(page-execute-async! p s arg ...)  jsexpr?

  p : page?
  s : string?
  arg : any/c
Executes the script s on p and returns its result.

procedure

(page-interactive? p)  boolean?

  p : page?

procedure

(page-loaded? p)  boolean?

  p : page?
Ascertain the current "ready state" of p.

procedure

(page-title p)  string?

  p : page?

procedure

(page-url p)  url?

  p : page?
Accessors for p’s title and url, respectively.

procedure

(page-content p)  string?

  p : page?

procedure

(set-page-content! p s)  void?

  p : page?
  s : string?
Get or set p’s HTML content.

procedure

(page-wait-for! p    
  selector    
  [#:timeout timeout    
  #:visible? visible?])  (or/c false/c element?)
  p : page?
  selector : non-empty-string?
  timeout : (and/c real? (not/c negative?)) = 30
  visible? : boolean? = #t
Waits for an element matching selector to appear on p or timeout milliseconds to pass. If visible? is #t, then the element must be visible on the page for it to match.

procedure

(page-query-selector! p selector)  (or/c false/c element?)

  p : page?
  selector : non-empty-string?

procedure

(page-query-selector-all! p selector)  (listof element?)

  p : page?
  selector : non-empty-string?
Query p for either the first or all element?s that match the given selector.

procedure

(page-alert-text p)  string?

  p : page?

procedure

(page-alert-accept! p)  void?

  p : page?

procedure

(page-alert-dismiss! p)  void?

  p : page?

procedure

(page-alert-type! p text)  void?

  p : page?
  text : string?
Interact with the current prompt on p. By default, all prompts are automatically dismissed, so you won’t have anything to interact with. To change this, specify a different unhandled prompt behavior in your capabilities?.

procedure

(call-with-page-screenshot! page    
  proc    
  [#:full? full?])  any
  page : page?
  proc : (-> bytes? any)
  full? : boolean? = #t
Take a screenshot of page and call proc with the resulting bytes?. full? determines whether or not the entire page is captured.

3.3 Element

 (require marionette/element) package: marionette-lib

procedure

(element? e)  boolean?

  e : any/c
Returns #t when e is a element.

procedure

(element=? e1 e2)  boolean?

  e1 : element?
  e2 : element?
Returns #t when e1 and e2 represent the same element (i.e. they have the same handle but are not necessarily the same object in memory).

procedure

(element-click! e)  void?

  e : element?
Clicks on e.

procedure

(element-clear! e)  void?

  e : element?
Clears e’s contents if it is an HTMLInputElement.

procedure

(element-type! e text)  void

  e : element?
  text : string?
Types text into e.

procedure

(element-query-selector! e selector)  (or/c false/c element?)

  e : element?
  selector : non-empty-string?

procedure

(element-query-selector-all! e selector)  (listof element?)

  e : element?
  selector : non-empty-string?
Query e for either the first or all element?s belonging to it that match the given selector.

procedure

(element-enabled? e)  boolean?

  e : element?

procedure

(element-selected? e)  boolean?

  e : element?

procedure

(element-visible? e)  boolean?

  e : element?
Returns #t if e is enabled, selected or visible, respectively.

procedure

(element-handle e)  handle/c

  e : element?

procedure

(element-tag e)  string?

  e : element?

procedure

(element-text e)  string?

  e : element?

procedure

(element-rect e)  rect?

  e : element?
Access various e fields.

procedure

(element-attribute e name)  (or/c false/c string?)

  e : element?
  name : string?

procedure

(element-property e name)  (or/c false/c string?)

  e : element
  name : string?
Retrieve e’s attribute named name statically and dynamically, respectively.

procedure

(call-with-element-screenshot! e p)  any

  e : element?
  p : (-> bytes? any)
Take a screenshot of e and call proc with the resulting bytes?.

3.4 Capabilities

 (require marionette/capabilities)
  package: marionette-lib

struct

(struct capabilities (timeouts
    page-load-strategy
    unhandled-prompt-behavior
    accept-insecure-certs?)
    #:extra-constructor-name make-capabilities)
  timeouts : timeouts?
  page-load-strategy : (or/c "none" "eager" "normal")
  unhandled-prompt-behavior : 
(or/c "dismiss" "dismiss and notify"
      "accept" "accept and notify"
      "ignore")
  accept-insecure-certs? : boolean?
This struct is used to represent a session’s capabilities. Think of these as settings/behaviors that you can tweak when you create a new session via browser-connect!.

procedure

(make-capabilities 
  [#:timeouts timeouts 
  #:page-load-strategy page-load-strategy 
  #:unhandled-prompt-behavior unhandled-prompt-behavior 
  #:accept-insecure-certs? accept-insecure-certs?]) 
  capabilities?
  timeouts : timeouts? = (make-timeouts)
  page-load-strategy : page-load-strategy/c = "normal"
  unhandled-prompt-behavior : unhandled-prompt-behavior/c
   = "dismiss and notify"
  accept-insecure-certs? : boolean? = #f
A convenience constructor for capabilities.

3.5 Timeouts

 (require marionette/timeouts) package: marionette-lib

struct

(struct timeouts (script page-load implicit)
    #:extra-constructor-name make-timeouts)
  script : exact-nonnegative-integer?
  page-load : exact-nonnegative-integer?
  implicit : exact-nonnegative-integer?
This struct is used to represent the browser’s timeout settings.

procedure

(make-timeouts [#:script script    
  #:page-load page-load    
  #:implicit implicit])  timeouts?
  script : exact-nonnegative-integer? = 30000
  page-load : exact-nonnegative-integer? = 300000
  implicit : exact-nonnegative-integer? = 0
A convenience constructor for timeouts.

3.6 Rect

 (require marionette/rect) package: marionette-lib

struct

(struct rect (x y w h)
    #:extra-constructor-name make-rect)
  x : exact-integer?
  y : exact-integer?
  w : natural?
  h : natural?
This struct is used to represent an element’s bounding client rect.