etaoin.api — etaoin 1.0.40

A wrapper over the W3C WebDriver Specification to automate popular browsers.

Tries to normalize differences across the various implementations.

See the User Guide for details and examples.

This is a rich API:

WebDriver

• with-driver boot-driver defaults defaults-global when-not-drivers
• with-chrome with-chrome-headless chrome chrome-headless chrome? when-chrome when-not-chrome
• with-edge with-edge-headless edge edge-headless when-edge when-not-edge
• with-firefox with-firefox-headless firefox firefox-headless firefox? when-firefox when-not-firefox
• with-phantom phantom phantom? when-phantom when-not-phantom
• with-safari safari safari? when-safari when-not-safari
• driver? running? headless? when-headless when-not-headless
• disconnect-driver stop-driver quit

WebDriver Lower Level Comms

• execute with-http-error

Driver Sessions

• get-status create-session delete-session

Querying/Selecting DOM Elements

• query query-all query-tree
• exists? absent?
• displayed? displayed-el? enabled? enabled-el? disabled? invisible? visible?
• child children
• get-element-tag get-element-tag-el
• get-element-attr get-element-attr-el get-element-attrs
• get-element-property get-element-property-el get-element-properties
• has-class? has-class-el? has-no-class?
• get-element-css get-element-css-el get-element-csss
• get-element-text get-element-text-el has-text?
• get-element-inner-html get-element-inner-html-el
• get-element-value get-element-value-el
• get-element-size get-element-size-el get-element-location get-element-location-el get-element-box intersects?
• use-css with-css use-xpath with-xpath

Browser Navigation

• go get-url get-hash set-hash
• back forward
• refresh reload

Mouse/Pointer

• click click-el click-single click-multi
• left-click left-click-on
• middle-click middle-click-on
• right-click right-click-on
• mouse-click mouse-move-to mouse-click-on
• double-click double-click-el
• drag-and-drop mouse-btn-down mouse-btn-up
• touch-down touch-move touch-tap touch-up

Inputs/Forms

• fill fill-active fill-el fill-multi
• fill-human fill-human-el fill-human-multi
• select selected? selected-el?
• upload-file remote-file
• disabled? enabled?
• clear clear-el
• submit

Cookies

• get-cookie get-cookies
• set-cookie
• delete-cookie delete-cookies

Alerts

• has-alert? has-no-alert?
• get-alert-text
• accept-alert dismiss-alert

Scrolling

• get-scroll
• scroll scroll-by
• scroll-bottom scroll-top
• scroll-down scroll-up scroll-left scroll-right
• scroll-offset
• scroll-query

Scripting

• js-execute js-async js-localstorage-clear el->ref add-script

Browser Windows

• get-window-handle get-window-handles
• get-window-position set-window-position
• get-window-size set-window-size
• maximize
• switch-window switch-window-next
• close-window

Frames

• switch-frame switch-frame-first switch-frame-parent switch-frame-top with-frame

Page Info

• get-source get-title

Screenshots

• screenshot screenshot-element with-screenshots

Print to PDF

• print-page

Browser Info

• supports-logs? get-log-types get-logs
• get-user-agent
• with-postmortem

Waiting

• doto-wait wait with-wait
• *wait-interval* *wait-timeout* with-wait-interval with-wait-timeout
• wait-exists wait-absent
• wait-visible wait-invisible
• wait-disabled wait-enabled
• wait-has-alert
• wait-has-class
• wait-has-text wait-has-text-everywhere
• wait-predicate
• wait-running

Browser Timeouts

• get-implicit-timeout set-implicit-timeout
• get-page-load-timeout set-page-load-timeout
• get-script-timeout set-script-timeout with-script-timeout

WebDriver Actions

• make-action-input make-key-input make-mouse-input make-pen-input make-pointer-input make-touch-input
• add-action
• add-double-pause
• add-key-down add-key-press add-key-up with-key-down
• add-pause
• add-pointer-click add-pointer-click-el add-pointer-double-click add-pointer-double-click-el
• add-pointer-down add-pointer-up
• with-pointer-btn-down with-pointer-left-btn-down with-mouse-btn
• add-pointer-move add-pointer-move-to-el
• add-pointer-cancel
• perform-actions release-actions

Convenience

• rand-uuid when-predicate when-not-predicate

*wait-interval* clj

Frequency in seconds to check if we should still wait, default for wait-* functions.

*wait-timeout* clj

Maximum seconds to wait, default for wait-* functions.

absent? clj

(absent? driver q & more)

Opposite of exists?.

accept-alert clj multimethod

(accept-alert driver)

Have driver accept open alert dialog.

add-action clj

(add-action input action)

Return input with action added.

add-double-pause clj

(add-double-pause input & [duration])

Return input source with two pause actions added.

Optionally specify a duration, defaults to 0.

add-key-down clj

(add-key-down input key)

Return input source with key down action added.

add-key-press clj

(add-key-press input key)

Return input source with key down and up actions added.

add-key-up clj

(add-key-up input key)

Return input source with key up action added.

add-pause clj

(add-pause input & [duration])

Return input source with a pause action added.

Optionally specify a duration, defaults to 0.

add-pointer-cancel clj

(add-pointer-cancel input)

Return input with a pointer cancel action added.

add-pointer-click clj

(add-pointer-click input & [pointer-button])

Return input source with pointer-button down and up actions added.

pointer-button defaults to etaoin.keys/mouse-left

add-pointer-click-el clj

(add-pointer-click-el input el & [pointer-button])

Return input source with pointer-button down and up actions on element el added.

pointer-button defaults to etaoin.keys/mouse-left

add-pointer-double-click clj

(add-pointer-double-click input & [pointer-button])

Return input source with pointer-button down, up, down, up actions added.

pointer-button defaults to etaoin.keys/mouse-left

add-pointer-double-click-el clj

(add-pointer-double-click-el input el & [pointer-button])

Return input source with pointer-button down, up, down, up actions on element el added.

