limo.api — limo 0.2.4

The core API wrapper around selenium webdrivers

*default-interval* clj

*default-timeout* clj

The default timeout in milliseconds until limo gives up attempting to try an action. Defaults to 15 seconds (15000).

This value is used for wait-* set of functions which most other function calls rely upon.

The default value is generous enough to try and cover a variety of machine speeds, but you may find value in tweaking this parameter when checking for a negative state (eg - verifying that a checkbox isn't checked).

*driver* clj

The implied selenium WebDriver instance to use when invoking functions with api calls.

All API functions can explicitly accept the WebDriver as the first argument. Otherwise if that argument is excluded, then this dynamically bounded var is used instead.

Example:

(limo.api/click "#button") ;; becomes (limo.api/click driver "#button")

Defaults to nil. Use set-driver! as a way to quickly set this variable.

active-window clj

(active-window)

(active-window driver)

Returns the window id (string) of the current window that the driver is focused on.

The active-window is the window where (switch-to-window (active-window)) is a no-op.

See switch-to-window to switch focused window. See all-windows to list all window ids See active-window to get the current window id

IMMEDIATE: This function is considered immediate, and does not poll using wait-until or wait-for. Thus, it is unaffected by *default-timeout*.

all-windows clj

(all-windows)

(all-windows driver)

Returns a sequence of all window ids (strings) that refer to specific browser windows the driver controls.

IMMEDIATE: This function is considered immediate, and does not poll using wait-until or wait-for. Thus, it is unaffected by *default-timeout*.

allow-backspace? clj

(allow-backspace? e)

Returns a true if the given element can handle backspace keypresses.

Hitting backspace on anything except selects, radios, checkboxes will cause the browser to go back to the previous page.

attribute clj

(attribute selector-or-element attr)

(attribute driver selector-or-element attr)

Returns an element's attribute value for a given attribute name.

by clj

(by s)

Creates a Selenium By instance (aka - a selenium element search query) to find an HTML element.

In general, you shouldn't probably be calling this function directly. All limo functions call element which internally calls this function to find an element.

This function accepts either a String, Selenium WebElement or a map containing one of the following keys to indicate how to find a DOM element:

• :css or :css-selector => search by CSS selector
• :id => search by element ID attribute
• :xpath => search by element xpath
• :tag-name => search by element tag name (eg - p, h1, div)
• :link-text => search by anchor text
• :partial-link-text => search by anchor text containing some text
• :name => search by name attribute (eg - input fields)
• :class-name => search by a css class name the element has

Examples:

;; return By instance to query by CSS

(by "h1") ;; Implies (by {:css "h1"})

clear-fields clj

(clear-fields fields)

Like fill-form, but clears all the text contents of inputs by deleting its contents.

NOTE: currently this is very naive presses backspace and delete N times, where N is the len of the text.

click clj

(click selector-or-element)

(click driver selector-or-element)

Clicks on a given element.

click-when-visible clj

(click-when-visible selector)

Clicks on a given element, but makes sure it's visible before doing so.

contains-text? clj

(contains-text? selector-or-element expected-substr)

(contains-text? driver selector-or-element expected-substr)

Returns true if the element has innerText contains a given value. The comparison is case-insensitive and will timeout if a match does not occur.

current-url clj

(current-url)

(current-url driver)

Returns the current url the browser is on.

IMMEDIATE: This function is considered immediate, and does not poll using wait-until or wait-for. Thus, it is unaffected by *default-timeout*.

current-url-contains? clj

(current-url-contains? substr)

Returns true if the current url contains some text

delete-all-cookies clj

(delete-all-cookies)

(delete-all-cookies driver)

Deletes all cookies associated with the page the browser is currently on.

There is no way in Selenium's APIs to clear all cookies in a driver without re-creating the driver. If you wish to reuse a driver, you must navigate to every domain and call this function to clear cookies.

IMMEDIATE: This function is considered immediate, and does not poll using wait-until or wait-for. Thus, it is unaffected by *default-timeout*.

element clj

(element selector-or-element)

(element driver selector-or-element)

Returns a selenium WebElement of a selector that by accepts.

If selector-or-element is an element?, then the value is simply returned.

IMMEDIATE: This function is considered immediate, and does not poll using wait-until or wait-for. Thus, it is unaffected by *default-timeout*.

element-matches clj

(element-matches selector-or-element pred)

(element-matches driver selector-or-element pred)

Returns true if the element has a certain number of elements that matches the given query.

element? clj

(element? e)

Helper function. A predicate that indicates if the given value is a selenium WebElement instance.

elements clj

(elements selector-or-elements)

(elements driver selector-or-elements)

Returns a sequence of WebElement instances that match the selector that by accepts.

If selector-or-element is an element?, then the value is simply returned.

IMMEDIATE: This function is considered immediate, and does not poll using wait-until or wait-for. Thus, it is unaffected by *default-timeout*.

execute-script clj

(execute-script driver js & js-args)

Evaluates a given javascript string on the page.

Generally you want to control most of your interacts via the supported browser operations, but sometimes it's needed to run some javascript on the page directly - like activating a verbose logging mode, or forcing one into a specific A/B test.

Parameters:

• driver is the selenium driver to use
• js is the javascript string to eval on the page.
• js-args is the variadic arguments of values to pass into the eval function. These values are limited to what can be translated to javascript, which are the following:
  • numbers
  • booleans
  • strings
  • WebElements (objects returned via element)
  • lists of any above types

Note: The javascript script string is executed in anonymous closure like this:

(function(){ $JS })($JS-ARGS);

which means you'll need to use arguments in js to access arguments pass through from clojure to javascript.

Returns: The return value is whatever the return value of the javascript eval expression, which are also constrainted to the same times that can be translated as a js-args value.

IMMEDIATE: This function is considered immediate, and does not poll using wait-until or wait-for. Thus, it is unaffected by *default-timeout*.

exists? clj

(exists? selector-or-element)

(exists? driver selector-or-element)

Returns a boolean indicates if the given selector (that by accepts) matches an element that is not the current page the selenium browser is viewing.

IMMEDIATE: This function is considered immediate, and does not poll using wait-until or wait-for. Thus, it is unaffected by *default-timeout*.

fill-form clj

(fill-form fields)

(fill-form fields1 fields2 & more-fields)

Fills forms either by input text (if a string is given) or calling a function.

This function is variadic to allow ordered-filling of inputs.

If text is filled in, then its prior contents is cleared first.

Example:

(fill-form {"input[name=name]" "my name" "input[email=email]" "[e-mail]"} {"input[type=submit]" click})

has-class clj

(has-class q class)

Returns a true if a given element has a class on it.

implicit-wait clj

(implicit-wait timeout)

(implicit-wait driver timeout)

Sets the driver's implicit wait interval. The implicit wait interval is poll interval is how much a browser will wait.

There are two kinds of waits:

• The test suite polls & waits (see *default-interval*, *default-timeout*, wait-until, wait-for, wait-until-clickable, wait-for-else). Here the test suite / limo is responsible for polling and asking the browser to see if an element exists.
• The browser waits for an element to appear. This is what implicit-wait configures.

For example, if we ask the browser to click on #button, but it isn't immediately available, the browser will use the implicit-wait value to internally wait up to the given time until returning an element not found error.

Read Selenium's explaination of waits for another perspective of the same thing: http://www.seleniumhq.org/docs/04_webdriver_advanced.jsp#explicit-and-implicit-waits

in-new-window clj macro

(in-new-window opts action do-body)

(in-new-window driver {:keys [auto-close?]} action do-body)

Creates a temporary new browser window that do-body runs inside.

input-text clj

Alias to send-keys. Sends keypresses to a given element. Types on a given input field.

Characters can be strings or vector of strings.

invisible? clj

(invisible? selector-or-element)

(invisible? driver selector-or-element)

Returns true if the given element is invisible.

narrate clj macro

(narrate msg & args)

normalize-fields clj

(normalize-fields fields)

Converts all string values that indicate typing text into functions

num-elements= clj

(num-elements= selector-or-element expected-count)

(num-elements= driver selector-or-element expected-count)

Returns true if the element has a certain number of elements that matches the given query.

options clj

(options selector-or-element)

(options driver selector-or-element)

Returns a sequence of all form value and visible text for a given drop-down

quit clj

(quit)

(quit driver)

Closes the driver, which implies closing all browser windows the driver has created.

IMMEDIATE: This function is considered immediate, and does not poll using wait-until or wait-for. Thus, it is unaffected by *default-timeout*.

read-json-logs! clj

(read-json-logs! log-type-kw)

(read-json-logs! driver log-type-kw)

Identical read-logs!, but parses the message body as JSON.

NOTE: the same limitations as read-logs! applies: that is, that the browser may discard the log information after the request to retrive the logs occurs.

This is known to be useful with Chrome's performance logs to get network and rendering information. Chrome's performance log data is encoded in JSON.

read-json-logs! is pretty low-level in comparison to most of the other limo apis. Considering using [[read-performance-logs-until-test-pass!]]

read-logs! clj

(read-logs! log-type-kw)

(read-logs! driver log-type-kw)

Retrieves logs of a given type from the browser being control by selenium.

NOTE: The browser may discard the log information after the request to retrive the logs occurs. This means multiple calls to readonly-logs! can return different results.

(count (read-logs!)) => 5 (count (read-logs!)) => 0

read-logs! is pretty low-level in comparison to most of the other limo apis. Considering using [[read-performance-logs-until-test-pass!]]

refresh clj

(refresh)

(refresh driver)

Refreshes/Reloads the current page the browser is on.

IMMEDIATE: This function is considered immediate, and does not poll using wait-until or wait-for. Thus, it is unaffected by *default-timeout*.

screenshot clj

(screenshot name)

(screenshot name dir-f)

A higher-level function to take a screenshot and immediately save it on disk.

scroll-to clj

(scroll-to selector-or-element)

(scroll-to driver selector-or-element)

Scrolls the browser to a given element so that it visible on the screen.

select-by-text clj

(select-by-text selector-or-element value)

(select-by-text driver selector-or-element value)

Selects a given option in a drop-down element by the user-visible text on the element.

Useful if you know you want to select a given option that is visible on screen and its value changes more often that its display text.

select-by-value clj

(select-by-value selector-or-element value)

(select-by-value driver selector-or-element value)

Selects a given option in a drop-down element by the server-provided value of the element.

Useful if you know you want to select a given option that has a constant value, but may change its user-visible text more often.

selected? clj

(selected? selector-or-element)

(selected? driver selector-or-element)

Returns true if the given element is selected (eg - checkbox)

send-keys clj

(send-keys selector-or-element s)

(send-keys driver selector-or-element s)

Sends keypresses to a given element. Types on a given input field.

Characters can be strings or vector of strings.

set-checkbox clj

(set-checkbox selector checked?)

Sets a checkbox element to the given state (true = check, false = unchecked)

set-driver! clj

(set-driver! d)

Sets the current implied active selenium WebDriver (*driver*).

Note: (set-driver! nil) is a no-op.

submit clj

Alias to click. Typically reads nice when referring to submit buttons.

switch-to-frame clj

(switch-to-frame frame-element)

(switch-to-frame driver frame-element)

Changes the driver's DOM queries to target a given frame or iframe.

Drivers do no walk through child frames/iframes' DOM elements. This function allows all subsequent calls (eg - element) will target elements inside that frame.

See switch-to-main-page to restore querying against the page elements. See switch-to-window to query against windows.

switch-to-main-page clj

(switch-to-main-page)

(switch-to-main-page driver)

Changes the driver's DOM queries to target the main page body.

Drivers do no walk through child frames/iframes' DOM elements. This function allows all subsequent calls (eg - element) will target elements directly on the page.

See switch-to-frame to query against iframes / frames. See switch-to-window to query against windows.

IMMEDIATE: This function is considered immediate, and does not poll using wait-until or wait-for. Thus, it is unaffected by *default-timeout*.

switch-to-window clj

(switch-to-window window-handle)

(switch-to-window driver window-handle)

Changes the driver's DOM queries to target a given browser window.

See switch-to-frame to query against iframes / frames. See all-windows to list all window ids See active-window to get the current window id

tag clj

(tag selector-or-element)

(tag driver selector-or-element)

Returns an element's html tag name.

take-screenshot clj

(take-screenshot)

(take-screenshot format)

(take-screenshot format destination)

(take-screenshot driver format destination)

Tells the driver to capture a screenshot of the currently active window.

Paramters:

format: Can be :file, :base64, or :bytes which prescribes the return value destination: An optional path to save the screenshot to disk. Set nil to ignore.

Returns:

org.openqa.selenium.OutputType instance with the screenshot data in the desired format.

IMMEDIATE: This function is considered immediate, and does not poll using wait-until or wait-for. Thus, it is unaffected by *default-timeout*.

text clj

(text selector-or-element)

(text driver selector-or-element)

Returns an element's innerText.

text= clj

(text= selector-or-element expected-value)

(text= driver selector-or-element expected-value)

Returns true if the element has innerText of a given value. The comparison is case-insensitive and will timeout if a match does not occur.

to clj

(to url)

(to driver url)

Navigates to a given url. As if one types on the address bar.

IMMEDIATE: This function is considered immediate, and does not poll using wait-until or wait-for. Thus, it is unaffected by *default-timeout*.

toggle clj

Alias to click. Typically reads nice when referring to checkboxes

value clj

(value selector-or-element)

(value driver selector-or-element)

Returns the input's value of a given input element

value= clj

(value= selector-or-element expected-value)

(value= driver selector-or-element expected-value)

Returns true if the element has a value of a given string. The comparison is case-insensitive and will timeout if a match does not occur.

visible? clj

(visible? selector-or-element)

(visible? driver selector-or-element)

Returns true if the given element is visible?

wait-for clj macro

(wait-for driver narration & body)

A specialized version of wait-until that includes narration (printing to stdout) the action that is taken.

wait-for-else clj macro

(wait-for-else driver narration default-value & body)

Like wait-for, but has a default return value if the waiting predicate fails.

wait-until clj

(wait-until pred)

(wait-until pred timeout)

(wait-until pred timeout interval)

(wait-until driver pred timeout interval)

Runs a given predicate pred repeatedly until a timeout occurs or pred returns a truthy value.

This is usually called by other limo APIs unless IMMEDIATE is indicated in the docs.

Parameters:

• pred can return a value, and that becomes the return value of wait-until.
• timeout in the time in milliseconds to wait for. Uses *default-timeout* if not explicitly specified.
• interval is the time in milliseconds between calling pred. Defaults to 0 because implicit-wait is probably what you want to set.
• driver is an alternative WebDriver instance to use other than *driver*.

Waits & polls: There are 3-values that dicate polling in Limo: timeout interval, sleep interval, and browser wait interval.

• Timeout interval is the maximum time in Selenium (& Limo) which an action can take in its entirety.
• Sleep interval is the Thead.sleep call Selenium calls inbetween calls to pred returning a falsy value.
• Browser wait interval (aka - ImplicitlyWait) is the maximum time the browser will wait for an element that matches to appear.

In our experience, the browser wait interval is usually what keeps actions held. An action like "click this button" relies on the button existing before it can be clicked.

StaleElementReferenceException are captured and indicate a falsy return value of pred. Other exceptions will be rethrown.

wait-until-clickable clj

(wait-until-clickable selector)

(wait-until-clickable driver selector timeout)

A specialized version of wait-until that waits until an element is clickable.

window-resize clj

(window-resize dimensions-map)

(window-resize driver {:keys [width height] :as dimensions-map})

Resizes the current window to the given dimensions.

IMMEDIATE: This function is considered immediate, and does not poll using wait-until or wait-for. Thus, it is unaffected by *default-timeout*.

window-size clj

(window-size)

(window-size driver)

Returns the current window's size

IMMEDIATE: This function is considered immediate, and does not poll using wait-until or wait-for. Thus, it is unaffected by *default-timeout*.

with-window-size clj macro

(with-window-size new-size & body)

Temporarily resizes the current driver window when evaluating the body expression.

with-window-size* clj

(with-window-size* new-size actions-fn)

(with-window-size* driver new-size actions-fn)

Use with-window-size instead.