Refactoring tests using builder functions in Clojure/ClojureScript

Using literals in your tests can have some advantages, such as, readability and traceability.

While this is true when the data are simple, it's less so when the data are nested, complex structures. In that case, using literals can hinder refactoring and thus become an obstacle to adapting to changes.

The problem with using literals for complex, nested data is that the knowledge about how to build such data is spread all over the tests. There are many tests that know about the representation of the data.

In that scenario, nearly any change in the representation of those data will have a big impact on the tests code because it will force us to change many tests.

This is an example of a test using literals, (from a ClojureScript application using re-frame, I'm developing with Francesc), to prepare the application state (usually called db in re-frame):

	(deftest test-right-and-wrong-word-handlers
	(let [co-fx {:db
	{:language :catalan
	:words-in-use {:current-word {:correct-word "ess"
	:answer-ts :any-ts
	:parts [(text/make "e")
	(tests-helpers/answered-gap "ss" [] 1 "ss")]}
	:current-word-index 1
	:visited-words {}
	:words {"first-word" {}
	"current-word" {:description "current-word"
	:parts ["e"
	{:correct-answer "ss"
	:options ["c", "ç", "k", "s", "ss", "z", "q"]}]}
	"next-word" {:description "next-word"
	:parts ["e"
	{:correct-answer "ss"
	:options ["c", "ç", "k", "s", "ss", "z", "q"]}]}}
	:words-keys ["first-word" "current-word" "next-word"]}}}]
	(testing "that right word handler selects the next word"
	(check-current-word-is-new
	(answer-handlers/right-word-handler co-fx :no-event)
	:description "next-word" :current-word-index 2))
	(testing "that wrong word handler repeats the same word"
	(check-current-word-is-new
	(answer-handlers/wrong-word-handler co-fx :no-event)
	:description "current-word" :current-word-index 1))))

view raw using-literals.cljs hosted with ❤ by GitHub

As you can see, this test knows to much about the structure of db.

There were many other tests doing something similar at some nesting level of the db.

To make things worse, at that moment, we were still learning a lot about the domain, so the structure of the db was suffering changes with every new thing we learned.

The situation was starting to be painful, since any refactoring provoke many changes in the tests, so we decided to fix it.

What we wanted was a way to place all the knowledge about the representation of the db in just one place (i.e., remove duplication), so that, in case we needed to change that representation, the impact of the change would be absorbed by changing only one place.

A nice way of achieving this goal in object-oriented code, and at the same time making your tests code more readable, is by using test data builders which use the builder pattern, but how can we do these builders in Clojure?

Option maps or function with keyword arguments are a nice alternative to traditional builders in dynamic languages such as Ruby or Python.

In Clojure we can compose functions with keyword arguments to get very readable builders that also hide the representation of the data.

We did TDD to write these builder functions. These are the tests for one of them, the db builder:

	(ns visual-spelling.test-helpers.db-builder-test
	(:require
	[cljs.test :refer-macros [deftest testing is]]
	[visual-spelling.test-helpers.db-helpers :as db-helpers]
	[visual-spelling.test-helpers.db-builder :refer [make-db]]
	[visual-spelling.db :as db]))
	(deftest test-db-builder
	(is (= (make-db) db/default-db))
	(is (= (make-db :results :some-results)
	(assoc db/default-db :results :some-results)))
	(is (= (make-db :language :some-language)
	(assoc db/default-db :language :some-language)))
	(let [db (make-db :words {:some-word {} :another-word {}})]
	(is (= (db-helpers/extract-from-db db :words)
	{:some-word {} :another-word {}}))
	(is (= (set (db-helpers/extract-from-db db :words-keys))
	(set [:some-word :another-word]))))
	(is (= (db-helpers/extract-from-db
	(make-db :current-word-index :some-index) :current-word-index)
	:some-index))
	(is (= (db-helpers/extract-from-db
	(make-db :current-word :some-word) :current-word)
	:some-word))
	(is (= (make-db :words-in-use :some-words-in-use)
	(assoc db/default-db :words-in-use :some-words-in-use)))
	(is (= (make-db :words-per-session :some-words-per-session)
	(assoc db/default-db :words-per-session :some-words-per-session)))
	(is (= (make-db :visited-words :some-:visited-words)
	(assoc db/default-db :visited-words :some-:visited-words))))

view raw db_builder_test.cljs hosted with ❤ by GitHub

and this is the db builder code:

	(ns visual-spelling.test-helpers.db-builder
	(:require
	[visual-spelling.db :as db]))
	(defn- property-used? [v]
	(not= v ::not-used))
	(defn- assoc-if-used [m k v]
	(if (property-used? v)
	(assoc m k v)
	m))
	(defn make-words-in-use
	[default-word-in-use words-in-use words current-word-index current-word]
	(let [words-keys (if (property-used? words) (keys words) ::not-used)]
	(if (property-used? words-in-use)
	words-in-use
	(-> default-word-in-use
	(assoc-if-used :words-keys words-keys)
	(assoc-if-used :words words)
	(assoc-if-used :current-word-index current-word-index)
	(assoc-if-used :current-word current-word)))))
	(defn make-db
	[& {:keys [language words current-word-index current-word
	visited-words results words-in-use words-per-session]
	:or {language ::not-used
	words ::not-used
	current-word-index ::not-used
	current-word ::not-used
	visited-words ::not-used
	results ::not-used
	words-in-use ::not-used
	words-per-session ::not-used}}]
	(let [words-in-use (make-words-in-use
	(:words-in-use db/default-db)
	words-in-use
	words current-word-index current-word)]
	(-> db/default-db
	(assoc :words-in-use words-in-use)
	(assoc-if-used :language language)
	(assoc-if-used :results results)
	(assoc-if-used :words-per-session words-per-session)
	(assoc-if-used :visited-words visited-words))))

view raw db_builder.cljs hosted with ❤ by GitHub

which is using associative destructuring on the function's optional arguments to have a function with keyword arguments, and creating proper default values using the :or keyword (have a look at the material of a talk about destructuring I did some time ago for Clojure Barcelona Developers community).

After creating builder functions for some other data used in the project, our test started to read better and to be robust against changes in the structure of db.

For instance, this is the code of the test I showed at the beginning of the post, but now using builder functions instead of literals:

	(deftest test-right-and-wrong-word-handlers
	(let [db (make-db
	:language :catalan
	:current-word (make-word
	:correct-word "ess"
	:answer-ts :any-ts
	:parts (parts "e"
	{:correct-answer "ss"
	:user-answer "ss"}))
	:current-word-index 1
	:words {"first-word" (make-raw-word)
	"current-word" (make-raw-word
	:description "current-word"
	:parts (raw-parts
	"e"
	{:correct-answer "ss"
	:options ["c", "ç", "k", "s", "ss", "z", "q"]}))
	"next-word" (make-raw-word
	:description "next-word"
	:parts (raw-parts
	"e"
	{:correct-answer "ss"
	:options ["c", "ç", "k", "s", "ss", "z", "q"]}))})
	co-fx {:db db}]
	(testing "that right word handler selects the next word"
	(check-current-word-is-new
	(right-word-handler co-fx :no-event) :description "next-word" :current-word-index 2))
	(testing "that wrong word handler repeats the same word"
	(check-current-word-is-new
	(wrong-word-handler co-fx :no-event) :description "current-word" :current-word-index 1))))

view raw using-builders.cljs hosted with ❤ by GitHub

which not only hides the representation of db but also eliminates details that are not used in particular tests, while still being as easy to read, if not easier, than the version using literals.

We have seen how, by composing builder functions and using them in our tests, we managed to reduce the surface of the impact that changes in the representation of data might have on our tests. Builder functions absorb the impact of those changes, and enable faster refactoring, and, by doing so, enable adapting to changes faster.