cuic.core — cuic 0.6.0-20210223.1

Core functions for UI queries and interactions

*base-url* clj

Base url that will be prepended to cuic.core/goto url if the value does not contain hostname.

Use binding to assign default for e.g. single test run:

(defn local-server-test-fixture [t]
  (binding [*base-url* (str "http://localhost:" (get-local-server-port))]
    (t)))

*browser* clj

Default browser that will be used for core queries such as cuic.core/find, cuic.core/document or cuic.core/window if not explicitly defined during the query invocation time.

Use binding to assign default for e.g. single test run:

(defn shared-chrome-fixture [t]
  (binding [*browser* (get-shared-chrome-instance-somehow)]
    (t)))

*query-scope* clj

HTML element that acts as a root scope for cuic.core/find and cuic.core/query queries, unless othewise specified at query invocation time. Setting this value to nil indicates that queries should use document scope by default.

Do not bind this variable directly, instead use cuic.core/in to define query scope in your application code.

*timeout* clj

Default implicit timeout (in milliseconds) for queries and interactions before cuic.TimeoutException is thrown

Use binding to assign default for e.g. single test run:

(defn browser-test-defaults-fixture [t]
  (binding [*timeout*       20000
            *typing-speed* :tycitys]
    (t)))

*typing-speed* clj

Default typing speed in typed characters per minute. Supports also the following preset values:

• :slow - 300 chars/min
• :normal - 600 chars/min
• :fast - 1200 chars/min
• :very-fast - 2400 chars/min
• :tycitys - 12000 chars/min

Use binding to assign default for e.g. single test run:

(defn browser-test-defaults-fixture [t]
  (binding [*timeout*       20000
            *typing-speed* :tycitys]
    (t)))

active-element clj

(active-element)

(active-element browser)

Returns active element (HTML element) for the current default browser or nil if there are no active elements in the page at the moment. Default browser can be overriden by providing browser explicitly as a parameter.

add-files clj

(add-files element files)

(add-files element files {:keys [allow-hidden?] :or {allow-hidden? false}})

