etaoin.api

The API below was written regarding to the source code
of different Webdriver implementations. All of them partially
differ from the official W3C specification.

The standard:
https://www.w3.org/TR/webdriver/

Chrome:
https://chromium.googlesource.com/chromium/src/+/master/chrome/test/chromedriver/

Firefox (Geckodriver):
https://github.com/mozilla/geckodriver
https://github.com/mozilla/webdriver-rust/

Phantom.js (Ghostdriver)
https://github.com/detro/ghostdriver/blob/

*wait-interval*

dynamic

*wait-timeout*

dynamic

absent?

Opposite of `exists?`.

accept-alert

multimethod

Simulates submitting an alert dialog (pressing OK button).

add-action

(add-action input action)

add-double-pause

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

add-key-down

(add-key-down input key)

add-key-press

(add-key-press input key)

add-key-up

(add-key-up input key)

add-pause

(add-pause input & [duration])

add-pointer-cancel

(add-pointer-cancel input)

add-pointer-click

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

add-pointer-click-el

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

add-pointer-double-click

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

add-pointer-double-click-el

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

add-pointer-down

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

add-pointer-move

(add-pointer-move input & [{:keys [x y origin duration]}])
Move the pointer from `origin` to `x` and `y` offsets
with `duration` in milliseconds.

Possible `origin` values are:

  - 'viewport'; the final x axis will be equal to `x` offset
  and the final y equal to `y` offset. This is the default
  value.

  - 'pointer'; the final x will be equal to start x of pointer + `x` offset
  and the final y equal to start y of pointer + `y` offset.

  - a map that represents a web element. To get it, pass the result
  of the `query` function into the `el->ref`, for example:

  (el->ref (query driver q))

  where `q` is a query term to find an element.

add-pointer-move-to-el

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

add-pointer-up

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

add-script

(add-script driver url)

back

(back driver)
Move backwards in a browser's history.

boot-driver

(boot-driver type)(boot-driver type {:keys [host], :as opt})
Three-in-one: creates a driver, starts a process and creates a new
session. Returns the driver instance.

Arguments:

- `type` a keyword determines a driver type.

- `opt` a map of all possible parameters that `-create-driver`,
`-run-driver` and `-connect-driver` may accept.

child

(child driver ancestor-el q)
Finds a single element under given root element.

children

(children driver ancestor-el q)
Finds multiple elements under given root element.

chrome

Launches Chrome driver. A shortcut for `boot-driver`.

chrome-headless

(chrome-headless)(chrome-headless opt)
Launches headless Chrome driver. A shortcut for `boot-driver`.

chrome?

(chrome? driver)
Returns true if a driver is a Chrome instance.

clear

(clear driver q & more)
Clears an element (input, textarea) found with a query.

0.1.6: multiple queries added.

clear-el

(clear-el driver el)
Clears an element by its identifier.

click

(click driver q)
Clicks on an element (a link, a button, etc).

click-el

(click-el driver el)
Click on an element having its system id.

click-multi

(click-multi driver qs & [pause])
Clicks on a multiple elements in batch.

`qs`  a vector of [query1 query2 query3 ...]
`pause` a pause between click in seconds, default is 0

click-single

(click-single driver q)
Click on an element checking that there is only one element found.
Throw an exception otherwise.

click-visible

(click-visible driver q & [opt])
Waits until an element becomes visible, then clicks on it.

Arguments:

- `driver`: a driver instance;
- `q`: a query term (see `query`);
- `opt`: a map of options (see `wait-predicate`).

close-window

multimethod

Closes the current browser window.

create-session

(create-session driver & [capabilities])
Initiates a new session for a driver. Opens a browser window as a
side-effect. All the further requests are made within specific
session. Some drivers may work with only one active session. Returns
a long string identifier.

default-duration

default-locator

default-origin

defaults

delete-cookies

multimethod

(delete-cookies driver)
Deletes all the cookies for all domains.

