Home

Awesome

<p align="center"><img src="kaocha.png"></p>

Full featured next generation test runner for Clojure.

Jump to Quick start | Docs

Projects

<!-- 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
<!-- /projects -->

考察 [kǎo chá]

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.

Docs

<!-- docs-toc --> <!-- /docs-toc -->

Features

Features include

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.91.1392"}}
         :main-opts ["-m" "kaocha.runner"]}}}

Add a binstub called bin/kaocha

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

If you're on windows and installed clojure into powershell then you can put this into kaocha.ps1 for use with powershell.exe

clojure -M:test "$args"

Or put this in kaocha.bat for use with cmd.exe

powershell -command clojure -M:test "%*"

Or put this in kaocha for use with msys2

powershell -command clojure -M:test "$@"

Leiningen

Add a profile and alias

;; project.clj
(defproject my-proj "0.1.0"
  :dependencies [,,,]
  :profiles {:kaocha {:dependencies [[lambdaisland/kaocha "1.91.1392"]]}}
  :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

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

We also support using the Clojure CLI :exec-fn/-X. However, we recommend the binstub approach above because it allows you to use traditional long and short options. If you nonetheless prefer :exec-fn/-X, you can set up deps.edn:

;; deps.edn
{:deps { ,,, }
 :aliases
 {:test {:extra-deps {lambdaisland/kaocha {:mvn/version "1.91.1392"}}
         :exec-fn kaocha.runner/exec-fn
         :exec-args {}}}}

And then Kaocha can be invoked this way: clojure -X:test

Generally speaking, we recommend using tests.edn for all of your configuration rather than putting it in exec-args unless there's an alternative combination of options you frequently run.

In that case, you can put configuration options :exec-args as though it were tests.edn. Let's say you frequently use watch with :fail-fast and a subset of tests skipped. You could save that configuration with an additional alias: clojure -X:watch-test like so:

;; deps.edn
{:deps { ,,, }
 :aliases
 {:test {:extra-deps {lambdaisland/kaocha {:mvn/version "1.91.1392"}}
         :exec-fn kaocha.runner/exec-fn
         :exec-args {}}
 :watch-test {:extra-deps {lambdaisland/kaocha {:mvn/version "1.91.1392"}}
         :exec-fn kaocha.runner/exec-fn
         :exec-args {:watch? true
	 :skip-meta :slow
	 :fail-fast? true }}}}

If you wanted to turn off fail-fast temporarily, you could run clojure -X:watch-test :fail-fast? false

You can also pass exec-args on the command line like so:

clojure -X:test :print-config true :kaocha.plugin.randomize/seed 603964682

Babashka

Kaocha is compatible with Babashka.

You can create a bb.edn file:

{:paths ["src" "test"]
 :deps {lambdaisland/kaocha {:mvn/version "1.91.1392"}}}

Then you can create a binstub named bin/kaocha-bb:


#!/usr/bin/env bash
bb -m kaocha.runner/-main  $@

If you exclusively want to run tests using Babashka, you can of course call it bin/kaocha.

All tools

By default, Kaocha assumes that:

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

Requirements

Kaocha requires Clojure 1.9 or later.

<!-- opencollective -->

Lambda Island Open Source

Thank you! kaocha is made possible thanks to our generous backers. Become a backer on OpenCollective so that we can continue to make kaocha better.

<a href="https://opencollective.com/lambda-island"> <img src="https://opencollective.com/lambda-island/organizations.svg?avatarHeight=46&width=800&button=false"> <img src="https://opencollective.com/lambda-island/individuals.svg?avatarHeight=46&width=800&button=false"> </a> <img align="left" src="https://github.com/lambdaisland/open-source/raw/master/artwork/lighthouse_readme.png">

 

kaocha is part of a growing collection of quality Clojure libraries created and maintained by the fine folks at Gaiwan.

Pay it forward by becoming a backer on our OpenCollective, so that we continue to enjoy a thriving Clojure ecosystem.

You can find an overview of all our different projects at lambdaisland/open-source.

 

 

<!-- /opencollective --> <!-- contributing -->

Contributing

We warmly welcome patches to kaocha. Please keep in mind the following:

We would very much appreciate it if you also

We recommend opening an issue first, before opening a pull request. That way we can make sure we agree what the problem is, and discuss how best to solve it. This is especially true if you add new dependencies, or significantly increase the API surface. In cases like these we need to decide if these changes are in line with the project's goals.

* This goes for features too, a feature needs to solve a problem. State the problem it solves first, only then move on to solving it.

** Projects that have a version that starts with 0. may still see breaking changes, although we also consider the level of community adoption. The more widespread a project is, the less likely we're willing to introduce breakage. See LambdaIsland-flavored Versioning for more info.

<!-- /contributing --> <!-- license -->

License

Copyright © 2018-2023 Arne Brasseur and contributors

Available under the terms of the Eclipse Public License 1.0, see LICENSE.txt

<!-- /license -->