cuic.core — cuic 0.6.0-20201123.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

DOM node that acts as a root node 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 (DOM node) 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 node & files)

Add files to the given node. Node must be a valid html file input element or otherwise an exception is thrown. If node is not in the view, scrolls the node into view first. Waits cuic.core/*timeout* until the node 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.

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

as clj

(as node name)

Assigns a new debug name for the give node. 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 node)

Returns node'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? node)

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

choose clj

(choose node & options)

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

Returns the target node for threading.

classes clj

(classes node)

Returns a set of css classes (as strings) for the given node. Returns an empty set if node 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 node)

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

Returns the target node for threading.

click clj

(click node)

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

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

Returns the clicked node for threading.

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

client-rect clj

(client-rect node)

Returns the bounding client rect for the given node 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? node)

Returns boolean whether the given node is disabled or not.

document clj

(document)

(document browser)

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

double-click clj

(double-click node)

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

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

Returns the clicked node 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 node 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 node 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 node text)

(fill node text opts)

Fills the given text to the given input or textarea element, clearing any previous text before typing the new text. If node is not in the view, scrolls the node into view first. Waits cuic.core/*timeout* until the node 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 node 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 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 node, 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 node)

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

Returns the focused node 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? node class)

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

has-focus? clj

(has-focus? node)

Returns boolean whether the given node has focus or not

hover clj

(hover node)

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

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

Returns the target node for threading.

in clj macro

(in scope & body)

Macro that runs its body using the given node as "root scope" for queries: all matching elements must be found under the node. Scope must be a valid DOM node 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? node)

Returns boolean whether the given node is currently visible and in the viewport

inner-text clj

(inner-text node)

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

matches? clj

(matches? node selector)

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

name clj

(name node)

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

options clj

(options node)

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

outer-html clj

(outer-html node)

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

press clj

(press key)

(press key browser)

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 another-chrome)

query clj

(query selector)

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

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

;; 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 nodes 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 node)

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

Returns the target node for threading.

select-text clj

(select-text node)

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

Returns the target node 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 node)

Returns the text content of the given node. 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 node 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 node. 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 node)

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

visible? clj

(visible? node)

Returns boolean whether the given node 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.