pointer-button defaults to etaoin.keys/mouse-left

add-pointer-down clj

(add-pointer-down input & [pointer-button])

Return input source with pointer-button down action added.

button defaults to etaoin.keys/mouse-left

add-pointer-move clj

(add-pointer-move input & [{:keys [x y origin duration]}])

Return input source with pointer move action added.

Moves the pointer from origin to offset x y with optional duration in milliseconds.

Possible origin values are:

• "viewport" move to x y offset in viewport. This is the default.
• "pointer" x y are interpreted as offsets from the current pointer location.
• a map that represents a web element for example via el->ref:

  (el->ref (query driver q))
  

  where q is query to find the element.

Optionally specify :duration in milliseconds, defaults to 250.

add-pointer-move-to-el clj

(add-pointer-move-to-el input el & [{:keys [duration]}])

Return input source with pointer move to element el action added.

Optionally specify :duration in milliseconds, defaults to 250.

add-pointer-up clj

(add-pointer-up input & [pointer-button])

Return input source with pointer-button up action added.

button defaults to etaoin.keys/mouse-left

add-script clj

(add-script driver url)

Have driver add script with src url to page.

back clj

(back driver)

Have driver navigate backward in the browser history.

boot-driver clj

(boot-driver type)

(boot-driver type {:keys [host webdriver-url] :as opts})

Launch and return a driver of type (e.g. :chrome, :firefox :safari :edge :phantom) with opts options.

• creates a driver
• launches a WebDriver process (or connects to an existing running process if :host or :webdriver-url is specified)
• creates a session for driver

Defaults taken from defaults-global then defaults for type: :port - if :host not specified, port is randomly generated for local WebDriver process :capabilities - are deep merged as part of connect logic.

opts map is optionally, see Driver Options.

child clj

(child driver ancestor-el q)

Uses driver to return single element satisfying query q under given ancestor-el element.

See query for details on q.

children clj

(children driver ancestor-el q)

Use driver to return a vector of unique elements satisfying query q under given ancestor-el element.

See query for details on q.

chrome clj

(chrome)

(chrome opts)

Launch and return a Chrome driver.

opts map is optionally, see Driver Options.

chrome-headless clj

(chrome-headless)

(chrome-headless opt)

Launch and return a headless Chrome driver.

opts map is optionally, see Driver Options.

chrome? clj

(chrome? driver)

Returns true if a driver is Chrome.

clear clj

(clear driver q & more-qs)

Have driver clear input element found by q (and optionally more-qs).

See query for details on q.

clear-el clj

(clear-el driver el)

Have driver clear input element el

click clj

(click driver q)

Have driver click on element found by query q.

See query for details on q.

click-el clj

(click-el driver el)

Have driver click on element el.

click-multi clj

(click-multi driver qs & [pause])

Have driver click on first element found by each query in vector qs.

• qs a vector of queries [query1 query2 query3 ...]
• pause a pause prior to each click in seconds, default is 0.

See query for details on qs.

click-single clj

(click-single driver q)

Have driver click on element found by query q. If q returns more than one element, throws.

See query for details on q.

click-visible clj

(click-visible driver q & [opts])

Waits until driver finds visible element via query q then clicks on it.

• opts: see wait-predicate opts.

close-window clj multimethod

(close-window driver)

Have driver close current browser window.

create-session clj

(create-session driver & [capabilities])

Have driver create a new session and return resulting session-id string.

Opens a browser window as a side-effect (visible if not running headless). Further requests to this driver will be for this session. Etaoin assumes one active session per driver.

defaults clj

WebDriver driver type specific option defaults. Note that for locally launched WebDriver processes the default port is a random free port.

defaults-global clj

WebDriver global option defaults

delete-cookie clj

(delete-cookie driver cookie-name)

Have driver delete cookie with cookie cookie-name.

delete-cookies clj multimethod

(delete-cookies driver)

Have driver delete all browser cookies for all domains.

delete-session clj

(delete-session driver)

Have driver delete the active session. Closes the browser window.

See also: quit.

disabled? clj

(disabled? query q)

Opposite of enabled?

disconnect-driver clj

(disconnect-driver driver)

Returns new driver after disconnecting from a running WebDriver process.

Closes the current session that is stored in the driver if it still exists. Removes the session from driver.

dismiss-alert clj multimethod

(dismiss-alert driver)

Have driver cancel open alert dialog.

displayed-el? clj multimethod

(displayed-el? driver el)

Return true if driver finds el is displayed/visible.

See query for details on q.

Note: Safari webdriver has not implemented displayed, for it we currently default to some naive CSS display/visibilty checks.

displayed? clj

(displayed? driver q)

Return true if element found by driver with query q is effectively displayed.

doto-wait clj macro

(doto-wait seconds obj & body)

The same as clojure.core/doto but prepends each form with (wait seconds) clause.

double-click clj

(double-click driver q)

Have driver double-click on element found by query q.

See query for details on q.

Note:

• the supported browsers are Chrome, and Phantom.js.
• for Firefox and Safari, your may try to simulate via click, wait, click sequence.

double-click-el clj multimethod

(double-click-el driver el)

Have driver double-click on element el.

Note:

• the supported browsers are Chrome, and Phantom.js.
• for Firefox and Safari, your may try to simulate it as a click, wait, click sequence.

drag-and-drop clj multimethod

(drag-and-drop driver q-from q-to)

Have driver perform a drag and drop from element found by q-from to element found by q-to:

1. moves mouse pointer to an element found with q-from query;
2. holds down the mouse button;
3. moves mouse to an element found with q-to query;
4. releases the mouse button.

See query for details on q-from, q-to.

Notes:

• does not work in Phantom.js since it does not have a virtual mouse API;
• does not work in Safari.

driver? clj

(driver? driver type)

Return true if driver is of type (e.g. on of: :chrome, :edge, :firefox, :safari, :phantom)

edge clj

(edge)

(edge opts)

Launch and return an Edge driver.

opts map is optionally, see Driver Options.

