2. Installing

Kaocha is distributed through Clojars, with the identifier lambdaisland/kaocha. You can find version information for the latest release at https://clojars.org/lambdaisland/kaocha.

The main namespace for use at the command line is kaocha.runner, regardless of which tool you're using to invoke Clojure.

For example:

clojure -Sdeps '{:deps {lambdaisland/kaocha {:mvn/version "1.0.902"}}}' -m kaocha.runner --test-help

Below are instructions on the recommended way to set things up for various build tools.

Clojure CLI / deps.edn

In deps.edn, create a test "alias" (profile) that loads the lambdaisland/kaocha dependency.

;; deps.edn
{:deps { ,,, }
 :aliases
 {:test {:extra-deps {lambdaisland/kaocha {:mvn/version "1.0.902"}}}}}

Other dependencies that are only used for tests, like test framework or assertion libraries, can also go here.

Next create a bin/kaocha wrapper script. Having it in this location is strongly recommended, as it's where developers coming from other projects will expect to find it.

In it invoke clojure with the :test alias and the kaocha.runner main namespace. This is what bin/kaocha by default looks like. Make sure to add "$@" so that any arguments to bin/kaocha are passed on to kaocha.runner.

#!/usr/bin/env bash

clojure -A:test -m kaocha.runner "$@"

Make sure the script is executable:

chmod +x bin/kaocha

This script provides a useful place to encode extra flags or setup that is needed in order for tests to run correctly.

#!/usr/bin/env bash

. secrets.env
clojure -J-Xmx512m -A:dev:test -m kaocha.runner --config-file test/tests.edn "$@"

This version also sets an alternative location for Kaocha's configuration file: tests.edn. It is generally recommended to leave it at the root of the project, but if you do want to move or rename it this is the way to go.

--config-file is the only Kaocha option that makes sense in this script, other Kaocha configuration should be done through tests.edn.

Now you can invoke Kaocha as such:

bin/kaocha --version

Leiningen

Add Kaocha to your :dev profile, then add an alias that invokes lein run -m kaocha.runner:

(defproject my-proj "0.1.0"
  :dependencies [,,,]
  :profiles {:dev {:dependencies [,,, [lambdaisland/kaocha "1.0.902"]]}}
  :aliases {"kaocha" ["run" "-m" "kaocha.runner"]})

Now you can invoke Kaocha as such:

lein kaocha --version

It is still recommeded to create a bin/kaocha wrapper for consistency among projects. The rest of the documentation assumes you can invoke Kaocha with bin/kaocha.

#!/usr/bin/env bash

lein kaocha "$@"

For more information on :dev, see the Leiningen docs.

Alternative method: separate :kaocha profile

If you want to use Kaocha only in certain circumstances, say when profiling tests, you may not want to add it to your :dev profile.

Instead, add a :kaocha profile with the Kaocha dependency, then add an alias that activates the profile and invokes lein run -m kaocha.runner:

(defproject my-proj "0.1.0"
  :dependencies [,,,]
  :profiles {:kaocha {:dependencies [[lambdaisland/kaocha "1.0.902"]]}}
  :aliases {"kaocha" ["with-profile" "+kaocha" "run" "-m" "kaocha.runner"]})

Invoking Kaocha and creating bin/kaocha will work the same way. However, Kaocha will not be available in your REPL by default.

Boot

See kaocha-boot for instructions.