Kaocha
Full featured next generation test runner for Clojure.
Projects
Project | CI | Docs | Release | Coverage |
---|---|---|---|---|
kaocha | ||||
kaocha-cljs | ||||
kaocha-cucumber | ||||
kaocha-junit-xml | ||||
kaocha-cloverage | ||||
kaocha-boot | ||||
deep-diff |
Docs
- 1. Introduction
- 2. Installing
- 3. Configuration
- 4. Running Kaocha CLI
- 5. Running Kaocha From the REPL
- 6. Focusing and Skipping
- 7. Watch mode
- 8. Plugins
- 9. Extending
clojure.test
assertion extensions- CLI:
--fail-fast
option - CLI: Print the Kaocha configuration
- CLI:
--reporter
option - CLI: Selecting test suites
- Configuration: Bindings
- Focusing based on metadata
- Focusing on specific tests
- Skipping based on metadata
- Skipping test based on ids
- Marking tests as pending
- Plugin: Capture output
- Plugin: Hooks
- Plugin: Notifier (desktop notifications)
- Plugin: Clojure/Java Version filter
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 "0.0-418"}}}}}
Add a binstub called bin/kaocha
mkdir -p bin
echo '#!/usr/bin/env bash' > 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 "0.0-418"]]}}
:aliases {"kaocha" ["with-profile" "+kaocha" "run" "-m" "kaocha.runner"]})
Add a binstub called bin/kaocha
mkdir -p bin
echo '#!/usr/bin/env bash' > 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 bash' > 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
(justunit
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
#kaocha/v1
{:tests [{:id :unit
:test-paths ["test" "src"]
:ns-patterns [".*"]}]}
;; :reporter kaocha.report.progress/progress
;; :plugins [:profiling :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
© Arne Brasseur 2018
Available under the terms of the Eclipse Public License 1.0, see LICENSE.txt