Liking cljdoc? Tell your friends :D

Full featured next generation test runner for Clojure.

Projects

ProjectCIDocsReleaseCoverage
kaochaCircleCIcljdoc badgeClojars Projectcodecov
kaocha-cljsCircleCIcljdoc badgeClojars Projectcodecov
kaocha-cucumberCircleCIcljdoc badgeClojars Projectcodecov
kaocha-junit-xmlCircleCIcljdoc badgeClojars Projectcodecov
kaocha-cloverageCircleCIcljdoc badgeClojars Projectcodecov
kaocha-bootCircleCIcljdoc badgeClojars Projectcodecov
deep-diffCircleCIcljdoc badgeClojars Projectcodecov

考察 [kǎo chá]

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

See the Line Dict entry for an audio sample.

Support Lambda Island Open Source

Kaocha and its sub-projects are part of a growing collection of quality Clojure libraries and tools released on the Lambda Island label. If you find value in our work please consider becoming a backer on Open Collective

Need help?

Are you

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

Docs

Features

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 { ,,, }
 :aliases
 {:test {:extra-deps {lambdaisland/kaocha {:mvn/version "1.0.629"}}}}}

Add a binstub called bin/kaocha

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

Leiningen

Add a profile and alias

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

Add a binstub called bin/kaocha

mkdir -p bin
echo '#!/usr/bin/env sh' > bin/kaocha
echo 'lein kaocha "$@"' >> bin/kaocha
chmod +x bin/kaocha

Boot

In your build.boot 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 bin/kaocha

mkdir -p bin
echo '#!/usr/bin/env sh' > bin/kaocha
echo 'boot kaocha "$@"' >> bin/kaocha
chmod +x bin/kaocha

All tools

By default, Kaocha assumes that:

  • source files are in the src/ folder,
  • tests files are in the test/ folder,
  • all test namespaces names end with -test (eg. my-project.core-test). Also, the default test suite id is :unit (just unit 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 tests.edn 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 tests.edn config file (should run all tests found in src/ and /test, in any namespace).

#kaocha/v1
{:tests [{:id          :unit
          :test-paths  ["test" "src"]
          :ns-patterns [".*"]}]}
          ;; :reporter kaocha.report.progress/report
          ;; :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

bin/kaocha

# 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 my.app.foo-test/bar-test

# 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))

Requirements

Kaocha requirements Clojure 1.9 or later.

License

  Copyright © 2018-2019 Arne Brasseur   Available under the terms of the Eclipse Public License 1.0, see LICENSE.txt

Can you improve this documentation? These fine people already did:
Arne Brasseur, François De Serres, Rick Moynihan, Matthew Boston, fdserr, Joel Kaasinen, The Alchemist, Daniel Compton, José Luis Lafuente & Jose V. Trigueros
Edit on GitHub

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

× close