delete-session

(delete-session driver)
Deletes a session. Closes a browser window.

disabled?

disconnect-driver

(disconnect-driver driver)
Disconnects from a running Webdriver server.

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

dismiss-alert

multimethod

Simulates cancelling an alert dialog (pressing cross button).

dispatch-driver

(dispatch-driver driver & _)
Returns the current driver's type. Used as dispatcher in
multimethods.

displayed-el?

multimethod

Checks whether an element is displayed by its identifier.

Note: Safari does not have native `displayed` implementation, we
have to check some common cases manually (CSS display, visibility,
etc).

Returns true or false.

displayed?

(displayed? driver q)
Checks whether an element is displayed an screen.

doto-wait

macro

(doto-wait n obj & body)
The same as doto but prepends each form with (wait n) clause.

double-click

(double-click driver q)
Performs double click on an element.

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.

double-click-el

multimethod

drag-and-drop

multimethod

(drag-and-drop driver q-from q-to)
Performs drag and drop operation as a sequence of the following steps:

1. moves mouse pointer to an element found with `q-from` query;
2. puts down mouse button;
3. moves mouse to an element found with `q-to` query;
4. puts up mouse button.

Arguments:

- `driver`: a driver instance,

- `q-from`: from what element to start dragging; any expression that
`query` function may accept;

- `q-to`: to what element to drag, a seach term.

Notes:

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

- does not work in Safari.

driver?

(driver? driver type)

edge

Launches Edge driver. A shortcut for `boot-driver`.

edge-headless

(edge-headless)(edge-headless opt)
Launches headless Edge driver. A shortcut for `boot-driver`.

edge?

(edge? driver)
Returns true if a driver is an Edge  instance.

el->ref

(el->ref el)
Turns machinery-wise element ID into an object
that Javascript use to reference existing DOM element.

The magic constant below is taken from the standard:
https://www.w3.org/TR/webdriver/#elements

Passing such an object to `js-execute` automatically expands into a
DOM node. For example:

