Liking cljdoc? Tell your friends :D

kaocha.api

Programmable test runner interface.

Programmable test runner interface.

kaocha.classpath

This is the add-classpath function from Pomegranate 1.0.0, extracted so we don't need to pull in Aether.

This is the add-classpath function from Pomegranate 1.0.0, extracted so we
don't need to pull in Aether.

kaocha.plugin.alpha.xfail

This plugin inverses fail & pass for tests marked with the ^:kaocha/xfail metadata. A failing test can be marked with this metadata, and will now be considered passing. Once the test passes again, it fails.

Note that this current implementation inverses each assertion in turn, so if you have multiple assertions in a xfail test, then they all must fail for the test to pass.

This plugin inverses fail & pass for tests marked with the ^:kaocha/xfail
metadata. A failing test can be marked with this metadata, and will now be
considered passing. Once the test passes again, it fails.

Note that this current implementation inverses each assertion in turn, so if
you have multiple assertions in a xfail test, then they all must fail for the
test to pass.

kaocha.plugin.version-filter

Filter tests based on the Clojure or Java version.

This plugin will look for test metadata specifying the minimum or maximum version of Clojure or Java this test is designed to work with.

The recognized metadata keys are :min-clojure-version, :max-clojure-version, :min-java-version, and :max-java-version. The associated value is a version string, such as "1.10.0".

You can set both a minimum and a maximum to limit to a certain range. The boundaries are always inclusive, so ^{:max-clojure-version "1.9"} will run on Clojure 1.9.* or earlier.

Specificty matters, a test with a max version of "1.10" will also run on version"1.10.2", whereas if the max version is"1.10.0"` it will not.

Filter tests based on the Clojure or Java version.

This plugin will look for test metadata specifying the minimum or maximum
version of Clojure or Java this test is designed to work with.

The recognized metadata keys are `:min-clojure-version`,
`:max-clojure-version`, `:min-java-version`, and `:max-java-version`. The
associated value is a version string, such as `"1.10.0"`.

You can set both a minimum and a maximum to limit to a certain range. The
boundaries are always inclusive, so `^{:max-clojure-version "1.9"}` will run
on Clojure `1.9.*` or earlier.

Specificty matters, a test with a max version of `"1.10" will also run on
version `"1.10.2"`, whereas if the max version is `"1.10.0"` it will not.

kaocha.repl

REPL interface to Kaocha

Running tests

To run tests from the REPL, use run. Without any arguments it runs all tests in the current namespace. This is equivalent to (run *ns*)

