cljs-test-runner

Run all of your ClojureScript tests with one simple command.

Inspired by Cognitect's test-runner for Clojure, it is designed to be used in conjunction with the Clojure CLI tool and a deps.edn file.

Under the hood it's building a test runner file, compiling everything and then executing the compiled tests with doo (using ingesolvoll's fork). Discovery of test namespaces is automatic, so no configuration is required.

Usage

In simple cases, you'll be able to execute your tests with something as succinct as the following line.

$ clojure -Sdeps '{:deps {olical/cljs-test-runner {:mvn/version "3.8.1"}}}' -m cljs-test-runner.main

Note: The generated test code is placed in the directory cljs-test-runner-out by default (configure with --out), you should add that to your .gitignore file.

It's likely that your tests will require dependencies and configuration that would become unwieldy in this format. You will need to add the dependency and --main (-m) parameter to your deps.edn file.

I recommend you put this under an alias such as test or cljs-test if that's already taken by your Clojure tests.

{:deps {org.clojure/clojure {:mvn/version "1.10.1"}
        org.clojure/clojurescript {:mvn/version "1.10.520"}}
 :aliases {:test {:extra-deps {olical/cljs-test-runner {:mvn/version "3.8.1"}}
                  :main-opts ["-m" "cljs-test-runner.main"]}}}

The following will then find, compile and execute your tests through node.

$ clojure -Atest

Testing example.partial-test

Testing example.yes-test

Ran 2 tests containing 2 assertions.
0 failures, 0 errors.

Configuration

You can configure the test runner with a few different flags, the most important one is --env (-x) which allows you to swap from node to phantom or chrome-headless if required. I would recommend sticking to node and using something like jsdom, but this does come down to preference and technical requirements.

$ clojure -Atest -x phantom

If you need to use foreign-libs or any cljs compiler flags that are not mirrored in cljs-test-runner's flags, you can put them into an EDN file and point to that file using the --compile-opts flag.

You can use --help to see the current flags and their default values.

$ clojure -Atest --help
  -d, --dir DIRNAME            test                  The directory containing your test files
  -n, --namespace SYMBOL                             Symbol indicating a specific namespace to test.
  -r, --namespace-regex REGEX  .*\-test$             Regex for namespaces to test. Only namespaces ending in '-test' are evaluated by default.
  -v, --var SYMBOL                                   Symbol indicating the fully qualified name of a specific test.
  -i, --include SYMBOL                               Run only tests that have this metadata keyword.
  -e, --exclude SYMBOL                               Exclude tests with this metadata keyword.
  -o, --out DIRNAME            cljs-test-runner-out  The output directory for compiled test code
  -x, --env ENV                node                  Run your tests in node, phantom, chrome-headless, lumo or planck.
  -w, --watch DIRNAME                                Directory to watch for changes (alongside the test directory). May be repeated.
  -c, --compile-opts PATH                            EDN file containing opts to be passed to the ClojureScript compiler.
  -D, --doo-opts PATH                                EDN file containing opts to be passed to doo.
  -V, --verbose                                      Flag passed directly to the ClojureScript compiler to enable verbose compiler output.
  -H, --help

Advanced compilation

To use Closure Compiler advanced optimisation levels you will need to create an EDN file like this:

{:optimizations :advanced}

Now when you run the following, your tests will be executed with advanced compilation:

clj -m cljs-test-runner.main -c ./config/advanced-compilation.edn

You can also directly inline the EDN using the -c flag:

clj -m cljs-test-runner.main -c '{:optimizations :advanced}'

There is a known issue with :whitespace, I just haven't invested the time into working out what it is. For now, stick to :none, :simple or :advanced, the original issue for optimisation levels breaking things is #16.

Bundle target

The new bundle target requires a 2-step process for compilation. One for building an index.js consumable by bundlers like webpack, and a second step for actually running the bundler. This requires you to specify 2 different targets.

In essence, this requires you to include the following in your doo.edn:

{:output-to "resources/public/js/main.js"}

Your CLJS compiler options should be according to the standard guide.

Gotchas

Paths

Make sure the directory (or directories!) containing your tests are on your Java class path. Specify this with a top level :paths key in your deps.edn file.

Lumo / Planck

To use Lumo or Planck, add the generated test runner to the :paths in your deps.edn:

:paths ["src" "test" "cljs-test-runner-out/gen"]

and set the environment:

-x lumo

or

-x planck

Unlicenced

Find the full unlicense in the UNLICENSE file, but here's a snippet.

This is free and unencumbered software released into the public domain.

Anyone is free to copy, modify, publish, use, compile, sell, or distribute this software, either in source code form or as a compiled binary, for any purpose, commercial or non-commercial, and by any means.

Do what you want. Learn as much as you can. Unlicense more software.