Marionette
1 Introduction
2 Limitations
3 Reference
start-marionette!
call-with-marionette!
call-with-marionette/  browser!
call-with-marionette/  browser/  page!
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
page-load-strategy/  c
unhandled-prompt-behavior/  c
capabilities
make-capabilities
3.5 Timeouts
timeouts
make-timeouts
3.6 Rect
rect
7.9

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    
  #:port port    
  #:safe-mode? safe-mode?    
  #:headless? headless?    
  #:timeout timeout])  (-> void?)
  command : absolute-path? = "/usr/local/bin/firefox"
  profile : (or/c false/c absolute-path?) = #f
  port : (or/c false/c (integer-in 1 65535)) = #f
  safe-mode? : boolean? = #t
  headless? : boolean? = #t
  timeout : exact-nonnegative-integer? = 5

procedure

(call-with-marionette! p)  any

  p : (-> any)

procedure

(call-with-marionette/browser! p)  any

  p : (-> browser? any)

procedure

(call-with-marionette/browser/page! p)  any

  p : (-> page? 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.

If port is provided, then the profile will be modified to instruct the marionette server to listen on that port.

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.

call-with-marionette/browser! composes call-with-marionette! and call-with-browser! together. Keyword arguments are passed through to start-marionette!.

call-with-marionette/browser/page! composes call-with-marionette/browser! and call-with-page! together. Keyword arguments are passed through to start-marionette!.

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

value

page-load-strategy/c : (or/c "none" "eager" "normal")

value

unhandled-prompt-behavior/c : 
(or/c "dismiss"
      "dismiss and notify"
      "accept"
      "accept and notify"
      "ignore")
Contracts used by the functions in this module.

struct

(struct capabilities (timeouts
    page-load-strategy
    unhandled-prompt-behavior
    accept-insecure-certs?)
    #:extra-constructor-name make-capabilities)
  timeouts : timeouts?
  page-load-strategy : page-load-strategy/c
  unhandled-prompt-behavior : unhandled-prompt-behavior/c
  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.