;; returns long UUID
(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?

(enabled-el? driver el)

enabled?

(enabled? driver q)
Checks whether an element is enabled.

execute

(execute {:keys [driver method path data result]})
Executes an HTTP request to a driver's server. Performs the body
within result data bound to the `result` clause.

Arguments:

- `driver`: a driver instance,

- `method`: a keyword represents HTTP method, e.g. `:get`, `:post`,
`:delete`, etc.

- `path`: a vector of strings/keywords represents a server's
path. For example:

`[:session "aaaa-bbbb-cccc" :element "dddd-eeee" :find]`

will turn into "/session/aaaa-bbbb-cccc/element/dddd-eeee/find".

- `data`: any data sctructure to be sent as JSON body. Put `nil` For
`GET` requests.

- `result`: a symbol to bind the data from the HTTP response with
`let` form before executing the body.

Example:

(def driver (firefox))
(println (execute {:driver driver
                   :method :get
                   :path [:session (:session driver) :element :active])))

exists?

(exists? driver q & more)
Returns true if an element exists on the page.

Keep in mind it does not validates whether the element is visible,
clickable and so on.

fill

(fill driver q text & more)
Fills an element found with a query with a given text.

0.1.6: now the rest parameters are supported. They will
joined using "str":

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

fill-active

(fill-active driver text & more)
Fills an active element with keys.

fill-el

multimethod

(fill-el driver el text & more)
Fills an element with text by its identifier.

fill-human

(fill-human driver q text)(fill-human driver q text opt)
Fills text like humans do: with error, corrections and pauses.

Arguments:

- `driver`: a driver instance,

- `q`: a query term, see `query` function for more info,

- `text`: a string to input.

fill-human-el

(fill-human-el driver el text opt)

fill-human-multi

(fill-human-multi driver q-text)(fill-human-multi driver q-text opt)
`fill-human` + `fill-multi`

fill-multi

(fill-multi driver q-text)
Fills multiple inputs in batch.

`q-text` could be:

- a map of {query -> text}
- a vector of [query1 text1 query2 text2 ...]

find-elements*

multimethod

firefox

Launches Firefox driver. A shortcut for `boot-driver`.

firefox-headless

(firefox-headless)(firefox-headless opt)
Launches headless Firefox driver. A shortcut for `boot-driver`.

firefox?

(firefox? driver)
Returns true if a driver is a Firefox instance.

format-date

(format-date date pattern)

forward

(forward driver)
Move forwards in a browser's history.

get-alert-text

multimethod

Returns a string of text that appears in alert dialog (if present).

get-cookies

(get-cookies driver)
Returns all the cookies browser keeps at the moment.

Each cookie is a map with structure:

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

get-element-attr

(get-element-attr driver q name)
Returns an HTTP attribute of an element (class, id, href, etc).

Arguments:

- `driver`: a driver instance,

- `q`: a query term to find an element,

- `name`: either a string or a keyword with a name of an attribute.

Returns: a string with the attribute value, `nil` if no such
attribute for that element.

Note: it does not split CSS classes! A single string with spaces is
returned.

Example:

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

get-element-attr-el

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

get-element-attrs

(get-element-attrs driver q & attrs)
Returns multiple attributes in batch. The result is a vector of
corresponding attributes.

get-element-box

(get-element-box driver q)
Returns a bounding box for an element found with a query term.

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

(get-element-css driver q prop)
Returns a CSS property of an element. The property might be both
own or inherited.

Arguments:

- `driver`: a driver instance,

- `q`: a query term,

- `name`: a string/keyword with a CSS name (:font, "background-color", etc).

Returns a string with a value, `nil` if there is no such property.

Note: colors, fonts and some other properties may be represented in
their own ways depending on a browser.

Example:

(def driver (firefox))
(get-element-css driver {:id :content} :background-color)
>> "rgb(204, 204, 204)" ;; or "rgba(204, 204, 204, 1)"

get-element-csss

(get-element-csss driver q & props)
Returns multiple CSS properties in batch. The result is a vector of
corresponding properties.

get-element-inner-html

(get-element-inner-html driver q)
Returns element's inner HTML.

For element `el` in `<div id="el"><p class="foo">hello</p></div>` it will
be "<p class="foo">hello</p>" string.

get-element-inner-html-el

multimethod

Returns element's inner text by its identifier.

get-element-location

(get-element-location driver q)
Returns an element location on a page as a map with :x and :x keys.

get-element-location-el

multimethod

get-element-properties

(get-element-properties driver q & props)
Returns multiple properties in batch. The result is a vector of
corresponding properties.

get-element-property

(get-element-property driver q name)
Returns a property of an element (value, etc).

Arguments:

- `driver`: a driver instance,

- `q`: a query term to find an element,

- `name`: either a string or a keyword with a name of a property.

Returns: a string with the attribute value, `nil` if no such
property for that element.

get-element-size

(get-element-size driver q)
Returns an element size as a map with :width and :height keys.

get-element-size-el

multimethod

get-element-tag

(get-element-tag driver q)
Returns element's tag name ("div", "input", etc).

get-element-tag-el

(get-element-tag-el driver el)
Returns element's tag name by its identifier.

get-element-text

(get-element-text driver q)
Returns inner element's text.

For `<p class="foo">hello</p>` it will be "hello" string.

get-element-text-el

(get-element-text-el driver el)
Returns element's inner text by its identifier.

get-element-value

multimethod

(get-element-value driver q)
Returns the current element's value (input text).

get-hash

(get-hash driver)
Returns the current hash fragment (nil when not set).

get-implicit-timeout

(get-implicit-timeout driver)
Returns the current implicit timeout in seconds.

get-log-types

multimethod

(get-log-types driver)
Returns a set of log types the browser supports.

get-logs

(get-logs driver)(get-logs driver logtype)

get-page-load-timeout

(get-page-load-timeout driver)
Returns the current page load timeout in seconds.

get-pwd

(get-pwd)

get-script-timeout

(get-script-timeout driver)
Returns the current script timeout in seconds.

get-scroll

(get-scroll driver)
Returns the current scroll position as a map
with `:x` and `:y` keys and integer values.

get-source

(get-source driver)
Returns browser's current HTML markup as a string.

get-status

(get-status driver)
Returns the current Webdriver status info. The content depends on
specific driver.

get-title

(get-title driver)
Returns the current window's title.

get-url

(get-url driver)
Returns the current URL string.

get-user-agent

(get-user-agent driver)

get-window-handle

multimethod

(get-window-handle driver)
Returns the current active window handler as a string.

get-window-handles

multimethod

(get-window-handles driver)
Returns a vector of all window handlers.

get-window-position

multimethod

(get-window-position driver)
Returns a window position relative to your screen as a map with
`:x` and `:y` keys.

get-window-size

multimethod

(get-window-size driver)
Returns a window size a map with `:width` and `:height` keys.

go

(go driver url)
Open the URL the current window.

Example:

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

has-alert?

(has-alert? driver)
Checks if there is an alert dialog opened on the page.

has-class-el?

(has-class-el? driver el class)

has-class?

(has-class? driver q class)
Checks whether an element has a specific class.

has-no-alert?

Opposite to `has-alert?`.

has-no-class?

Opposite to `has-class?`.

has-text?

(has-text? driver text)(has-text? driver q text)
Returns true if a passed text appears anywhere on a page.
With a leading query expression, finds a text inside the first
element that matches the query.

headless?

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

intersects?

(intersects? driver q1 q2)
Determines whether two elements intersects in geometry meaning.

The implementation compares bounding boxes for each element
analyzing their arrangement.

Arguments:

- `q1` and `q2` are query terms to find elements to check for
intersection.

Returns true or false.

invisible?

Oppsite to `visible?`.

join-path

(join-path p1 p2 & more)
Joins two and more path components into a single file path OS-wisely.

js-async

multimethod

(js-async driver script & args)
Executes an asynchronous script in the browser and returns the result.
An asynchronous script is a such one that performs any kind of IO operations,
say, AJAX request to the server. When running such kind of a script, you cannot
just use the `return` statement like you do in ordinary scripts. Instead, 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`, `get-script-timeout`
and `with-script-timeout` functions/macroses.

Example of a script:

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

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)});
  }
}});

Arguments:

- `driver`: a driver instance,

- `script`: a string with the code to execute.

- `args`: additional arguments for your code. Any data that might be
serialized into JSON.

js-execute

multimethod

(js-execute driver script & args)
Executes Javascript code in browser synchronously.

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

Don't forget to add `return <something>` operator if you are
interested in the result 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).

Arguments:

- `driver`: a driver instance,

- `script`: a string with the code to execute.

- `args`: additional arguments for your code. Any data that might be
serialized into JSON.

Example:

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

js-localstorage-clear

(js-localstorage-clear driver)

left-click

(left-click driver)
A shortcut for `mouse-click` with the left button.

left-click-on

(left-click-on driver q)
Left mouse click on an element. Probably don't need
that one, use `click` instead.

locator-css

locator-xpath

make-action-input

(make-action-input type)

make-key-input

(make-key-input)

make-mouse-input

(make-mouse-input)

make-pen-input

(make-pen-input)

make-pointer-input

(make-pointer-input type)

make-screenshot-file-path

(make-screenshot-file-path driver-type dir)

make-touch-input

(make-touch-input)

make-url

(make-url host port)
Makes an Webdriver URL from a host and port.

maximize

multimethod

(maximize driver)
Makes the browser window as wide as your screen allows.

middle-click

(middle-click driver)
A shortcut for `mouse-click` with the middle button.

middle-click-on

(middle-click-on driver q)
Move pointer to an element found with a query
and middle click on it. Useful for opening links
in a new tab.

mouse-btn-down

multimethod

(mouse-btn-down driver)
Puts down a button of a virtual mouse.

mouse-btn-up

multimethod

(mouse-btn-up driver)
Puts up a button of a virtual mouse.

mouse-click

multimethod

(mouse-click driver btn)
Click on a mouse button using the *current* mouse position.
The `btn` is a mouse button code. See `keys/mouse-*` constants.

mouse-click-on

(mouse-click-on driver btn q)
Mouse click on a specific element and a button.
Moves the mouse pointer to the element first.

mouse-move-to

multimethod

(mouse-move-to driver q)(mouse-move-to driver x y)
Moves a virtual mouse pointer either to an element
or by `x` and `y` offset.

perform-actions

multimethod

phantom

Launches Phantom.js driver. A shortcut for `boot-driver`.

phantom?

(phantom? driver)
Returns true if a driver is a Phantom.js instance.

postmortem-handler

(postmortem-handler driver {:keys [dir dir-src dir-img dir-log date-format]})
Internal postmortem handler that creates files.
See the `with-postmortem`'s docstring below for more info.

process-log

(process-log entry)
Remaps some of the log's fields.

proxy-env

(proxy-env proxy)

query

(query driver q)(query driver q & more)
Finds an element on a page.

A query might be:

- a string with an XPath expression;
- a keyword `:active` that means to get the current active element;
- any other keyword which stands for an element's ID attribute;
- a map with either `:xpath` or `:css` key with a string value
  of corresponding selector type (XPath or CSS);
- any other map that will be expanded into XPath term (see README.md);
- a vector of any expressions mentioned above. In that case, each next
  term is searched from the previous one.

Returns a element's unique identifier.

query-all

(query-all driver q)(query-all driver q & more)
Finds multiple elements on a page.
See `query` function for incoming params.
Returns a vector of element identifiers.

query-tree

(query-tree driver q & qs)
Takes selectors and acts like a tree.
Every next selector queries elements from the previous ones.
The fist selector relies on find-elements,
and the rest ones use find-elements-from

{:tag :div} {:tag :a}
means
{:tag :div} -> [div1 div2 div3]
div1 -> [a1 a2 a3]
div2 -> [a4 a5 a6]
div3 -> [a7 a8 a9]
so the result will be [a1 ... a9]

quit

(quit driver)
Closes the current session and stops the driver.

rand-uuid

(rand-uuid)

refresh

(refresh driver)
Reloads the current window.

release-actions

multimethod

reload

right-click

(right-click driver)
A shortcut for `mouse-click` with the right button.

right-click-on

(right-click-on driver q)
Move pointer to an element found with a query
and right click on it.

running?

(running? driver)
Check whether a driver runs HTTP server.

safari

Launches Safari driver. A shortcut for `boot-driver`.

safari?

(safari? driver)
Returns true if a driver is a Safari instance.

screenshot

multimethod

(screenshot driver file)
Takes a screenshot of the current page. Saves it in a *.png file on disk.
Rises exception if a screenshot was empty.

Arguments:

- `driver`: driver instance,

- `file`: either a path to a file or a native `java.io.File` instance.

screenshot-element

multimethod

(screenshot-element driver q file)

scroll

(scroll driver x y)(scroll driver {:keys [x y]})
Scrolls the window into absolute position (jumps to exact place).

scroll-bottom

(scroll-bottom driver)
Scrolls to bottom of the page keeping current horizontal position.

scroll-by

(scroll-by driver x y)(scroll-by driver {:keys [x y]})
Scrolls the window by offset (relatively the current position).

scroll-down

(scroll-down driver offset)(scroll-down driver)
Scrolls the page down by specific number of pixels.
The `scroll-offset` constant is used when not passed.

scroll-left

(scroll-left driver offset)(scroll-left driver)
Scrolls the page left by specific number of pixels.
The `scroll-offset` constant is used when not passed.

scroll-offset

Default scroll offset in pixels.

scroll-query

(scroll-query driver q)(scroll-query driver q param)
Scrolls to the first element found with a query.

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

See this page for details:
https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView

scroll-right

(scroll-right driver offset)(scroll-right driver)
Scrolls the page right by specific number of pixels.
The `scroll-offset` constant is used when not passed.

scroll-top

(scroll-top driver)
Scrolls to top of the page keeping current horizontal position.

scroll-up

(scroll-up driver offset)(scroll-up driver)
Scrolls the page up by specific number of pixels.
The `scroll-offset` constant is used when not passed.

select

(select driver q text)
Select element in select-box by visible text on click.

Arguments:

- `driver`: a driver instance,

- `q`: a query term, see `query` function for more info,

- `text`: a string, text in the option you want to select

selected-el?

(selected-el? driver el)

selected?

(selected? driver q)
Checks whether an element is selected.

set-hash

(set-hash driver hash)
Sets a new hash fragment for the current page.
Don't include the leading # symbol. Useful when navigating
on single page applications.

set-implicit-timeout

multimethod

(set-implicit-timeout driver sec)
Sets timeout that is used when finding elements on the page.

set-page-load-timeout

multimethod

(set-page-load-timeout driver sec)
Sets timeout for loading pages.

set-script-timeout

multimethod

(set-script-timeout driver sec)
Sets timeout for executing JS sctipts.

set-window-position

(set-window-position driver {:keys [x y]})(set-window-position driver x y)
Sets new position for a window. Absolute precision is not
guaranteed.

set-window-size

(set-window-size driver {:keys [width height]})(set-window-size driver width height)
Sets new size for a window. Absolute precision is not guaranteed.

stop-driver

(stop-driver driver)
Stops the driver's process. Removes proces's data from the driver
instance. Returns a modified driver.

submit

(submit driver q)
Sends Enter button value to an element found with query.

supports-logs?

(supports-logs? driver)
Checks whether a driver supports getting console logs.

switch-frame

(switch-frame driver q)
Switches to an (i)frame quering the page for it.

switch-frame*

(switch-frame* driver id)
Switches to an (i)frame by its index or an element reference.

switch-frame-first

(switch-frame-first driver)
Switches to the first (i)frame.

switch-frame-parent

(switch-frame-parent driver)
Switches to the parent of the current (i)frame.

switch-frame-top

(switch-frame-top driver)
Switches to the most top of the page.

switch-window

multimethod

(switch-window driver handle)
Switches a browser to another window.

switch-window-next

(switch-window-next driver)

touch-down

multimethod

touch-move

multimethod

touch-tap

multimethod

touch-up

multimethod

upload-file

multimethod

Attaches a local file to a file input field.

Arguments:

- `q` is a query term that refers to a file input;
- `file` is either a string or java.io.File object
that references a local file. The file should exist.

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

use-css

(use-css driver)

use-locator

(use-locator driver locator)

use-xpath

(use-xpath driver)

visible?

(visible? driver q)
Checks whether an element is visible on the page.

wait

(wait driver sec)(wait sec)
Sleeps for N seconds.

wait-absent

(wait-absent driver q & [opt])
Waits until an element is absent.

Arguments:

- `driver`: a driver instance;
- `q`: a query term (see `query`);
- `opt`: a map of options (see `wait-predicate`).

wait-disabled

(wait-disabled driver q & [opt])
Waits until an element is disabled (usually an input element).

Arguments:

- `driver`: a driver instance;
- `q`: a query term (see `query`);
- `opt`: a map of options (see `wait-predicate`).

wait-enabled

(wait-enabled driver q & [opt])
Waits until an element is enabled (usually an input element).

Arguments:

- `driver`: a driver instance;
- `q`: a query term (see `query`);
- `opt`: a map of options (see `wait-predicate`).

wait-exists

(wait-exists driver q & [opt])
Waits until an element exists on a page (but may not be visible though).

Arguments:

- `driver`: a driver instance;
- `q`: a query term (see `query`);
- `opt`: a map of options (see `wait-predicate`).

wait-has-alert

(wait-has-alert driver & [opt])
Waits until an alert dialog appears on the screen.

Arguments:

- `driver`: a driver instance;
- `opt`: a map of options (see `wait-predicate`).

wait-has-class

(wait-has-class driver q class & [opt])
Waits until an element has specific class.

Arguments:

- `driver`: a driver instance;
- `q`: a query term (see `query`);
- `class`: a class to search as string;
- `opt`: a map of options (see `wait-predicate`).

wait-has-text

(wait-has-text driver q text & [opt])
Waits until an element has text anywhere inside it (including inner HTML).

Arguments:

- `driver`: a driver instance;
- `q`: a query term (see `query`).
- `text`: a string to search;
- `opt`: a map of options (see `wait-predicate`).

wait-has-text-everywhere

(wait-has-text-everywhere driver text & [opt])
Like `wait-has-text` but searches for text across the entire page.

Arguments:

- `driver`: a driver instance;
- `text`: a string to search;
- `opt`: a map of options (see `wait-predicate`).

wait-invisible

(wait-invisible driver q & [opt])
Waits until an element presents but not visible.

Arguments:

- `driver`: a driver instance;
- `q`: a query term (see `query`);
- `opt`: a map of options (see `wait-predicate`).

wait-predicate

(wait-predicate pred)(wait-predicate pred opt)
Sleeps continuously calling a predicate until it returns true.
Raises a slingshot exception when timeout is reached.

Arguments:

- `pred`: a zero-argument predicate to call;
- `opt`: a map of optional parameters:
-- `:timeout` wait limit in seconds, 20 by default;
-- `:interval` how long to wait b/w calls, 0.33 by default;
-- `:message` a message that becomes a part of exception when timeout is reached.

wait-running

(wait-running driver & [opt])

wait-visible

(wait-visible driver q & [opt])
Waits until an element presents and is visible.

Arguments:

- `driver`: a driver instance;
- `q`: a query term (see `query`);
- `opt`: a map of options (see `wait-predicate`).

when-chrome

macro

(when-chrome driver & body)
Executes the body only if the driver is Chrome.

Example:

(def driver (chrome))
(when-chrome driver
  (println "It's Chrome!")

when-edge

macro

(when-edge driver & body)
Executes the body only if the driver is Edge.

when-firefox

macro

(when-firefox driver & body)
Executes the body only if the driver is Firefox.

when-headless

macro

(when-headless driver & body)
Executes the body only if the driver is run in headless mode.

when-not-chrome

macro

(when-not-chrome driver & body)
Executes the body only if a browser is NOT Chrome.

when-not-drivers

macro

(when-not-drivers browsers driver & body)
Executes the body only if a browsers is NOT in set #{:browser1 :browser2}

when-not-edge

macro

(when-not-edge driver & body)
Executes the body only if a browser is NOT Edge.

when-not-firefox

macro

(when-not-firefox driver & body)
Executes the body only if a browser is NOT Firefox.

when-not-headless

macro

(when-not-headless driver & body)
Executes the body only if a browser is NOT run in headless mode.

when-not-phantom

macro

(when-not-phantom driver & body)
Executes the body only if a browser is NOT Phantom.js.

when-not-predicate

macro

(when-not-predicate predicate & body)

when-not-safari

macro

(when-not-safari driver & body)
Executes the body only if a browser is NOT Safari.

when-phantom

macro

(when-phantom driver & body)
Executes the body only if the driver is Phantom.js.

when-predicate

macro

(when-predicate predicate & body)
Executes the body only if a predicate returns true.

when-safari

macro

(when-safari driver & body)
Executes the body only if the driver is Safari.

with-chrome

macro

(with-chrome opt bind & body)
Performs the body with Chrome session. A shortcut for
`with-driver`.

with-chrome-headless

macro

(with-chrome-headless opt bind & body)
Performs the body with headless Chrome session. A shortcut for
`with-driver`.

with-css

macro

(with-css driver & body)

with-driver

macro

(with-driver type opt bind & body)
Performs the body within a driver session.

Launches a driver of a given type. Binds the driver instance to a
passed `bind` symbol. Executes the body once the driver has
started. Shutdowns the driver finally (even if an exception
occurred).

Arguments:

- `type` is a keyword what driver type to start.

- `opt` is a map with driver's options. See `boot-driver` for more
details.

- `bind` is a symbol to bind a driver reference.

Example:

(with-driver :firefox {} driver
  (go driver "http://example.com"))

with-edge

macro

(with-edge opt bind & body)
Performs the body with Edge session. A shortcut for
`with-driver`.

with-edge-headless

macro

(with-edge-headless opt bind & body)
Performs the body with headless Edge session. A shortcut for
`with-driver`.

with-exception

macro

(with-exception catch fallback & body)

with-firefox

macro

(with-firefox opt bind & body)
Performs the body with Firefox session. A shortcut for
`with-driver`.

with-firefox-headless

macro

(with-firefox-headless opt bind & body)
Performs the body with headless Firefox session. A shortcut for
`with-driver`.

with-frame

macro

(with-frame driver q & body)
Switches to the (i)frame temporary while executing the body
returning the result of the last expression.

with-http-error

macro

(with-http-error & body)

with-key-down

macro

(with-key-down input key & body)

with-locator

macro

(with-locator driver locator & body)

with-mouse-btn

macro

(with-mouse-btn driver & body)
Performs the body keeping mouse botton pressed.

with-phantom

macro

(with-phantom opt bind & body)
Performs the body with Phantom.js session. A shortcut for
`with-driver`.

with-pointer-btn-down

macro

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

with-pointer-left-btn-down

macro

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

with-postmortem

macro

(with-postmortem driver opt & body)
Wraps the body with postmortem handler. If any error occurs,
it will save a screenshot, the page's source code and console logs
(if supported) on disk before rising an exception. Having them
could help you to discover what happened.

Note: do not use it in test's fixtures. The standard `clojure.test`
framework has its own way of handling exceptions, so wrapping a fixture
with `(with-postmortem...)` would be in vain.

Arguments:

- `driver`: a driver instance,

- `opt`: a map of options, where:

-- `:dir` path to a directory where to store artifacts by default.
Might not exist, will be created otherwise. When not passed,
the current working directory (`pwd`) is used.

-- `:dir-img`: path to a directory where to store `.png`
files (screenshots). If `nil`, `:dir` value is used.

-- `:dir-src`: path to a directory where to store `.html`
files (page source). If `nil`, `:dir` value is used.

-- `:dir-log`: path to a directory where to store `.json`
files with console logs. If `nil`, `:dir` value is used.

-- `:date-format`: a string represents date(time) pattern to make
filenames unique. Default is "yyyy-MM-dd-HH-mm-ss". See Oracle
Java `SimpleDateFormat` class manual for more patterns.

with-safari

macro

(with-safari opt bind & body)
Performs the body with Safari session. A shortcut for
`with-driver`.

with-screenshots

macro

(with-screenshots driver dir & body)
Makes a screenshot after each form

with-script-timeout

macro

(with-script-timeout driver sec & body)
Performs the body setting the script timeout temporary.
Useful for async JS scripts.

with-wait

macro

(with-wait n & body)
Executes the body waiting for n seconds before each form.
Returns a value of the last form. Use that macros to perform
a bunch of actions slowly. Some SPA applications need extra time
to re-render the content.

with-wait-interval

macro

(with-wait-interval sec & body)

with-wait-timeout

macro

(with-wait-timeout sec & body)

with-xpath

macro

(with-xpath driver & body)