edge-headless clj

(edge-headless)

(edge-headless opts)

Launch and return a headless Edge driver.

opt map is optionally, see Driver Options.

edge? clj

(edge? driver)

Returns true if a driver is Edge.

el->ref clj

(el->ref el)

Return map representing an element reference for WebDriver.

The magic :element- constant in source is taken from the WebDriver Spec.

Passing the element reference map to js-execute automatically expands it into a DOM node. For example:

;; returns UUID string for the element
(def el (query driver :button-ok))

;; the first argument will the an Element instance.
(js-execute driver "arguments[0].scrollIntoView()", (el->ref el))

enabled-el? clj

(enabled-el? driver el)

Return true if driver determines element el is enabled.

For use on form elements.

enabled? clj

(enabled? driver q)

Returns true if driver determines element found by query q is enabled.

See query for details on q.

For use on form elements.

execute clj

(execute {:keys [driver method path data]})

Return response from having :driver execute HTTP :method request to :path with body :data.

Response body automatically converted from JSON to a clojure keywordized map. Any HTTP status failure code results in a throw.

• :method HTTP method, e.g. :get, :post, :delete, etc.
• :path a vector of strings/keywords representing a server's path. For example:
  • this: [:session "aaaa-bbbb-cccc" :element "dddd-eeee" :find]
  • becomes: "/session/aaaa-bbbb-cccc/element/dddd-eeee/find".
• :data optional body to send. Automatically converted to JSON.

This can be useful to call when you want to invoke some WebDriver implementation specific feature that Etaoin has not otherwise exposed.

For example, if Etaoin did not already have get-url:

(def driver (e/firefox))
(e/go driver "https://clojure.org")
(e/execute {:driver driver
            :method :get
            :path [:session (:session driver) :url]})
;; => {:value "https://clojure.org/"}

exists? clj

(exists? driver q & more)

Return true if driver can find element via query q.

See query for details on q.

Keep in mind this does not validate whether the found element is visible, clickable and so on.

fill clj

(fill driver q text & more)

Have driver fill input element found by q with text (and optionally more text).

See query for details on q.

Example:

(fill driver :simple-input "foo" "baz" 1)
;; fills the input with text: foobaz1

fill-active clj

(fill-active driver text & more)

Have driver fill active element with text (and optionally more text).

fill-el clj multimethod

(fill-el driver el text & more)

Have driver fill input element el with text (and optionally more text).

fill-human clj

(fill-human driver q text)

(fill-human driver q text opts)

Have driver fill element found by q with text as if it were a real human using opts.

See query for details on q.

opts

• :mistake-prob probability of making a typo (0 to 1.0) (default: 0.1)
• :pause-max maximum amount of time in seconds to pause between keystrokes (can be fractional) (default: 0.2)

fill-human-el clj

(fill-human-el driver el text opts)

Have driver fill element el with text as if it were a real human using opts.

opts

• :mistake-prob probability of making a typo (0 to 1.0) (default: 0.1)
• :pause-max maximum amount of time in seconds to pause between keystrokes (can be fractional) (default: 0.2)

fill-human-multi clj

(fill-human-multi driver q-text)

(fill-human-multi driver q-text opts)

Have driver fill multiple elements as if it were a real human being via q-text using opts.

q-text can be:

• a map of {q1 "text1" q2 "text2" ...}
• a vector of [q1 "text1" q2 "text2" ...]

See query for details on qs.

opts

• :mistake-prob probability of making a typo (0 to 1.0) (default: 0.1)
• :pause-max maximum amount of time in seconds to pause between keystrokes (can be fractional) (default: 0.2)

fill-multi clj

(fill-multi driver q-text)

Have driver fill multiple inputs via q-text.

q-text can be:

• a map of {q1 "text1" q2 "text2" ...}
• a vector of [q1 "text1" q2 "text2" ...]

See query for details on qs.

firefox clj

(firefox)

(firefox opts)

Launch and return a Firefox driver.

opts map is optionally, see Driver Options.

firefox-headless clj

(firefox-headless)

(firefox-headless opts)

Launch and return a headless Firefox driver.

opts map is optionally, see Driver Options.

firefox? clj

(firefox? driver)

Returns true if a driver is Firefox.

forward clj

(forward driver)

Have driver navigate forward in the browser's history.

get-alert-text clj multimethod

(get-alert-text driver)

Have driver return text string from alert dialog (if present).

get-cookie clj

(get-cookie driver cookie-name)

Have driver return first cookie matching cookie-name.

When cookie-name is a keyword it will be converted appropriately.

get-cookies clj

(get-cookies driver)

Have driver return a vector of current browser cookies.

Each cookie is a map with structure:

{:name "cookie1",
 :value "test1",
 :path "/",
 :domain "",
 :expiry nil,
 :secure false,
 :httpOnly false}

get-element-attr clj

(get-element-attr driver q attribute)

Have driver return value for attribute of element found by q.

Found attribute value is returned as string. When element is found but attribute is absent, returns nil.

See query for details on q.

Note: there is no special treatment of the class attribute. A single string with spaces is returned.

Example:

(def driver (firefox))
(get-element-attr driver {:tag :a} :class)
;; => "link link__external link__button"

get-element-attr-el clj

(get-element-attr-el driver el attribute)

Have driver return value for attribute of element el, or nil if attribute does not exist.

get-element-attrs clj

(get-element-attrs driver q & attributes)

Have driver return values for attributes of element found by query q.

Found attribute values are returned as strings. When element is found but attribute is absent, result is included in vector as nil.

See query for details on q.

get-element-box clj

(get-element-box driver q)

Have driver return map describing a bounding box for element found by query q.

See query for details on q.

The result is a map with the following keys:

• :x1: top left x coordinate;
• :y1: top left y coordinate;
• :x2: bottom right x coordinate;
• :y2: bottom right y coordinate;
• :width: width as a difference b/w :x2 and :x1;
• :height: height as a difference b/w :y2 and :y1.

get-element-css clj

