Testing Om components with cljs-react-test

I'm working for Green Power Monitor which is a company based in Barcelona specialized in monitoring renewable energy power plants and with clients all over the world.

We're developing a new application to monitor and manage renewable energy portfolios. I'm part of the front-end team. We're working on a challenging SPA that includes a large quantity of data visualization and which should present that data in an UI that is polished and easy to look at. We are using ClojureScript with Om (a ClojureScript interface to React) which are helping us be very productive.

I’d like to show an example in which we are testing an Om component that is used to select a command from several options, such as, loading stored filtering and grouping criteria for alerts (views), saving the current view, deleting an already saved view or going back to the default view.

This control will send a different message through a core.async channel depending on the selected command. This is the behavior we are going to test in this example, that the right message is sent through the channel for each selected command. We try to write all our components following this guideline of communicating with the rest of the application by sending data through core.async channels. Using channels makes testing much easier because the control doesn’t know anything about its context

We’re using cljs-react-test to test these Om components as a black box. cljs-react-test is a ClojureScript wrapper around Reacts Test Utilities which provides functions that allow us to mount and unmount controls in test fixtures, and interact with controls simulating events.

This is the code of the test:

	(ns horizon.controls.widgets.views-selector-tests.views-selector-test
	(:require
	[cljs.test :refer-macros [deftest testing is use-fixtures async]]
	[sablono.core :as sab :include-macros true]
	[cljs-react-test.utils :as tu]
	[cljs-react-test.simulate :as sim]
	[cljs.core.async :as core.async]
	[om.core :as om :include-macros true]
	[horizon.controls.widgets.comboboxes.views-selector :as views-selector]
	[horizon.common.messaging.core :as m]
	[horizon.test-helpers.async-test-tools :as async-test-tools]
	[horizon.test-doubles.core :as td :include-macros true]
	[horizon.common.logging :as log]
	[horizon.test-helpers.dom-selection :as dom-selection]))
	(def ^:private ^:dynamic c)
	(use-fixtures :each
	{:before #(async done
	(set! c (tu/new-container!))
	(done))
	:after #(do
	(td/with-doubles
	:ignoring [m/unsubscribe]
	(tu/unmount! c)))})
	(def ^:private possible-views-options
	[{:Id :view1 :Name "Custom View 1"}
	{:Id :view2 :Name "Custom View 2"}])
	(defn- mount-component-on-root
	[root-container combo-id-num app-state ui-events-channel commands-channel]
	(td/with-doubles
	:ignoring [log/debug]
	(om/root
	(fn [data owner]
	(reify
	om/IRenderState
	(render-state [_ _]
	(sab/html
	[:div
	(om/build
	views-selector/views-combobox
	data
	{:opts {:channels {:ui-events-channel ui-events-channel
	:commands-channel commands-channel}
	:generate-id-fn (constantly combo-id-num)}
	:init-state {:expanded true
	:value {:selected (:selected @app-state)}}})]))))
	app-state
	{:target root-container})))
	(deftest selecting-save-current-view-action
	(let [ui-events-channel (core.async/chan)
	commands-channel (core.async/chan)
	app-state (atom {:pre-label "Select view:"
	:views-options possible-views-options
	:selected -1})]
	(mount-component-on-root
	c 100 app-state ui-events-channel commands-channel)
	(async
	done
	(async-test-tools/expect-async-message
	commands-channel
	:done-fn done
	:expected-message {:type :command
	:payload {:command :show-custom-view
	:Id :view1}})
	(sim/click (dom-selection/nth-li c 2) {}))))
	(deftest selecting-showing-first-custom-view-action
	(let [ui-events-channel (core.async/chan)
	commands-channel (core.async/chan)
	app-state (atom {:pre-label "Select view:"
	:views-options possible-views-options
	:selected -1})]
	(mount-component-on-root
	c 100 app-state ui-events-channel commands-channel)
	(async
	done
	(async-test-tools/expect-async-message
	commands-channel
	:done-fn done
	:expected-message {:type :command
	:payload {:command :save-current-view}})
	(sim/click (dom-selection/nth-li c 4) {}))))
	(deftest deleting-view-action
	(let [ui-events-channel (core.async/chan)
	commands-channel (core.async/chan)
	app-state (atom {:pre-label "Select view:"
	:views-options possible-views-options
	:selected -1})]
	(mount-component-on-root
	c 100 app-state ui-events-channel commands-channel)
	(async
	done
	(async-test-tools/expect-async-message
	commands-channel
	:done-fn done
	:expected-message {:type :command
	:payload {:command :delete-custom-view
	:Id :view2}})
	(sim/click (second (dom-selection/elements-of-class c "delete")) {}))))

view raw views_selector_test.cljs hosted with ❤ by GitHub

We start by creating a var where we’ll put a DOM object that will act as container for our application, c.

We use a fixture function that creates this container before each test and tears down React's rendering tree, after each test. Notice that the fixture uses the async macro so it can be used for asynchronous tests. If your tests are not asynchronous, use the simpler fixture example that appears in cljs-react-test documentation.

All the tests follow this structure:

1. Setting up the initial state in an atom, app-state. This atom contains the data that will be passed to the control.
2. Mounting the Om root on the container. Notice that the combobox is already expanded to save a click.
3. Declaring what we expect to receive from the commands-channel using expect-async-message.
4. Finally, selecting the option we want from the combobox, and clicking on it.

expect-async-message is one of several functions we’re using to assert what to receive through core.async channels:

	(ns horizon.test-helpers.async-test-tools
	(:require
	[cljs.test :refer-macros [is]]
	[cljs.core.async :as core.async])
	(:require-macros
	[cljs.core.async.macros :refer [go go-loop]]))
	(def ^:private timeout-in-ms 2000)
	(defn- channel-timed-out-error [received-messages]
	(ex-info
	"Channel timed out!!!"
	{:cause :channel-timeout
	:received-messages received-messages}))
	(defn- maybe-exclude-keys [x ks]
	(if (and (map? x) ks)
	(apply dissoc x ks)
	x))
	(defn- invoke! [f]
	{:pre [(if f (ifn? f) true)]}
	(when f
	(f)))
	(defn- check-result
	[& {:keys [expected result done-fn excluding-keys] :as options}]
	{:pre [(every? #{:expected :result :done-fn :excluding-keys}
	(keys options))
	(if done-fn (ifn? done-fn) true)]}
	(let [expected (maybe-exclude-keys expected excluding-keys)
	result (maybe-exclude-keys result excluding-keys)]
	(try
	(is (= expected result))
	(finally
	(invoke! done-fn)))))
	(defn check-results
	[& {:keys [expected result done-fn excluding-keys] :as options}]
	{:pre [(every? #{:expected :result :done-fn :excluding-keys}
	(keys options))
	(if done-fn (ifn? done-fn) true)]}
	(try
	(mapv #(check-result :expected %1
	:result %2
	:excluding-keys excluding-keys)
	expected
	result)
	(finally
	(invoke! done-fn))))
	(defn- fail-because-of-timeout
	[expected-message received-messages done-fn]
	(check-result :expected expected-message
	:result (channel-timed-out-error received-messages)
	:done-fn done-fn))
	(defn expect-async-message
	[channel & {:keys [expected-message done-fn excluding-keys]}]
	{:pre [expected-message (if done-fn (ifn? done-fn) true)]}
	(go
	(let [[message ch] (core.async/alts!
	[channel (core.async/timeout timeout-in-ms)])]
	(if (= ch channel)
	(check-result :expected expected-message
	:result message
	:done-fn done-fn
	:excluding-keys excluding-keys)
	(fail-because-of-timeout expected-message [] done-fn)))))
	(defn expect-async-message-with-specific-type
	[channel & {:keys [expected-message-type expected-message done-fn excluding-keys]}]
	{:pre [expected-message expected-message-type (if done-fn (ifn? done-fn) true)]}
	(go-loop [received-messages []]
	(let [[message ch] (core.async/alts!
	[channel (core.async/timeout timeout-in-ms)])]
	(if (= ch channel)
	(if (= expected-message-type (:type message))
	(check-result :expected expected-message
	:result message
	:done-fn done-fn
	:excluding-keys excluding-keys)
	(recur (conj received-messages message)))
	(fail-because-of-timeout expected-message received-messages done-fn)))))
	(defn expect-n-async-messages
	[channel & {:keys [expected-messages done-fn excluding-keys]}]
	{:pre [(sequential? expected-messages) (if done-fn (ifn? done-fn) true)]}
	(go-loop [received-messages []]
	(let [[message ch] (core.async/alts!
	[channel (core.async/timeout timeout-in-ms)])
	total (count expected-messages)]
	(if (= ch channel)
	(let [received-messages (conj received-messages message)]
	(if (= total (count received-messages))
	(check-results :expected expected-messages
	:result received-messages
	:done-fn done-fn
	:excluding-keys excluding-keys)
	(recur received-messages)))
	(fail-because-of-timeout expected-messages received-messages done-fn)))))
	(defn async-used-fn [channel func-kw]
	(fn [& args]
	(go
	(core.async/>! channel {:used func-kw :with-args (vec args)}))))
	(defn send-fake-msg! [channel msg]
	(go
	(core.async/>! channel msg)))
	(defn expect-event-handler-receives-args
	[& {:keys [event channel expected-args done-fn close-fn]}]
	{:pre [event
	channel
	expected-args
	(if done-fn (ifn? done-fn) true)
	(if close-fn (ifn? close-fn) true)]}
	(let [events-channel (core.async/chan)
	close-and-done-fn (fn []
	(when close-fn (close-fn channel))
	(when done-fn (done-fn channel)))]
	(event
	channel
	(fn [& args]
	(go
	(core.async/>! events-channel args))))
	(go
	(let [[args ch] (core.async/alts!
	[events-channel (core.async/timeout timeout-in-ms)])]
	(if (= ch events-channel)
	(check-result
	:expected expected-args :result args :done-fn close-and-done-fn)
	(fail-because-of-timeout
	expected-args :never-called close-and-done-fn))))))

view raw async-test-tools.cljs hosted with ❤ by GitHub

The good thing about this kind of black-box tests is that they interact with controls as the user would do it, so the tests know nearly nothing about how the control is implemented.