Liking cljdoc? Tell your friends :D

2. Installing

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

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.732"}}}' -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 { ,,, }
 {:test {:extra-deps {lambdaisland/kaocha {:mvn/version "1.0.732"}}}}}

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 its 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


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.732"]]}}
  :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.732"]]}}
  :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.


See kaocha-boot for instructions.

Can you improve this documentation? These fine people already did:
Arne Brasseur, Alys Brooks & José Luis Lafuente
Edit on GitHub

cljdoc is a website building & hosting documentation for Clojure/Script libraries

× close