Add files to the given element. Element must be a valid html file input element or otherwise an exception is thrown. If element is not in the view, scrolls it into the view first. Waits cuic.core/*timeout* until the element becomes available (visible and not disabled) or throws an exception if the timeout exceeds.

The given files must be java.io.File instances and all of them must exist in the filesystem.

By default the target input must be visible. However, because it's very common in modern web applications that file inputs are hidden due to their bleak appearance, you can disable the visibility requirement by providing :allow-hidden? true option. The input must still be enabled though.

(require '[clojure.java.io :as io])
(def photo (c/find "input#photo"))
(c/add-files photo [(io/file "photos/profile.jpg")])

;; add profile picture to a hidden input
(c/add-files hidden-input [(io/file "photos/profile.jpg")] {:allow-hidden? true})

as clj

(as element name)

Assigns a new custom name for the give element. The assigned name will be displayed in REPL and in error messages but it does not have any effect on other behaviour.

(-> (c/find "#sidebar")
    (c/as "Sidebar")

Note that usually one should prefer (find {:as <name> :by <sel>}) for assigning names instead of (-> (find <sel>) (as <name>) because then the name will be displayed in error message if find fails for some reason. See cuic.core/find and cuic.core/query for more details.

attributes clj

(attributes element)

Returns element's HTML attributes as a map of keyword keys and string values. Boolean attribute values will be converted to true if they are present

;; html element <div id='foo' data-val='1' class='foo bar'></div>
(c/attributes (c/find "#foo"))
; =>
{:id       "foo"
 :data-val "1"
 :class    "foo bar"}

checked? clj

(checked? element)

Returns boolean whether the given element is checked or not. Throws an exception if the target element is not a valid input element.

children clj

(children element)

Returns children of the given html element as a vector or nil if element does not have children.

choose clj

(choose element & options)

Chooses the given options (strings) from the given element. element must be a html select element or otherwise an exception will be thrown. If element is not in the view, scrolls it into the view first. Waits cuic.core/*timeout* until the element becomes fillable (visible and not disabled) or throws an exception if the timeout exceeds.

Returns the target element for threading.

classes clj

(classes element)

Returns a set of css classes (as strings) for the given element. Returns an empty set if element does not have any classes.

;; <div id='foo' class='foo bar'></div>
(c/classes (c/find "#foo"))
; =>
#{"foo" "bar"}

;; <div id='foo'></div>
(c/classes (c/find "#foo"))
; =>
#{}

clear-text clj

(clear-text element)

First scrolls the given element into view (if needed) and then clears all text from the element. element must be an input/textarea element or otherwise an exception is thrown. Waits cuic.core/*timeout* until the element becomes visible or throws an exception if timeout exceeds.

Returns the target element for threading.

click clj

(click element)

First scrolls the given element into view (if needed) and then clicks the element once. Waits cuic.core/*timeout* until the element becomes visible or throws an exception if timeout exceeds.

Throws an exception if element is not clickable: it has either zero width or zero height or it is disabled.

Returns the clicked element for threading.

(c/click (c/find "button#save"))

client-rect clj

(client-rect element)

Returns the bounding client rect for the given element as a map of:

{:top    <number>
 :left   <number>
 :width  <number>
 :height <number>}

See https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect for more info.

disabled? clj

(disabled? element)

Returns boolean whether the given element is disabled or not.

document clj

(document)

(document browser)

Returns a document object (HTML element) for the current default browser. Default browser can be overriden by providing browser explicitly as a parameter.

double-click clj

(double-click element)

First scrolls the given element into view (if needed) and then double-clicks the element once. Waits cuic.core/*timeout* until the element becomes visible or throws an exception if timeout exceeds.

Throws an exception if element is not clickable: it has either zero width or zero height or it is disabled.

Returns the clicked element for threading.

(c/double-click (c/find "button#save"))

eval-js clj

(eval-js expr)

(eval-js expr args)

(eval-js expr args this)

Evaluates the given JavaScript expression in the given this object context and returns the expression's result value. Expression may take arguments from Clojure code.

By default this refers to the cuic.core/window of the current default browser but it may be rebound to any html element or window object.

Arguments serializable JSON values:

• nil (will be converted to null
• booleans
• numbers
• maps (will be converted to objects)
• collections (will be converted to arrays)

Likewise the return value of the expression is limited to JSON values:

• null, undefined (will be converted to nil)
• booleans
• numbers
• object (will be converted to maps)
• arrays (will be converted to vectors)

;; Return title of the current browser window
(c/eval-js "document.title")

;; Return async value
(c/eval-js "await new Promise(resolve => setTimeout(() => resolve('tsers'), 500))")

;; Increment list values in JS side
(c/eval-js "xs.map(x => x + 1)" {:xs [1 2 3]})

;; Perform some arithmetics in JS side
(c/eval-js "a + b.num" {:a 1000 :b {:num 337}})

;; Get placeholder value from the query input
(let [q (c/find "#query")]
  (c/eval-js "this.placeholder" {} q))

See also cuic.core/exec-js if you want to execute statements in JavaScript side.

exec-js clj

(exec-js body)

(exec-js body args)

(exec-js body args this)

Executes the given JavaScript function body in the given this object context. The executed body may also be parametrized by arguments from Clojure code, and it can return value by using JavaScript's return statement in the end. Function body may await async values/effects.

By default this refers to the cuic.core/window of the current default browser but it may be rebound to any html element or window object.

Arguments serializable JSON values:

• nil (will be converted to null
• booleans
• numbers
• maps (will be converted to objects)
• collections (will be converted to arrays)

Likewise the return value of the expression is limited to JSON values:

• null, undefined (will be converted to nil)
• booleans
• numbers
• object (will be converted to maps)
• arrays (will be converted to vectors)

;; Reset document title
(c/exec-js "document.title = 'tsers'")

;; Reset input's placeholder value
(let [input (c/find "#my-input")]
  (c/exec-js "this.setAttribute('placeholder', text)" {:text "tsers"} input))

;; Reset document's title and return the prior value
(c/exec-js "const prev = document.title;
             document.title = 'tsers';
             return prev;")

See also cuic.core/eval-js if you only want to query data from JavaScript side without performing any side-effects.

fill clj

(fill element text)

(fill element text opts)

Fills the given text to the given input or textarea element, clearing any previous text before typing the new text. If element is not in the view, scrolls it into the view first. Waits cuic.core/*timeout* until the element becomes fillable (visible and not disabled) or throws an exception if the timeout exceeds.

Uses cuic.core/*typing-speed* by default but it can be overrided by giving the speed as a third parameter. See cuic.core/*typing-speed* for valid values. Only text is allowed: if you need to type keycodes, use cuic.core/type instead. The exceptions are newline character \n and tab \t that will be interpreted as their respective key presses.

Returns the filled element for threading.

(def comment (c/find "input.comment"))

;; Fill some text to comment and commit by pressing enter
(c/fill comment "Tsers")
(c/press 'Enter)

;; Same in terser form
(c/fill comment "Tsers\n")

;; Fill text fast
(c/fill comment "Tsers" {:speed :tycitys})

find clj

(find selector)

Tries to find exactly one html element by the given css selector and throws an exception element wasn't found or there are multiple elements matching the selector.

If any element is not found from the DOM, find tries to wait for it until the element appears to the DOM or timeout exceeds. By default, the wait timeout is cuic.core/*timeout* but it can be overriden per invocation.

Basic usage:

(def search-input (c/find ".navi input.search")

In addition to plain css selector, find can be invoked with more information by using map form:

(find {:by      <selector>  ; mandatory - CSS selector for the query
       :in      <scope>     ; optional - root scope for query, defaults to document see cuic.core/in
       :as      <name>      ; optional - name of the result element, see cuic.core/as
       :timeout <ms>        ; optional - wait timeout in ms, defaults to cuic.core/*timeout*
       })

;; examples

(c/find {:by ".navi input.search"
         :as "Quick search input"})

(c/find {:in      (find "#sidebar")
         :by      ".logo"
         :timeout 10000})

focus clj

(focus element)

First scrolls the given element into view (if needed) and then focuses on the element. Waits cuic.core/*timeout* until the element becomes visible or throws an exception if timeout exceeds.

Returns the focused element for threading.

go-back clj

(go-back)

(go-back opts)

Simulates browser back button click. Returns boolean whether the back button was pressed or not. Back button pressing is disabled if there is no browser history to go back anymore.

;; Use default browser and timeout
(c/go-back)

;; Use non-default browser
(c/go-back {:browser another-chrome})

;; Use non-default timeout
(c/go-back {:timeout 1000})

go-forward clj

(go-forward)

(go-forward opts)

Simulates browser forward button click. Returns boolean whether the forward button was pressed or not. Forward button pressing is disabled if browser is already at the latest navigated page.

;; Use default browser and timeout
(c/go-forward)

;; Use non-default browser
(c/go-forward {:browser another-chrome})

;; Use non-default timeout
(c/go-forward {:timeout 1000})

goto clj

(goto url)

(goto url opts)

Navigates browser to the given url, equivalent to user typing url to the browser address bar and pressing enter. Url must contain the protocol. Reloads the page, even if navigating to the current page, and waits until the page is loaded or timeout exceeds. Uses cuic.core/*timeout* by default but it can be overrided by giving the timeout as an option to the invodation.

If cuic.core/*base-url* is set, it'll be prepended to the given url if the given url does not contain hostname.

Uses the current browser by default but it can be overrided by providing browser as an option to the invocation.

;; Use default browser and timeout
(c/goto "https://clojuredocs.org")

;; Use non-default browser
(c/goto "https://clojuredocs.org" {:browser another-chrome})

;; Use non-default timeout
(c/goto "https://clojuredocs.org" {:timeout 300000})

;; Go to https://clojuredocs.org/clojure.core/map using base url
(binding [c/*base-url* "https://clojuredocs.org"]
  (c/goto "/clojure.core/map"))

has-class? clj

(has-class? element class)

Returns boolean whether the given element has the tested css class or not

has-focus? clj

(has-focus? element)

Returns boolean whether the given element has focus or not

hover clj

(hover element)

First scrolls the given element into view (if needed) and then moves the mouse over the element. Waits cuic.core/*timeout* until the element becomes visible or throws an exception if timeout exceeds.

Throws an exception if element is not hoverable: it has either zero width or zero height.

Returns the target element for threading.

in clj macro

(in scope & body)

Macro that runs its body using the given element as "root scope" for queries: all matching elements must be found under the element. Scope must be a valid HTML element or otherwise an exception will be thrown.

;; the following codes are equivalent

(c/in (c/find "#header")
  (let [items (c/query ".navi-item")]
    ...))

(let [header (c/find "#header")
      items (c/query {:in header :by ".navi-item"})]
  ...)

in-viewport? clj

(in-viewport? element)

Returns boolean whether the given element currently visible and in the viewport

inner-text clj

(inner-text element)

Returns the inner text of the given html element. See https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/innerText for more info.

matches? clj

(matches? element selector)

Returns boolean whether the given element matches the tested css selector or not. Throws an exception if selector is not valid.

name clj

(name element)

Returns the custom name of the given element or nil if debug name is not set for the element.

options clj

(options element)

Returns a list of options {:keys [value text selected]} for the given element. Throws an exception if element is not a select element.

outer-html clj

(outer-html element)

Returns the outer HTML of the given element as hiccup. Comments will be returned using :-#comment tag and CDATA nodes will be returned using :-#data tag.

parent clj

(parent element)

Returns parent element of the given html element or nil if element does not have parent (= document)

press clj

(press key)

(press key opts)

Simulates key press of single key. The pressed key must be a symbol of a valid keycode with optional modifiers separated by '+' (see examples below). You can use e.g. https://keycode.info to get desired key code (event.code) for the pressed key. The complete list of available key codes can be found from https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/keyCode

Uses the current browser by default but it can be overrided by providing browser as a second parameter.

;; Focus on next tab index element
(c/press 'Tab)

;; Focus on previous tab index element
(c/press 'Shift+Tab)

;; Focus on next tab index element in custom browser
(c/press 'Tab {:browser another-chrome})

query clj

(query selector)

Works like cuic.core/find but returns 0..n elements matching the given css selector. In case of no results, nil will be returned, otherwise the return value is a vector of matching HTML elements.

Basic usage:

(def navi-items
  (c/query ".navi .item")

In addition to plain css selector, query can be invoked with more information by using map form:

(query {:by <selector>  ; mandatory - CSS selector for the query
        :in <scope>     ; optional - root scope for query, defaults to document see cuic.core/in
        :as <name>      ; optional - name for the result elements
        })

;; examples

(c/query {:by ".navi .item"
          :as "Navigation item"})

(c/find {:in (find "#sidebar")
         :by ".item"
         :as "Sidebar item"})

Note that unlike cuic.core/find, cuic.core/query does not wait for the results: if there are zero elements matching the given selector at the query time, the result set will be nil. If some results are expected, use cuic.core/query in conjunction with cuic.core/wait e.g.

(c/wait (c/query ".navi .item"))

screenshot clj

(screenshot)

(screenshot {:keys [browser format quality timeout]
             :or {format :png quality 50 timeout *timeout*}})

Captures a screenshot from the current page and returns a byte array the the captured image data. Image format and quality can be configured by the following options:

{:format  ... ; either :jpeg or :png>
 :quality ... ; 0-100, applied only if format is :jpeg
 }

Uses the current browser by default but it can be overrided by providing browser as an option to the invocation.

;; Take PNG screenshot and save it the disk
(let [data (c/screenshot)]
  (io/copy data (io/file "screenshots/example.png")))

;; Take JPEG screenshot with quality of 75
(c/screenshot {:format :jpeg :quality 75})

;; Take screenshot from non-default browser
(c/screenshot {:browser another-chrome})

scroll-into-view clj

(scroll-into-view element)

Scrolls the given element into view if it is not in the view already. Waits cuic.core/*timeout* until the element becomes visible or throws an exception if timeout exceeds.

Returns the target element for threading.

select-text clj

(select-text element)

First scrolls the given element into view (if needed) and then selects all text from the element. element must be an input/textarea element or otherwise an exception is thrown. Waits cuic.core/*timeout* until the element becomes visible or throws an exception if timeout exceeds.

Returns the target element for threading.

set-base-url! clj

(set-base-url! base-url)

Globally resets the default base url. Useful for example REPL usage. See cuic.core/*timeout* for more details.

set-browser! clj

(set-browser! browser)

Globally resets the default browser. Useful for example REPL usage. See cuic.core/*browser* for more details.

set-timeout! clj

(set-timeout! timeout)

Globally resets the default implicit timeout. Useful for example REPL usage. See cuic.core/*timeout* for more details.

set-typing-speed! clj

(set-typing-speed! speed)

Globally resets the default typing speed. Useful for example REPL usage. See cuic.core/*typing-speed* for more details.

sleep clj

(sleep ms)

Stops the current thread execution for the given n milliseconds.

text-content clj

(text-content element)

Returns the text content of the given html element. See https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent for more info.

timeout-ex? clj

(timeout-ex? ex)

Return true if the given exception is caused by timeout while waiting for certain condition, for example element becoming visible before click or custom condition from cuic.core/wait.

type clj

(type text)

(type text opts)

Simulates keyboard typing. Characters are pressed and released one by one using the provided typing speed. Typing speed uses cuic.core/*typing-speed* by default but it can be overrided by giving it as :speed option to the invocation.

Note that this function is pretty low level and it does not focus the typed text to any element. See cuic.core/fill for a more high-level alternative.

Uses the current browser by default but it can be overrided by providing :browser option to the invocation.

;; Type some text
(c/type "Tsers!")

;; Type some text very fast
(c/type "Tsers!" {:speed :tycitys})

;; Type some text to non-default browser
(c/type "Tsers!" {:browser another-chrome})

value clj

(value element)

Returns the current string value of the given input/select/textarea element. Throws an exception if the target element is not a valid input element

visible? clj

(visible? element)

Returns boolean whether the given element is visible in DOM or not

wait clj macro

(wait expr)

(wait expr timeout)

Macro that waits until the given expression returns a truthy value or timeouts. Uses cuic.core/*timeout* by default but the timeout value can be overrided by providing it as a second parameter.

Attention: the waited expression may be invoked multiple times so it should not mutate anything during the invocation!

window clj

(window)

(window browser)

Returns a window object for the current default browser. Note that window can only be used as this in cuic.core/eval-js and cuic.core/exec-js but not as query scope. For query scopes, use cuic.core/document instead.

Default browser can be overriden by providing browser explicitly as a parameter.