cuic.core — cuic 1.0.0-RC1

Core functions for UI queries and interactions

*base-url* clj

Base url that will be prepended to cuic.core/goto url if the url 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 the core queries such as cuic.core/find, cuic.core/document or cuic.core/window if the browser is 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 an implicit root scope for cuic.core/find and cuic.core/query invocations, unless explicitly 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 the 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 the active element (HTML element) for the current default browser or nil if there are no active element 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}})

Adds files to the given element. The element must be a valid html file input or otherwise an exception is thrown. If the element is not in the viewport, 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 an :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 given element. The assigned name will be displayed in REPL and in error messages but it does not have any effect on the JavaScript page element.

(-> (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 also in the error message if find fails for some reason. See cuic.core/find and cuic.core/query for more details about name assignment at the query time.

attributes clj

(attributes element)

Returns element's HTML attributes as a map of {:attr-name "attr-value"}. 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 a vector of children of the given html element or nil if the element does not have any children.

See https://developer.mozilla.org/en-US/docs/Web/API/ParentNode/children for more details

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 the viewport (if needed) and then clears all text from the element. The element must be an input/textarea or otherwise an exception is thrown. Waits cuic.core/*timeout* until the element becomes visible or throws an exception if the timeout exceeds.

Returns the target element for threading.

click clj

(click element)

First scrolls the given element into the viewport (if needed) and then clicks the element once. Waits cuic.core/*timeout* until the element becomes visible or throws an exception if the 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.

closest clj

(closest element selector)

Returns the closest ancestor element that matches the given css selector or nil if there are no matches.

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

disabled? clj

(disabled? element)

Returns boolean whether the given element is disabled or not.

document clj

(document)

(document browser)

Returns the JavaScript document object 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 the viewport (if needed) and then double-clicks the element twice. Waits cuic.core/*timeout* until the element becomes visible or throws an exception if the 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 with the given this binding and returns the expression's result value. The evaluated expression may be parametrized with arguments from the Clojure code.

By default this refers to the cuic.core/window of the current default browser but it may be rebound to any JavaScript object reference (obtained from prior invocations or queries).

The given input arguments must be either serializable JSON values or JavaScript object references. The return value is serialized back to Clojure data structures and non-serializable JavaScript objects are returned back as JavaScript object references. Accessing the properties of those references is only possible by using either cuic.core/eval-js or cuic.core/exec-js.

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

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

;; Increment the given list values in JS side and return them
;; bac as CLJ vector
(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 the JavaScript side.

exec-js clj

(exec-js body)

(exec-js body args)

(exec-js body args this)

Executes the given JavaScript function bodu with the given this binding. The executed body may be parametrized with arguments from the Clojure code and it can return a value by using JavaScript's return statement at the end of the body. The function body may also await async values effects - Clojure invocation will block until the async result is resolved.

By default this refers to the cuic.core/window of the current default browser but it may be rebound to any JavaScript object reference (obtained from prior invocations or queries).

The given input arguments must be either serializable JSON values or JavaScript object references. The return value is serialized back to Clojure data structures and non-serializable JavaScript objects are returned back as JavaScript object references. Accessing the properties of those references is only possible by using either cuic.core/eval-js or cuic.core/exec-js.

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

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

;; Reset the document 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 the 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 the element is not in the viewport, 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/press 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 if the element wasn't found or there are more than one element matching the selector.

If the desired element is not found immediately, find waits until the element appears in the DOM. If the element does not appear within a certain time period, find throws an exception. By default, the wait timeout is cuic.core/*timeout* but it can be overrided 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 a 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
       :when    <predicate> ; optional - predicate function for extra conditions that the queried element must satisfy
       :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 {:by   "button"
         :when #(re-find #"Save" (c/text-content %))
         :as   "Save button"})

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

focus clj

(focus element)

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

Returns the focused element for threading.

go-back clj

(go-back)

(go-back opts)

Simulates browser's 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's 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's address bar and pressing enter. Url must contain the protocol. Reloads the page, even if navigating to the current page. 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 invocation.

If cuic.core/*base-url* is set, it'll be prepended to the given url if the given url does not contain a 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 the viewport (if needed) and then moves the mouse over the element. Waits cuic.core/*timeout* until the element becomes visible or throws an exception if the 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 the "root scope" for queries: all matching elements must be found under the element. Scope must be a valid HTML element or otherwise an exception is 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 is 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 the name is not set for the element.

offset-parent clj

(offset-parent element)

Returns the offset parent element of the given html element or nil if the element does not have any offset parent.

See https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/offsetParent for more details.

options clj

(options element)

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

outer-html clj

(outer-html element)

Returns the outer HTML of the given element in a hiccup. form. Comments use :-#comment tag and CDATA nodes will use :-#data tag.

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

parent clj

(parent element)

Returns the parent element of the given html element or nil if the element does not have any parent.

See https://developer.mozilla.org/en-US/docs/Web/API/Node/parentElement for more details.

press clj

(press key)

(press key opts)

Simulates a 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 the desired key code (event.code) for the pressed key. The complete list of the 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 a 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
        :when <predicate> ; optional - predicate function for extra conditions that the queried elements must satisfy
        :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 will be nil. If results are expected, use cuic.core/query in conjunction with cuic.core/wait, for example:

(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 of 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 the viewport if it is not in the view already. Waits cuic.core/*timeout* until the element becomes visible or throws an exception if the timeout exceeds.

Returns the target element for threading.

select clj

(select element option-or-options)

Selects the given option or options (strings) from the given element. The element must be a html select or otherwise an exception will be thrown. If element is not in the viewport, 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.

In a case of single option, provide the selected option as a string. In a case of multiple options, provide the selected options as a sequence of strings.

Returns the target element for threading.

;; Select single option
(c/select my-html-select "foo")

;; Select multiple options
(c/select my-html-multiselect ["foo" "bar"])

select-all-text clj

(select-all-text element)

First scrolls the given element into the viewport (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 the 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 a :speed option to the invocation.

Note that this function is quite low level and it does not focus the typed text on 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 opts)

Macro that waits until the given expression yields a truthy value. If the expression does not yield a thruthy value within a certain time, throws a timeout exception. Uses cuic.core/*timeout* by default but the timeout value can be overrided by providing it as an option.

Attention: the waited expression may be invoked multiple times so it should not contain any side effects!

Supported options are:

• :timeout - integer value of milliseconds until wait timeouts, use zero to disable timeout entirely
• :message - custom error message to display in case of timeout. Can be either string or zero-arity function that gets called when the timeout occurs.

;; Wait using defaults
(c/wait (= 2 (get-num-result-rows)))

;; Wait using custom 1 sec timeout
(c/wait (= 2 (get-num-result-rows)) {:timeout 1000})

;; Wait using custom error message
(c/wait (= 2 (get-num-result-rows)) {:message "Result rows not matching"})

;; Wait using dynamic custom error message
(c/wait (= 2 (get-num-result-rows)) {:message #(format "Expected 2 rows but got %d" (get-num-result-rows))})

window clj

(window)

(window browser)

Returns the JavaScript window object for the current default browser. Note that window can't be used as the query scope. For query scopes, use cuic.core/document instead.

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