(get-element-css driver q property)

Have driver return the CSS style property of element found by query q.

property is a string/keyword representing a CSS name. Examples: :font or "background-color"

The property will be returned if it was defined for the element itself or inherited.

Found property value is returned as string. When element is found but property is absent, returns nil.

See query for details on q.

Note: colors, fonts and some other properties may be represented differently for different browsers.

Example:

(def driver (firefox))
(e/go driver "https://clojars.org")
(get-element-css driver {:id :content} :background-color)
;; => "rgb(226, 228, 227)"

get-element-css-el clj

(get-element-css-el driver el property)

Have driver return value for CSS style property of element el, or nil if property does not exist.

get-element-csss clj

(get-element-csss driver q & properties)

Have driver return CSS style properties matching properties of element found by query q.

See query for details on q.

Found property values are returned as strings. When element is found but property is absent, result is included in vector as nil.

Note: colors, fonts and some other properties may be represented differently for different browsers.

Example:

(def driver (firefox))
(e/go driver "https://clojars.org")
(e/get-element-csss driver {:tag :body} :background-color :typo :line-height :font-size)
;; => ["rgb(226, 228, 227)" nil "20px" "14px"]

get-element-inner-html clj

(get-element-inner-html driver q)

Have driver return inner text of element found by query q.

See query for details on q.

For element with my-id in <div id="my-id"><p class="foo">hello</p></div> return will be "<p class="foo">hello</p>".

get-element-inner-html-el clj multimethod

(get-element-inner-html-el driver el)

Have driver return inner text of element el.

For element with my-id in <div id="my-id"><p class="foo">hello</p></div> return will be "<p class="foo">hello</p>".

get-element-location clj

(get-element-location driver q)

Have driver return map of :x :y offset, in pixels of element found by query q.

See query for details on q.

get-element-location-el clj multimethod

(get-element-location-el driver el)

Have driver return map of :x :y offset, in pixels of element el.

get-element-properties clj

(get-element-properties driver q & properties)

Have driver return a vector of property values matching properties of element found by query q.

Found property values are returned as strings. When element is found but property is absent, result is included in vector as nil.

See query for details on q.

get-element-property clj

(get-element-property driver q property)

Have driver value for property of element found by query q.

Found property value is returned as string. When element is found but property is absent, returns nil.

See query for details on q.

get-element-property-el clj

(get-element-property-el driver el property)

Have driver return value for property of element el.

get-element-size clj

(get-element-size driver q)

Have driver return map of :width and :height, in pixels, of element found by query q.

See query for details on q.

get-element-size-el clj multimethod

(get-element-size-el driver el)

Have driver return map of :width and :height, in pixels, of element el.

get-element-tag clj

(get-element-tag driver q)

Have driver return tag name of element found by query q.

See query for details on q.

get-element-tag-el clj

(get-element-tag-el driver el)

Have driver return tag name of element el.

get-element-text clj

(get-element-text driver q)

Have driver return inner text of element found by query q.

See query for details on q.

Text return for <p class="foo">hello</p> is "hello".

get-element-text-el clj

(get-element-text-el driver el)

Have driver return text of element el.

Text return for <p class="foo">hello</p> is "hello".

get-element-value clj multimethod

(get-element-value driver q)

Have driver return the value of element found by query q.

To be used on input elements.

See query for details on q.

get-element-value-el clj

(get-element-value-el driver el)

Have driver return the value of element el.

To be used on input elements.

get-hash clj

(get-hash driver)

Have driver fetch the current hash fragment for the current page (nil when not set).

Example:

(def driver (chrome))
(go driver "https://en.wikipedia.org/wiki/Clojure")
(get-hash driver)
;; => nil
(go driver "https://en.wikipedia.org/wiki/Clojure#Popularity")
(get-hash driver)
;; => "Popularity"

See also: set-hash.

get-implicit-timeout clj

(get-implicit-timeout driver)

Returns driver timeout in seconds to find elements on the page.

get-log-types clj multimethod

(get-log-types driver)

Have driver return a vector of log types the browser supports.

get-logs clj

(get-logs driver)

(get-logs driver logtype)

Have driver return Javascript console log entries.

Each log entry is a map with the following structure:

