Marionette

7.7

top ← prev up next →

Marionette

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)
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.

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.

procedure
(browser-viewport-size b) →
exact-nonnegative-integer?
exact-nonnegative-integer?
  b : browser?
procedure
(set-browser-viewport-size! b w h) → void?
  b : browser?
  w : exact-nonnegative-integer?
  h : exact-nonnegative-integer?

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.

top ← prev up next →