(use 'kaocha.repl)

(run)
;;=> #:kaocha.result{:count 18, :pass 50, :error 0, :fail 0}

Pass one or more arguments to run to only run specific tests. This way you can test a single var, a namespace, or a test suite. You can using keywords, symbols, namespace objects, and vars.

(run :unit)                               ;; run the :unit test suite
(run 'kaocha.random-test)                 ;; run all tests in the kaocha.random-test namespace
(run 'kaocha.random-test/rand-ints-test)  ;; run the specified test
(run #'rand-ints-test)                    ;; test the given var

You can pass in any number of things to test. As a final argument you can pass in a map to override specific configuration options. See config for syntax.

(run :foo.bar
     :bar.baz
     {:config-file "my_tests.edn"
      :focus-meta [:xxx]}) ;; run all tests with ^:xxx metadata

run always performs a full kaocha run, meaning all fixtures, plugins etc will run.

Note that deftest returns the var it defines. This means that with in-buffer evaluation you can use this pattern to quickly define and validate a test.

(run
  (defmethod my-test ,,,))
;;=> #:kaocha/result{:count 1, :pass 3, :error 0, :fail 0}

To run all tests defined in tests.edn, use run-all

Inspecting configuration and test plan

Before running tests Kaocha builds up a configuration, and based on that loads all tests and builds up a test-plan. If Kaocha is not behaving as you would expect then inspecting the configuration and test-plan is a good way to figure out what's going on. The config and test-plan functions provide this kind of debugging information.

These will particularly come in handy when developing plugins.

REPL interface to Kaocha

## Running tests

To run tests from the REPL, use [[run]]. Without any arguments it runs all
tests in the current namespace. This is equivalent to `(run *ns*)`

``` clojure
(use 'kaocha.repl)

(run)
;;=> #:kaocha.result{:count 18, :pass 50, :error 0, :fail 0}
```

Pass one or more arguments to [[run]] to only run specific tests. This way
you can test a single var, a namespace, or a test suite. You can using keywords,
symbols, namespace objects, and vars.

``` clojure
(run :unit)                               ;; run the :unit test suite
(run 'kaocha.random-test)                 ;; run all tests in the kaocha.random-test namespace
(run 'kaocha.random-test/rand-ints-test)  ;; run the specified test
(run #'rand-ints-test)                    ;; test the given var
```

You can pass in any number of things to test. As a final argument you can pass
in a map to override specific configuration options. See [[config]] for syntax.

``` clojure
(run :foo.bar
     :bar.baz
     {:config-file "my_tests.edn"
      :focus-meta [:xxx]}) ;; run all tests with ^:xxx metadata
```

`run` always performs a full kaocha run, meaning all fixtures, plugins etc
will run.

Note that `deftest` returns the var it defines. This means that with in-buffer
evaluation you can use this pattern to quickly define and validate a test.

``` clojure
(run
  (defmethod my-test ,,,))
;;=> #:kaocha/result{:count 1, :pass 3, :error 0, :fail 0}
```

To run all tests defined in `tests.edn`, use [[run-all]]

## Inspecting configuration and test plan

Before running tests Kaocha builds up a configuration, and based on that loads
all tests and builds up a test-plan. If Kaocha is not behaving as you would
expect then inspecting the configuration and test-plan is a good way to figure
out what's going on. The [[config]] and [[test-plan]] functions provide this
kind of debugging information.

These will particularly come in handy when developing plugins.

kaocha.report

Reporters generate textual output during a test run, providing real-time information on test progress, failures, errors, and so forth. They are in nature imperative and side-effectful, they generate output on an output stream (typically stdout), based on test events. Some reporters are also used to track state. This is unfortunate as it goes against Kaocha's functional design, but since we want test runs to be interruptible it is somewhat inevitable.

The concept of reporters is directly taken from clojure.test, but is used in Kaocha also when running other types of tests.

A reporter is a function which takes a single argument, a map. The map will have a :type key indicating the type of event, e.g. :begin-test-var, :fail, :pass, or :summary.

Reporters as imagined in clojure.test are a flawed design, we try to make the best of it. See also the monkeypatching of clojure.test/do-test in kaocha.monkey-patch, which is necessary to be able to intercept failures quickly in case the users runs with --fail-fast enabled. The patch also ensures that the current testable is always available in the event map under :kaocha/testable,

Kaocha differs from stock clojure.test in that multiple reporters can be active at the same time. On the command line you can specify --reporter multiple times, in tests.edn you can pass a vector to :kaocha/reporter, and/or point at a var which itself defines a vector of functions. Each of the given functions will be called in turn for each event generated.

This has allowed Kaocha to split the functionality of reporters up, making them more modular. E.g. kaocha.report/report-counters only keeps the fail/error/pass/test counters, without concerning itself with output, making it reusable.

This namespace implements the reporters provided by Kaocha out of the box that don't need extra dependencies. Others like e.g. the progress bar are in their own namespace to prevent loading files we don't need, and thus slowing down startup.

Issues with clojure.test reporters

clojure.test provides reporters as a way to extend the library. By default clojure.test/report is a multimethod which dispatches on :type, and so libraries can extend this multimethod to add support for their own event types. A good example is the :mismatch event generated by matcher-combinators.

Tools can also rebind clojure.test/report, and use it as an interface for capturing test run information.

The problem is that these two approaches don't mesh. When tools (like Kaocha, CIDER, Cursive, etc.) rebind clojure.test/report, then any custom extensions to the multimethod disappear.

This can also cause troubles when a library which extends clojure.test/report gets loaded after it has been rebound. This was an issue for a while in test.check, which assumed report would always be a multimethod (this has been rectified). For this reasons Kaocha only rebinds report after the "load" step.

Kaocha tries to work around these issues to some extent by forwarding any keys it does not know about to the original clojure.test/report multimethod. This isn't ideal, as these extensions are not aware of Kaocha's formatting and output handling, but it does provide some level of compatiblity with third party libraries.

For popular libraries we will include reporter implementations that handle these events in a way that makes sense within Kaocha, see e.g. kaocha.matcher-combinators. Alternatively library authors can themselves strive for Kaocha compatiblity, we try to give them the tools to enable this, through keyword derivation and custom multimethods.

Custom event types

kaocha.report makes use of Clojure's keyword hierarchy feature to determine the type of test events. To make Kaocha aware of your custom event, first add a derivation from :kaocha/known-type, this will stop the event from being propagated to the original clojure.test/report

(kaocha.hierarchy/derive! :mismatch :kaocha/known-key)

If the event signals an error or failure which causes the test to fail, then derive from :kaocha/fail-type. This will make Kaocha's existing reporters compatible with your custom event.

(kaocha.hierarchy/derive! :mismatch :kaocha/fail-type)
Reporters generate textual output during a test run, providing real-time
information on test progress, failures, errors, and so forth. They are in
nature imperative and side-effectful, they generate output on an output
stream (typically stdout), based on test events. Some reporters are also used
to track state. This is unfortunate as it goes against Kaocha's functional
design, but since we want test runs to be interruptible it is somewhat
inevitable.

The concept of reporters is directly taken from clojure.test, but is used in
Kaocha also when running other types of tests.

A reporter is a function which takes a single argument, a map. The map will
have a `:type` key indicating the type of event, e.g. `:begin-test-var`,
`:fail`, `:pass`, or `:summary`.

Reporters as imagined in `clojure.test` are a flawed design, we try to make
the best of it. See also the monkeypatching of `clojure.test/do-test` in
`kaocha.monkey-patch`, which is necessary to be able to intercept failures
quickly in case the users runs with `--fail-fast` enabled. The patch also
ensures that the current testable is always available in the event map under
`:kaocha/testable`,

Kaocha differs from stock `clojure.test` in that multiple reporters can be
active at the same time. On the command line you can specify `--reporter`
multiple times, in `tests.edn` you can pass a vector to `:kaocha/reporter`,
and/or point at a var which itself defines a vector of functions. Each of the
given functions will be called in turn for each event generated.

This has allowed Kaocha to split the functionality of reporters up, making
them more modular. E.g. `kaocha.report/report-counters` only keeps the
fail/error/pass/test counters, without concerning itself with output, making
it reusable.

This namespace implements the reporters provided by Kaocha out of the box that
don't need extra dependencies. Others like e.g. the progress bar are in their
own namespace to prevent loading files we don't need, and thus slowing down
startup.

### Issues with clojure.test reporters

`clojure.test` provides reporters as a way to extend the library. By default
`clojure.test/report` is a multimethod which dispatches on `:type`, and so
libraries can extend this multimethod to add support for their own event
types. A good example is the `:mismatch` event generated by
matcher-combinators.

Tools can also rebind `clojure.test/report`, and use it as an interface for
capturing test run information.

The problem is that these two approaches don't mesh. When tools (like Kaocha,
CIDER, Cursive, etc.) rebind `clojure.test/report`, then any custom extensions
to the multimethod disappear.

This can also cause troubles when a library which extends
`clojure.test/report` gets loaded after it has been rebound. This was an issue
for a while in test.check, which assumed `report` would always be a
multimethod (this has been rectified). For this reasons Kaocha only rebinds
`report` *after* the "load" step.

Kaocha tries to work around these issues to some extent by forwarding any keys
it does not know about to the original `clojure.test/report` multimethod. This
isn't ideal, as these extensions are not aware of Kaocha's formatting and
output handling, but it does provide some level of compatiblity with third
party libraries.

For popular libraries we will include reporter implementations that handle
these events in a way that makes sense within Kaocha, see e.g.
`kaocha.matcher-combinators`. Alternatively library authors can
themselves strive for Kaocha compatiblity, we try to give them the tools to
enable this, through keyword derivation and custom multimethods.

### Custom event types

`kaocha.report` makes use of Clojure's keyword hierarchy feature to determine
the type of test events. To make Kaocha aware of your custom event, first add
a derivation from `:kaocha/known-type`, this will stop the event from being
propagated to the original `clojure.test/report`

``` clojure
(kaocha.hierarchy/derive! :mismatch :kaocha/known-key)
```

If the event signals an error or failure which causes the test to fail, then
derive from `:kaocha/fail-type`. This will make Kaocha's existing reporters
compatible with your custom event.

``` clojure
(kaocha.hierarchy/derive! :mismatch :kaocha/fail-type)
```

kaocha.runner

Main entry point for command line use.

Main entry point for command line use.

kaocha.test

Work in progress.

This is intended to eventually be a drop-in replacement for clojure.test, with some improvements.

  • deftest will kick-off a test run unless one is already in progress, for easy in-buffer eval
Work in progress.

This is intended to eventually be a drop-in replacement for clojure.test, with
some improvements.

- deftest will kick-off a test run unless one is already in progress, for easy
  in-buffer eval

kaocha.type

Utilities for writing new test types.

Utilities for writing new test types.

kaocha.type.clojure.test

No vars in this namespace.

kaocha.type.var

No vars in this namespace.

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

× close