cuic.test — cuic 0.6.0-20201124.1

Utilities for writing concise and robust UI tests.

Example usage:

(ns todomvc-tests
  (:require [clojure.test :refer :all]
            [cuic.core :as c]
            [cuic.test :refer [deftest* is* browser-test-fixture]]))

(use-fixtures
  :once
  (browser-test-fixture))

(defn todos []
  (->> (c/query ".todo-list li")
       (map c/text-content)))

(defn add-todo [text]
  (doto (c/find ".new-todo")
    (c/fill text))
  (c/press 'Enter))

(deftest* creating-new-todos
  (c/goto "http://todomvc.com/examples/react")
  (is* (= [] (todos)))
  (add-todo "Hello world!")
  (is* (= ["Hello world!"] (todos)))
  (add-todo "Tsers!")
  (is* (= ["Hello world!" "Tsers!"] (todos))))

*abort-immediately* clj

Controls the behaviour of immediate test abort in case of cuic.test/is* failure. Setting this value to false means that test run continues even if is* assertion fails (reflects the behaviour of the standard clojure.test/is).

;; Run the whole test regardless of is* failures
(use-fixtures
  :once
  (fn [t]
    (binding [*abort-immediately* false]
      (t))))

*screenshot-options* clj

Options that cuic.test/deftest* will use for screenshots that are taken from failed tests. Accepts all options accepted by [[cuic.core/screenhot]] plus :dir (java.io.File instance) defining directory, where the taken screenshots will be saved.

;; Store taken screenshots under $PWD/__screenshots__ directory
(use-fixtures
  :once
  (fn [t]
    (binding [*screenshot-options* (assoc *screenshot-options* :dir (io/file "__screenshots__"))]
      (t))))

browser-test-fixture clj

(browser-test-fixture)

(browser-test-fixture {:keys [headless options]
                       :or {headless (not= "false"
                                           (System/getProperty "cuic.headless"))
                            options {}}})

Convenience test fixture for UI tests. Launches single Chrome instance and setups it as the default browser for cuic.core functions.

Browser's headless mode is controlled either directly by the given options or indirectly by the cuic.headless system property. If you're developing tests with REPL, you probably want to set {:jvm-opts ["-Dcuic.headless=false"]} to your REPL profile so that tests are run from REPL are using non-headless mode but still using headless when run in CI.

This fixture covers only the basic cases. For more complex test setups, you probably want to write your own test fixture.

See namespace documentation for a complete usage example.

deftest* clj macro

(deftest* name & body)

Cuic's counterpart for clojure.test/deftest. Must be used if your test contains cuic.test/is* assertions. Works identically to deftest but stops gracefully if test gets aborted due to an assertion failure in cuic.test/is*, assuming that cuic.test/*abort-immediately* is set to true.

See namespace documentation for a complete usage example.

is* clj macro

(is* form)

Basically a shortcut for (is (c/wait <cond>)) but with some improvements to error reporting. Can be used only inside tests defined with cuic.test/deftest*. See namespace documentation for a complete usage example.

If the tested expression does not yield truthy value within the current cuic.core/*timeout*, a assertion failure will be reported using the standard clojure.test reporting mechanism. However, the difference between (is (c/wait <cond>)) and (is* <cond>) is that former reports the failure from (c/wait <cond>) whereas the latter reports the failure from <cond> which will produce much better error messages and diffs when using custom test reporters such as eftest or Cursive's test runner.

Because of the nature of UI tests, first assertion failure will usually indicate the failure of the remaining assertions as well. If each of these assertions wait the timeout before giving up, the test run might prolong quite a bit. That's why is* aborts the current test run immediately after first failed assertion. This behaviour can be changed by setting cuic.test/*abort-immediately* to false in the surrounding scope with binding or globally with cuic.test/set-abort-immediately!.

For experts only: if you are writing a custom test reporter and want to hook into cuic internals, is* provides the following report types:

;; (is* expr) timeout occurred
{:type    :cuic/timeout
 :message <string>   ; error message of the timeout exception
 :expr    <any>      ; sexpr of the failed form
 }

;; Screenshot was time form the current browser
{:type     :cuic/screenshot-taken
 :filename <string>  ; absolute path to the saved screenshot file
 }

;; Screenshot was failed for some reason
{:type  :cuic/screenshot-failed
 :cause <throwable>   ; reason for failure
 }

;; Test run was aborted
{:type :cuic/test-aborted
 :test <symbol>    ; aborted test fully qualified name
 :form <any>       ; sexpr of the form causing the abort
 }

set-abort-immediately! clj

(set-abort-immediately! abort?)

Globally resets the test abort behaviour. Useful for example REPL usage. See cuic.test/*abort-immediately* for more details.

set-screenshot-options! clj

(set-screenshot-options! opts)

Globally resets the default screenshot options. Useful for example REPL usage. See cuic.test/*screenshot-options* for more details.