If you followed the installation instructions, you
should have a
bin/kaocha wrapper ("binstub") in your project that accepts
The command line runner takes the names of test suites to run, as well as a
number of flags and options. If you don't give it any suite names it runs all
You can get an overview of all available flags with
Kaocha relies on a
tests.edn configuration file, see the section on
configuration. To load an alternative configuration, use
bin/kaocha --config-file tests_ci.edn
Note that plugins specified in the config file will influence the available
command line options.
--plugin option lets you activate additional plugins, it is followed by
the plugin's name, a namespaced symbol. This option can be specified multiple
--reporter you can specify an alternative reporter, to change Kaocha's
For example, to see a colorful progress bar, use
bin/kaocha --reporter kaocha.report.progress/report
Plugins in the
kaocha.plugin namespace, and reporters in the
namespace can be specified without the namespace.
bin/kaocha --plugin profiling --reporter documentation
Stop the test run as soon as a single assertion fails or an exception is thrown,
and then print the results so far.
Kaocha by default randomizes the order that tests are run: it picks a random
seed, and uses that to re-order the test suites, namespaces, and test vars.
Tests should be independent, but this is not always the case. This random order
helps to track down unintended dependencies between tests.
The random seed will be printed at the start of the test run. On the same code
base with the same seed you will always get the same test order. This way you
can, e.g., reproduce a test run that failed on a build server.
bin/kaocha --seed 10761431
--no-randomize to load suites in the order they are specified, and vars in
the order they occur in the source. You can disable randomization in
Kaocha makes liberal use of ANSI escape codes for colorizing the output. If you
prefer or need plain text output use
By default Kaocha will capture any output that occurs on stdout or stderr during
a test run. Only when a test fails is the captured output printed as part of the
test result summary. This is generally what you want, since this way tests that
pass don't generate distracting noise. If you do want all the output as it
deep-diff2 when tests fail to distinguish the difference between
the actual and expected values. If you don't like the format, or if it provides
unhelpful output in a particular scenario, you can turn it off using the
--diff-style :none option.
--version prints version information, whereas
--test-help will print the
available command line flags. Note that while the more common
--help is also
available, it is not usable under Clojure CLI, instead it will print the help
information for Clojure itself.
Conceptually Kaocha goes through three steps: load configuration, load tests,
and run tests. The result of each step is a data structure. You can view these
structures (EDN) with
--print-config Print out the fully merged and normalized config, then exit.
--print-test-plan Load tests, build up a test plan, then print out the test plan and exit.
--print-result Print the test result map as returned by the Kaocha API.