{:level :warning,
 :message "1,2,3,4  anonymous (:1)",
 :timestamp 1511449388366,
 :source nil,
 :datetime #inst "2017-11-23T15:03:08.366-00:00"}

Empirical knowledge about browser differences:

• Chrome:

  • Returns all recorded logs.
  • Clears the logs once they have been read.
  • JS console logs have :console-api for :source field.
  • Entries about errors will have SEVERE level.

• PhantomJS (obsolete and no longer tested):

  • Return all recorded logs since the last URL change.
  • Does not clear recorded logs on subsequent invocations.
  • JS console logs have nil for :source field.
  • Entries about errors will have WARNING level, as coded here.

get-page-load-timeout clj

(get-page-load-timeout driver)

Returns driver timeout in seconds for loading a page.

get-script-timeout clj

(get-script-timeout driver)

Returns driver timeout in seconds for executing JavaScript.

get-scroll clj

(get-scroll driver)

Have driver return the current scroll position as a map of :x :y.

get-source clj

(get-source driver)

Have driver return browser's current page HTML markup as a string.

get-status clj

(get-status driver)

Returns driver status.

Can indicate readiness to create a new session.

The return varies for different driver implementations.

get-title clj

(get-title driver)

Have driver return the current page title.

get-url clj

(get-url driver)

Have driver return the current url location as a string.

get-user-agent clj

(get-user-agent driver)

Have driver return the browser User-Agent

get-window-handle clj multimethod

(get-window-handle driver)

Have driver return the current browser window handle string.

get-window-handles clj multimethod

(get-window-handles driver)

Have driver return a vector of all browser window handle strings.

get-window-position clj multimethod

(get-window-position driver)

Have driver return the current window position, in pixels relative to the screen, as a map of :x and :y.

get-window-size clj multimethod

(get-window-size driver)

Have driver return the current browser window size in pixels as a map of :width and :height.

go clj

(go driver url)

Have driver open url in the current browser window.

Example:

(def ff (firefox))
(go ff "http://google.com")

has-alert? clj

(has-alert? driver)

Returns true if driver sees an open alert dialog.

has-class-el? clj

(has-class-el? driver el class)

Returns true if driver finds that element el includes class in its class attribute.

has-class? clj

(has-class? driver q class)

Returns true if driver finds that element found by query q includes class in its class attribute.

See query for details on q.

has-no-alert? clj

(has-no-alert? driver)

Opposite of has-alert?.

has-no-class? clj

(has-no-class? query q class)

Opposite of has-class?.

has-text? clj

(has-text? driver text)

(has-text? driver q text)

Return true if driver finds that text appears anywhere on a page.

When q is specified, restricts search inside the element that matches query q. See query for details on q.

headless? clj

(headless? driver)

Returns true if a driver is in headless mode (without UI window).

intersects? clj

(intersects? driver q1 q2)

Return true if bounding boxes found by driver for element found by query q1 intersects element found by query q2.

Compares bounding boxes of found elements.

invisible? clj

(invisible? driver q)

Oppsite of visible?.

js-async clj multimethod

(js-async driver script & args)

Return result of driver executing JavaScript script with args asynchornously in the browser.

Executes an asynchronous script in the browser and returns the result. An asynchronous script one that typically performs some kind of IO operation, like an AJAX request to the server. You cannot just use the return statement like you do in synchronous scripts.

The driver passes a special handler as the last argument that should be called to return the final result.

Note: calling this function requires the script timeout to be set properly, meaning non-zero positive value. See get-script-timeout, set-script-timeout and with-script-timeout.

• args: additional arguments for your code. Automatically converted to JSON.

Example of a script:

// the `arguments` would be an array of something like:
// [1, 2, true, ..., <special callback added by driver>]

var callback = arguments[arguments.length-1];

// so the main script would look like:
$.ajax({url: '/some/url', success: function(result) {
  if (isResultOk(result)) {
    callback({ok: getProgressData(result)});
  }
  else {
    callback({error: getErrorData(result)});
  }
}});

js-execute clj multimethod

(js-execute driver script & args)

Return result of driver executing Javascript script with args synchronously in the browser.

The script is sent as a string (can be multi-line). Under the hood, the browser wraps your code into a function, so avoid using the function clause at the top level.

Don't forget to add return <something> operator if you are interested in a resulting value.

You may access arguments through the built-in arguments pseudo-array from your code. You may pass any data structures that are JSON-compatible (scalars, maps, vectors).

The result value is also returned trough JSON encode/decode pipeline (JS objects turn to Clojure maps, arrays into vectors and so on).

• args: additional arguments for your script. Automatically converted to JSON.

Example:

(def driver (chrome))
(js-execute driver "return arguments[0] + 1;" 42)
;; => 43

js-localstorage-clear clj

(js-localstorage-clear driver)

Have driver clear local storage.

left-click clj

(left-click driver)

Have driver click the left mouse button at current mouse pointer position.

left-click-on clj

(left-click-on driver q)

Have driver move mouse pointer to element found by q then click left mouse button.

See query for details on q.

make-action-input clj

(make-action-input type)

Return a new action input source of type.

make-key-input clj

(make-key-input)

Return a new key input source.

make-mouse-input clj

(make-mouse-input)

Return a new mouse input source.

make-pen-input clj

(make-pen-input)

Return a new pen input source.

make-pointer-input clj

(make-pointer-input type)

Return a new pointer input source of pointer type.

make-touch-input clj

(make-touch-input)

Return a new touch input source.

maximize clj multimethod

(maximize driver)

Have driver make the current browser window as large as your screen allows.

middle-click clj

(middle-click driver)

Have driver click the middle mouse button at current mouse pointer position.

middle-click-on clj

(middle-click-on driver q)

Have driver move mouse pointer to element found by q then click middle mouse button.

See query for details on q.

Useful for opening links in a new tab.

mouse-btn-down clj multimethod

(mouse-btn-down driver)

Have driver press down on the button of the virtual mouse.

mouse-btn-up clj multimethod

(mouse-btn-up driver)

Have driver release button of the virtual mouse.

mouse-click clj multimethod

(mouse-click driver mouse-button)

Have driver click mouse-button at current mouse pointer position.

mouse-button should be etaoin.keys/mouse-left,etaoin.keys/mouse-middle or etaoin.keys/mouse-right.

mouse-click-on clj

(mouse-click-on driver btn q)

Have driver move mouse pointer to element found by q then click mouse-button.

• mouse-button should be etaoin.keys/mouse-left,etaoin.keys/mouse-middle or etaoin.keys/mouse-right.
• q see query for details.

mouse-move-to clj multimethod

(mouse-move-to driver q)

(mouse-move-to driver x y)

Have driver moves the virtual mouse pointer either to an element found by query q or to a specific by x and y pixel offset within the browser window.

perform-actions clj multimethod

(perform-actions driver input & inputs)

Have driver perform actions defined in input source(s) simultaneously.

See Actions for more details.

phantom clj

(phantom)

(phantom opts)

Launch and return a Phantom.js driver.

opts map is optionally, see Driver Options.

phantom? clj

(phantom? driver)

Returns true if a driver is Phantom.js.

print-page clj multimethod

(print-page driver file)

(print-page driver file opts)

Have driver print current HTML page to file in PDF format.

file can be either a string or java.io.File, any missing parent directories are automatically created.

opts map is optional:

• :orientation is :landscape or :portrait (default)
• :scale a number, defaults to 1, min of 0.1, max of 2
• :background defaults to false
• :page (default is North American Letter size 8.5x11 inches)
  • :width in cm, defaults to 21.59
  • :height in cm, defaults to 27.94
• :margin
  • :top in cm, defaults to1
  • :bottom in cm, defaults to 1
  • :left in cm, defaults to 1
  • :right in cm, default to 1
• :shrinkToFit defaults to true
• :pageRanges a vector, 1-based pages to include, example ["1-3" "6"] or [] for all (default)

At the time of this writing current WebDriver support:

• chrome, works in headless mode only, supports all opts
• edge, works in headless only, supports all opts
• firefox, might not support all opts
• safari, feature is not implemented

query clj

(query driver q)

(query driver q & more)

Use driver to find and return the first element on current page matching q.

Query q can be:

• :active the current active element
• a keyword to find element by it's ID attribute:
  • :my-id
  • (use {:id "my-id"} for ids that cannot be represented as keywords)
• an XPath expression:
  • ".//input[@id='uname']"
• a map with either :xpath or :css:
  • {:xpath ".//input[@id='uname']"}`
  • {:css "input#uname[name='username']"}
• any other map is converted to an XPath expression:
  • {:tag :div}
  • is equivalent to XPath: ".//div"
• multiple of the above (wrapped in a vector or not). The result of each expression is fed into the next.
  • {:tag :div} ".//input[@id='uname']"
  • [{:tag :div} ".//input[@id='uname']"]

Returns the found element's unique identifier, or throws when not found.

See Selecting Elements for more details.

query-all clj

(query-all driver q)

(query-all driver q & more)

Use driver to return a vector of all elements on current page matching q.

See query for details on q.

query-tree clj

(query-tree driver q & qs)

Use driver to return a collection of all elements matching piped queries.

The results of q are queried by qs1 which in turn are queried by qs2, and so on.

See query for details on q.

See User Guide for an example.

quit clj

(quit driver)

Have driver close the current session, then, if Etaoin launched it, kill the WebDriver process.

rand-uuid clj

(rand-uuid)

Return a random UUID string.

refresh clj

(refresh driver)

Have driver reload the content in the current browser window.

release-actions clj multimethod

(release-actions driver)

Have driver clear any active action state. This includes any key presses and/or a pointer button being held down.

reload clj

(reload driver)

Alias for refresh

remote-file clj

(remote-file remote-file-path)

Wraps remote-file-path for use with upload-file to avoid local file existence check.

Example usage:

(upload-file (remote-file "C:/Users/hello/url.txt"))

right-click clj

(right-click driver)

Have driver click the right mouse button at current mouse pointer position.

right-click-on clj

(right-click-on driver q)

Have driver move mouse pointer to element found by q then click right mouse button.

See query for details on q.

running? clj

(running? driver)

Return true if driver seems accessable via its :host and :port.

Throws

• if using :webdriver-url
• if driver process is found not be running

safari clj

(safari)

(safari opts)

Launch and return a Safari driver.

opts map is optionally, see Driver Options.

safari? clj

(safari? driver)

Returns true if a driver is Safari.

screenshot clj multimethod

(screenshot driver file)

Have driver save a PNG format screenshot of the current page to file. Throws if screenshot is empty.

file can be either a string or java.io.File, any missing parent directories are automatically created.

screenshot-element clj multimethod

(screenshot-element driver q file)

Have driver save a PNG format screenshot of the element found by query q to file.

See query for details on q.

file can be either a string or java.io.File, any missing parent directories are automatically created.

scroll clj

(scroll driver {:keys [x y]})

(scroll driver x y)

Have driver scroll page to x y absolute pixel coordinates.

scroll-bottom clj

(scroll-bottom driver)

Have driver scroll vertically to bottom of the page keeping current horizontal position.

scroll-by clj

(scroll-by driver {:keys [x y]})

(scroll-by driver x y)

Have driver scroll by x y relative pixel offset.

scroll-down clj

(scroll-down driver)

(scroll-down driver offset)

Have driver scroll the page down by offset pixels.

offset defaults to scroll-offset.

scroll-left clj

(scroll-left driver)

(scroll-left driver offset)

Have driver scroll the page left by offset pixels.

offset defaults to scroll-offset.

scroll-offset clj

Default scroll offset in pixels.

scroll-query clj

(scroll-query driver q)

(scroll-query driver q param)

Have driver scroll to the element found by query q.

See query for details on q.

Invokes element's .scrollIntoView() method. Accepts extra param argument that might be either boolean or object for more control. See Mozilla's docs for values.

scroll-right clj

(scroll-right driver)

(scroll-right driver offset)

Have driver scroll the page right by offset pixels.

offset defaults to scroll-offset.

scroll-top clj

(scroll-top driver)

Have driver scroll vertically to the top of the page keeping current horizontal position.

scroll-up clj

(scroll-up driver)

(scroll-up driver offset)

Have driver scroll the page up by offset pixels.

offset defaults to scroll-offset.

select clj

(select driver q text)

Have driver select option with matching text for select element found by query q. The select element is clicked, then the option.

See query for details on q.

selected-el? clj

(selected-el? driver el)

Return true if driver determines element el is selected.

For use on input elements like checkboxes, radio buttons and option elements.

selected? clj

(selected? driver q)

Return true if driver determines element found by query q is selected.

See query for details on q.

For use on input elements like checkboxes, radio buttons and option elements.

set-cookie clj

(set-cookie driver cookie)

Have driver set a cookie.

cookie is a map with structure described in get-cookies. At least :name and :value keys should be populated.

set-hash clj

(set-hash driver hash)

Have driver set a new hash fragment for the current page.

Don't include the leading # character in hash.

Useful when navigating on single page applications. See also: get-hash.

set-implicit-timeout clj multimethod

(set-implicit-timeout driver seconds)

Sets driver timeout seconds to find elements on the page.

set-page-load-timeout clj multimethod

(set-page-load-timeout driver seconds)

Sets driver timeout seconds for loading a page.

set-script-timeout clj multimethod

(set-script-timeout driver seconds)

Sets driver timeout seconds for executing JavaScript.

set-window-position clj

(set-window-position driver {:keys [x y]})

(set-window-position driver x y)

Have driver set the x y position of the current browser window.

Position is in pixels and relative to your screen. Absolute precision is not guaranteed.

set-window-size clj

(set-window-size driver {:keys [width height]})

(set-window-size driver width height)

Have driver set the width and height in pixels of the current window. Absolute precision is not guaranteed.

stop-driver clj

(stop-driver driver)

Returns new driver after killing its WebDriver process.

submit clj

(submit driver q)

Have driver submit a form by sending the enter key to input element found by query q.

See query for details on q.

supports-logs? clj

(supports-logs? driver)

Returns true if driver supports getting console logs.

switch-frame clj

(switch-frame driver q)

Have driver switch context to (i)frame element found by query q.

See query for details on q.

switch-frame-first clj

(switch-frame-first driver)

Have driver switch context to the first (i)frame.

switch-frame-parent clj

(switch-frame-parent driver)

Have driver switch context to the parent of the current (i)frame.

switch-frame-top clj

(switch-frame-top driver)

Have driver switch context the main page.

switch-window clj multimethod

(switch-window driver handle)

Have driver switch to browser window with handle.

switch-window-next clj

(switch-window-next driver)

Have driver switch to next browser window.

touch-down clj multimethod

(touch-down driver q)

(touch-down driver x y)

Have driver touch down

• on element found by query q
• or x y coordinate

See query for details on q.

touch-move clj multimethod

(touch-move driver q)

(touch-move driver x y)

Have driver touch move

• on element found by query q
• or x y coordinate

See query for details on q.

touch-tap clj multimethod

(touch-tap driver q)

Have driver touch tap element found by query q.

See query for details on q.

touch-up clj multimethod

(touch-up driver q)

(touch-up driver x y)

Have driver touch up

• on element found by query q
• or x y coordinate

See query for details on q.

upload-file clj multimethod

(upload-file driver q path)

Have driver attach a file path to a file input field element found by query q.

Arguments:

• q see query for details;
• file
  • when a string or java.io.File object, the file must exist locally.
  • when remote-file file is assumed to exist remotely and no local existence check is performed.

Under the hood, we send the file's name as a sequence of keys to the input.

use-css clj

(use-css driver)

Return new driver with default locator set to CSS.

use-xpath clj

(use-xpath driver)

Return new driver with default locator set to XPath.

visible? clj

(visible? driver q)

Return true if element found by driver with query q exists and is effectively displayed.

See query for details on q.

Same as displayed? but does not throw if element does not exist.

wait clj

(wait seconds)

(wait driver seconds)

Sleep for seconds.

wait-absent clj

(wait-absent driver q & [opts])

Waits until driver determines element is not found by q (is absent?).

See query for details on q.

• opts: see wait-predicate opts.

wait-disabled clj

(wait-disabled driver q & [opts])

Waits until driver determines element found by q is disabled?.

See query for details on q.

• opts: see wait-predicate opts.

wait-enabled clj

(wait-enabled driver q & [opts])

Waits until driver determines element found by q is enabled?.

See query for details on q.

• opts: see wait-predicate opts.

wait-exists clj

(wait-exists driver q & [opts])

Waits until driver finds element exists? via q.

• opts: see wait-predicate opts.

wait-has-alert clj

(wait-has-alert driver & [opts])

Waits until driver finds page has-alert?.

• opts: see wait-predicate opts.

wait-has-class clj

(wait-has-class driver q class & [opts])

Waits until driver finds element via q has-class? class.

See query for details on q.

• opts: see wait-predicate opts.

wait-has-text clj

(wait-has-text driver q text & [opts])

Waits until driver finds element via q with text anywhere inside it (including inner HTML).

See query for details on q.

• opts: see wait-predicate opts.

wait-has-text-everywhere clj

(wait-has-text-everywhere driver text & [opts])

Waits until driver finds text anywhere on the current page.

• opts: see wait-predicate opts.

wait-invisible clj

(wait-invisible driver q & [opts])

Waits until driver determines element found by q is invisible?.

See query for details on q.

• opts: see wait-predicate opts.

wait-predicate clj

(wait-predicate pred)

(wait-predicate pred opts)

Wakes up every :interval seconds to call pred. Keeps this up until either pred returns true or :timeout has elapsed. When :timeout has elapsed a slingshot exception is throws with :message.

Arguments:

• pred: a zero-argument predicate to call
• opts: a map of optional parameters:
  • :timeout wait limit in seconds, *wait-timeout* by default;
  • :interval how long to wait between calls, *wait-interval* by default;
  • :message a message that becomes a part of exception when timeout is reached.

wait-running clj

(wait-running driver & [opts])

Waits until driver is reachable via its host and port via running?.

Throws

• if using :webdriver-url.

• if driver process is found to be no longer running while waiting

• opts: see wait-predicate opts.

wait-visible clj

(wait-visible driver q & [opts])

Waits until driver determines element found by q is visible?.

See query for details on q.

• opts: see wait-predicate opts.

when-chrome clj macro

(when-chrome driver & body)

Executes body when browser driver is Chrome.

when-edge clj macro

(when-edge driver & body)

Executes body when browser driver is Edge.

when-firefox clj macro

(when-firefox driver & body)

Executes body when browser driver is Firefox.

when-headless clj macro

(when-headless driver & body)

Executes body when the driver is in headless mode.

when-not-chrome clj macro

(when-not-chrome driver & body)

Executes body when browser driver is NOT Chrome.

when-not-drivers clj macro

(when-not-drivers browsers driver & body)

Executes body when browser driver is NOT in browsers, ex: #{:chrome :safari}

when-not-edge clj macro

(when-not-edge driver & body)

Executes body when browser driver is NOT Edge.

when-not-firefox clj macro

(when-not-firefox driver & body)

Executes body when browser driver is NOT Firefox.

when-not-headless clj macro

(when-not-headless driver & body)

Executes body when browser driver is NOT in headless mode.

when-not-phantom clj macro

(when-not-phantom driver & body)

Executes body when browser driver is NOT Phantom.js.

when-not-predicate clj macro

(when-not-predicate predicate & body)

Executes body when predicate returns falsy.

when-not-safari clj macro

(when-not-safari driver & body)

Executes body when browser driver is NOT Safari.

when-phantom clj macro

(when-phantom driver & body)

Executes body when browser driver is Phantom.js.

when-predicate clj macro

(when-predicate predicate & body)

Executes body when predicate returns truthy.

when-safari clj macro

(when-safari driver & body)

Executes body when browser driver is Safari.

with-chrome clj macro

(with-chrome opts? bind & body)

Executes body with a Chrome driver session bound to bind.

Driver is automatically launched and terminated (even if an exception occurs).

opts map can be omitted, see Driver Options.

Example:

(with-chrome driver
  (go driver "https://clojure.org"))

with-chrome-headless clj macro

(with-chrome-headless opts? bind & body)

Executes body with a headless Chrome driver session bound to bind.

Driver is automatically launched and terminated (even if an exception occurs).

opts map can be omitted, see Driver Options.

Example:

(with-chrome-headless driver
  (go driver "https://clojure.org"))

with-css clj macro

(with-css driver & body)

Execute body with default locator set to CSS.

with-driver clj macro

(with-driver type opts? bind & body)

Executes body with a driver session of type (e.g. :chrome, :firefox :safari :edge :phantom) with opts options, binding driver instance to bind.

Driver is automatically launched and terminated (even if an exception occurs).

opts map can be omitted, see Driver Options.

Example:

(with-driver :firefox driver
  (go driver "https://clojure.org"))

with-edge clj macro

(with-edge opts? bind & body)

Executes body with an Edge driver session bound to bind.

Driver is automatically launched and terminated (even if an exception occurs).

opts map can be omitted, see Driver Options.

Example:

(with-edge driver
  (go driver "https://clojure.org"))

with-edge-headless clj macro

(with-edge-headless opts? bind & body)

Executes body with a headless Edge driver session bound to bind.

Driver is automatically launched and terminated (even if an exception occurs).

opts map can be omitted, see Driver Options.

Example:

(with-edge-headless driver
  (go driver "https://clojure.org"))

with-firefox clj macro

(with-firefox bind & body)

(with-firefox opts? bind & body)

Executes body with a Firefox driver session bound to bind.

Driver is automatically launched and terminated (even if an exception occurs).

opts map can be omitted, see Driver Options.

Example:

(with-firefox driver
  (go driver "https://clojure.org"))

with-firefox-headless clj macro

(with-firefox-headless opts? bind & body)

Executes body with a headless Firefox driver session bound to bind.

Driver is automatically launched and terminated (even if an exception occurs).

opts map can be omitted, see Driver Options.

Example:

(with-firefox-headless driver
  (go driver "https://clojure.org"))

with-frame clj macro

(with-frame driver q & body)

Excecute body within context of frame found via driver by query q.

Frame context is restored after call. Result of body is returned.

with-http-error clj macro

(with-http-error & body)

Executes body suppressing catching any exception that would normally occur due to HTTP non-success status when communicating with a WebDriver.

Instead returns false on first HTTP non-success status.

with-key-down clj macro

(with-key-down input key & body)

Returns input source piped through key down, then presumably a body of more actions then a key up action.

with-mouse-btn clj macro

(with-mouse-btn driver & body)

Have driver press the virtual mouse button, execute body, then release the virtual mouse button.

with-phantom clj macro

(with-phantom opts? bind & body)

Executes body with an Phantom.JS driver session bound to bind.

Driver is automatically launched and terminated (even if an exception occurs).

opts map can be omitted, see Driver Options.

Example:

(with-phantom driver
  (go driver "https://clojure.org"))

with-pointer-btn-down clj macro

(with-pointer-btn-down input pointer-button & body)

Returns input source piped through pointer-button down action, then presumably a body of more actions then a pointer pointer-button up action.

pointer-button should be, for example, etaoin.keys/mouse-left

with-pointer-left-btn-down clj macro

(with-pointer-left-btn-down input & body)

Returns input source piped through pointer left button down action, then presumably a body of more actions then a pointer left button up action.

with-postmortem clj macro

(with-postmortem driver opts & body)

Executes body with postmortem handling. Good for forensics.

If an exception occurs, saves:

• screenshot .png to :dir-img else :dir else current working directory
• page source .html to :dir-scr else :dir else current working directory
• console log .json to :dir-log else :dir else current working directory

Dirs are automatically created if necessary.

:date-format used in filename to keep them unique. See Java SDK SimpleDateFormat for available patterns. Defaults to "yyyy-MM-dd-HH-mm-ss".

Tip: don't bother using with-postmortem in test fixtures. The standard clojure.testframework has its own way of handling exceptions, so wrapping a fixture with (with-postmortem...) would be in vain.

with-safari clj macro

(with-safari opts? bind & body)

Executes body with a Safari driver session bound to bind.

Driver is automatically launched and terminated (even if an exception occurs).

opts map can be omitted, see Driver Options.

Example:

(with-safari driver
  (go driver "https://clojure.org"))

with-screenshots clj macro

(with-screenshots driver dir & body)

Have driver save a PNG imge screenshot to dir after each form in body is executed.

Filenames will contain an epoch timestamp.

with-script-timeout clj macro

(with-script-timeout driver seconds & body)

Execute body temporarily setting driver to timeout seconds for executing JavaScript. Useful for asynchronous scripts.

with-wait clj macro

(with-wait seconds & body)

Execute body waiting seconds before each form.

Returns the value of the last form.

Can be used to perform actions slowly. Some SPA applications need extra time to re-render the content.

with-wait-interval clj macro

(with-wait-interval seconds & body)

Execute body with a *wait-interval* of seconds (which can be fractional).

with-wait-timeout clj macro

(with-wait-timeout seconds & body)

Execute body with a *wait-timeout* of seconds

with-xpath clj macro

(with-xpath driver & body)

Execute body with default locator set to XPath.