Marionette🔗ℹ

1 Introduction🔗ℹ

Marionette lets you control the Firefox web browser via the Marionette Protocol. This is the same interface used by Selenium, via geckodriver.

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 Examples🔗ℹ

Here are some simple examples of using marionette. The first saves a PNG file containing an image of the current racket-lang.org webpage:

> (require marionette            racket/file)

>

> (define data     (call-with-marionette/browser/page!      (lambda (p)        (page-goto! p "https://racket-lang.org")        (call-with-page-screenshot! p values))))

>

> (define filename     (make-temporary-file "~a.png"))

>

> (with-output-to-file filename     #:exists 'truncate/replace     (lambda ()       (write-bytes data)))

791931

>

> (printf "filename of page screenshot: ~v\n" (path->string filename))

filename of page screenshot: "/var/folders/6s/8kt06x656dddy8z5y0jmf_fc0000gn/T/16266838661626683866996.png"

This next example dowloads the HTML content of a password-protected web page:

#lang racket

(require marionette)

(define username "zipnarg")

(define nextcatalog-csc-minor-url

"https://nextcatalog-admin.calpoly.edu/collegesandprograms/\

collegeofengineering/computersciencesoftwareengineering/\

computerscienceminor/")

(define profile-path

(build-path "/Users/zipnarg/Library/Application Support/"

"Firefox/Profiles/s9y75gtr.wazoo"))

(define content

(call-with-marionette/browser/page!

#:profile profile-path

(λ (page)

(page-goto! page nextcatalog-csc-minor-url)

(printf "ready? ~v\n" (page-loaded? page))

(printf "page title: ~v\n" (page-title page))

(let ()

(define username-elt (page-query-selector! page "#username"))

(cond [username-elt

(element-type! username-elt username)]

[else

(error 'login "couldn't find username field.")]))

(let ()

(define password-elt (page-query-selector! page "#password"))

(cond [password-elt

(printf "password: ")

(define str (read-line))

(element-type! password-elt str)]

[else

(error 'login "couldn't find password field.")]))

(let ()

(define form-button (page-query-selector! page ".form-button"))

(cond [form-button

(element-click! form-button)]

[else

(error 'login "couldn't find login button.")]))

;; wait until the page is ready and the title is no longer

;; that of the login page

(let loop ()

(define loaded? (page-loaded? page))

(cond [loaded?

(define title (page-title page))

(cond [(equal? title "Cal Poly Web Login Service")

(printf "still login screen title, waiting...\n")

(sleep 1)

(loop)]

[else 'ok])]

[else

(printf "not ready, waiting...\n")

(sleep 1)

(loop)]))

(printf "final page title: ~v\n" (page-title page))

(page-content page))))

3 Reference🔗ℹ

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.

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

When the #:port argument is provided, the profile will be modified to instruct the marionette server to listen on that port.

When the #:user.js argument is provided, the contents of the hash will be set as preferences in the profile.

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

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

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

3.1 Browser🔗ℹ

Browsers represent a connection to a marionette-driven instance of Firefox. Browsers are not thread-safe, nor is it safe to interleave commands against the same marionette server. If you need concurrency, then create multiple marionettes and control them separately.

3.2 Page🔗ℹ

Added in version 1.4 of package marionette-lib.

3.3 Element🔗ℹ

Elements represent individual elements on a specific page. They are only valid for as long as the page they were queried from active. That is, if you query an element and then navigate off the page you got it from, it becomes invalid.

3.4 Capabilities🔗ℹ

3.5 Timeouts🔗ℹ

3.6 Keys🔗ℹ

This module provides bindings for special control characters that can be typed into an element or alert. Some examples:

(require marionette/key)

(map car (call-with-values

(lambda () (module->exports 'marionette/key))

(compose1 cdaar list)))

Added in version 1.3 of package marionette-lib.