Testing with Planck
cljs.test namespace has been ported for use in Planck. In short, this means you can require this namespace and make use of it, just like you can do in regular JVM ClojureScript.
What's the big deal? Why did it need to be ported?
A lot of
cljs.test is macros, like
is, and one key aspect is that these macros call other macros in the
cljs.test namespace. While this is cool in Clojure, it is verboten in ClojureScript. This alone means one does not simply
(require 'cljs.test) in a bootstrap REPL. This can be solved, though, by constructing a macro tower.
Another problem is that some of the
cljs.test macros call upon Clojure code in the compiler. This is fortunately easily solved by porting this Clojure code over to ClojureScript and including it internally within Planck.
Also with the port, the
cljs.test/assert-expr mechanism was made directly accessible to ClojureScript runtime code. This is covered here.
All of this is built into the Planck 1.10 binary. There is nothing special you need to do other than to require the
cljs.test namespace and optionally
:refer-macros as you see fit.
Of course, the primary result of this is you can now write unit tests for any code you write for use with Planck. Things just work.
Another nice outcome is that Planck's own unit tests can now be written using
cljs.test. When Planck was first being developed, this wasn't possible. In fact, the first tests for Planck took on a rudimentary form: A shell script that ran forms through the Planck binary, recording standard out and err, and comparing the results against expected output using
diff. Painful, but workable. Then, later, it became possible to write unit tests using
cljs.test, but because of the macros issue, these tests had to be AOT compiled using JVM ClojureScript and baked into the Planck binary. This meant that to fix a test, you'd have to rebuild everything. Ugh. Now, unit tests for Planck can just be simply required and executed by Planck. They can be changed and dynamically reloaded and re-run. Nice.
And yet another consequence of having ported
cljs.test to Planck is that now, for the first time:
We can compile and run the ClojureScript compiler's
cljs.core namespace unit tests in bootstrapped mode.
Read that again if it didn't sink in. This is absolutely huge. It means we can be much more certain that bootstrapped ClojureScript behaves like JVM ClojureScript.
Here is what running the test suite in Planck looks like, elided for brevity:
Testing cljs.core-test Testing cljs.reader-test Testing clojure.string-test ... Testing cljs.import-test Ran 184 tests containing 17219 assertions. 0 failures, 0 errors.
Without this capability, the ClojureScript compiler does have a few unit tests specifically for the
cljs.js namespace, and it is used to exercise some things at a high level within Node in bootstrap mode. But it is nowhere near as comprehensive as being able to compile and run the thousands of assertions that have been written over the years for JVM ClojureScript. Having this capability also means that, as new fixes or features are made in the ClojureScript compiler codebase, Planck can help automatically catch any bootstrap regressions that might creep in—Planck runs all of the tests above in CircleCI whenever changes are committed to Planck.
I'm excited about all of this as it helps ensure that bootstrapped ClojureScript can be relied upon and it also helps you easily write tests for any scripts you might write for use with Planck.