Need help with kaocha?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

622 Stars 63 Forks Eclipse Public License 1.0 980 Commits 48 Opened issues


Full featured next gen Clojure test runner

Services available


Need anything else?

Contributors list

Full featured next generation test runner for Clojure.

Jump to Quick start | Docs


| Project | CI | Docs | Release | Coverage | |---------|----|------|---------|----------| | kaocha | CircleCI | cljdoc badge | Clojars Project | codecov | | kaocha-cljs | CircleCI | cljdoc badge | Clojars Project | codecov | | kaocha-cucumber | CircleCI | cljdoc badge | Clojars Project | codecov | | kaocha-junit-xml | CircleCI | cljdoc badge | Clojars Project | codecov | | kaocha-cloverage | CircleCI | cljdoc badge | Clojars Project | codecov | | kaocha-boot | CircleCI | cljdoc badge | Clojars Project | codecov | | deep-diff | CircleCI | cljdoc badge | Clojars Project | codecov | <!-- /projects -->

考察 [kǎo chá]

  • to inspect
  • to observe and study
  • on-the-spot investigation

See the Line Dict entry for an audio sample.

Need help?

Are you

There is also a #kaocha channel on Clojurians Slack (sign up here), where users can help each other.



Features include

  • Filtering tests based on test names or metadata
  • Watch mode: watch the file system for changes and re-run tests
  • Pretty, pluggable reporting
  • Randomize test order
  • Detect when interrupted with ctrl-C and print report
  • Fail fast mode: stop at first failure and print report
  • Profiling (show slowest tests)
  • Dynamic classpath handling
  • Tests as data (get test config, test plan, or test results as EDN)
  • Extensible test types (clojure.test, Midje, ...)
  • Extensible through plugins
  • Tool agnostic (Clojure CLI, Leiningen, ...)

Quick start

This is no replacement for reading the docs, but if you're particularly impatient to try it out, or if you already know Kaocha and need a quick reference how to set up a new project, then this guide is for you.

Clojure CLI (tools.deps)

Add Kaocha as a dependency, preferably under an alias.

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

Add a binstub called

mkdir -p bin
echo '#!/usr/bin/env sh' > bin/kaocha
echo 'clojure -A:test -m kaocha.runner "[email protected]"' >> bin/kaocha
chmod +x bin/kaocha


Add a profile and alias

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

Add a binstub called

mkdir -p bin
echo '#!/usr/bin/env sh' > bin/kaocha
echo 'lein kaocha "[email protected]"' >> bin/kaocha
chmod +x bin/kaocha


In your

add the Kaocha dependency, and import the Kaocha task
;; build.boot
(set-env! :source-paths #{"src"}
          :dependencies '[[lambdaisland/kaocha-boot "..."]])

(require '[kaocha.boot-task :refer [kaocha]])

Add a binstub called

mkdir -p bin
echo '#!/usr/bin/env sh' > bin/kaocha
echo 'boot kaocha "[email protected]"' >> bin/kaocha
chmod +x bin/kaocha

Clojure CLI (tools.deps) :exec-fn alternative

We also support using the Clojure CLI

. However, we recommend the binstub approach above because it allows you to use traditional long and short options. If you nonetheless prefer
, you can set up
;; deps.edn
{:deps { ,,, }
 {:test {:extra-deps {lambdaisland/kaocha {:mvn/version "1.60.977"}}
         :exec-fn kaocha.runner/exec-fn
         :exec-args {}}}}

And then Kaocha can be invoked this way:

clojure -X:test

Generally speaking, we recommend using

for all of your configuration rather than putting it in
unless there's an alternative combination of options you frequently run.

In that case, you can put configuration options

as though it were
. Let's say you frequently use watch with
and a subset of tests skipped. You could save that configuration with an additional alias:
clojure -X:watch-test
like so:
;; deps.edn
{:deps { ,,, }
 {:test {:extra-deps {lambdaisland/kaocha {:mvn/version "1.60.977"}}
         :exec-fn kaocha.runner/exec-fn
         :exec-args {}}
 :watch-test {:extra-deps {lambdaisland/kaocha {:mvn/version "1.60.977"}}
         :exec-fn kaocha.runner/exec-fn
         :exec-args {:watch? true
     :skip-meta :slow
     :fail-fast? true }}}}

If you wanted to turn off

temporarily, you could run
-X:watch-test :fail-fast? false

All tools

By default, Kaocha assumes that: - source files are in the

folder, - test files are in the
folder, - all test namespaces names end with
). Also, the default test suite id is
on the command line).

If your tests don't seem to run (outcome is

0 tests, 0 assertions, 0 failures
) you may need to write up your own configuration: add a
at the root of the project to configure actual test and source paths, and optionally set a reporter or load plugins (cf. Configuration in the documentation).

Example of a catch-all

config file (should run all tests found in
, in any namespace). ``` clojure


{:tests [{:id :unit :test-paths ["test" "src"] :ns-patterns [".*"]}] ;; :reporter ;; :plugins [:kaocha.plugin/profiling :kaocha.plugin/notifier] } ``` Warning: this is not an optimal configuration. To avoid extra churn, you should try and target only folders and namespaces that actually contain tests.

Run your tests


Watch for changes

bin/kaocha --watch

Exit at first failure

bin/kaocha --fail-fast

Only run the unit suite

bin/kaocha unit

Only run a single test

bin/kaocha --focus

Use an alternative config file

bin/kaocha --config-file tests_ci.edn

See all available options

bin/kaocha --test-help

Third party projects

  • kaocha-noyoda Don't speak like Yoda, write
    (is (= actual expected))
    instead of
    (is (= expected actual))


Kaocha requires Clojure 1.9 or later.



Support Lambda Island Open Source

kaocha is part of a growing collection of quality Clojure libraries and tools released on the Lambda Island label. If you are using this project commercially then you are expected to pay it forward by becoming a backer on Open Collective, so that we may continue to enjoy a thriving Clojure ecosystem.




Everyone has a right to submit patches to kaocha, and thus become a contributor.

Contributors MUST

  • adhere to the LambdaIsland Clojure Style Guide
  • write patches that solve a problem. Start by stating the problem, then supply a minimal solution.
  • agree to license their contributions as EPL 1.0.
  • not break the contract with downstream consumers.
  • not break the tests.

Contributors SHOULD

  • update the CHANGELOG and README.
  • add tests for new functionality.

If you submit a pull request that adheres to these rules, then it will almost certainly be merged immediately. However some things may require more consideration. If you add new dependencies, or significantly increase the API surface, then we need to decide if these changes are in line with the project's goals. In this case you can start by writing a pitch, and collecting feedback on it.

This goes for features too, a feature needs to solve a problem. State the problem it solves, then supply a minimal solution.

As long as this project has not seen a public release (i.e. is not on Clojars) we may still consider making breaking changes, if there is consensus that the changes are justified. <!-- /contributing -->


Copyright © 2018-2021 Arne Brasseur and contributors

Available under the terms of the Eclipse Public License 1.0, see LICENSE.txt <!-- /license -->

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.