You can enable watch mode with the --watch
command line flag. If you want
watch mode to be the default you can also configure it in tests.edn
with
:watch? true
. In that case the --no-watch
flag turns it off again.
When running in watch mode Kaocha will keep an eye on your test and source
directories (as configured on the test suites), as well as your Kaocha
configuration in tests.edn
. Whenever any of these files changes it tries to
reload the changed files, and then runs your tests again.
Watch mode is based on tools.namespace
, this library keeps track of the
dependencies between namespaces. When a file changes then any namespace that
depends on it gets unloaded first, completely erasing the namespace and its vars
from Clojure's memory, before loading them again from scratch.
This fixes a lot of issues that are present with more naive code reloading schemes, but it comes with its own set of caveats. Refer to the tools.namespace README for more information.
If any tests fail, then upon the next change first the failed tests will be run. Only when they pass is the complete suite run again.
Sometimes your source or test directories will contain files that should be
ignored by watch mode, for instance temporary files left by your editor. You can
tell watch mode to ignore these with the :kaocha.watch/ignore
configuration
key.
This takes a vector of patterns which largely behave like Unix-shell style "glob" patterns, although they differ from standard shell behavior in some subtle ways. These are processed using Java's PathMatcher interface, the provided links describes how they work in detail.
#kaocha/v1
{:kaocha.watch/ignore ["*.tmp"]}
When running in watch mode you can press the Enter (Return) key to manually trigger a re-run of the tests. This will always run all tests, not just the tests that failed on the last run.
Interrupt the process (Ctrl-C) to exit Kaocha's watch mode.
The :kaocha.plugin/notifier
plugin will cause a system notification to pop up
whenever a test run finishes. This works really well together with watch mode,
as it means you can leave Kaocha running in the background, and only switch over
when a test failed.
Watch mode is most useful when it can provide quick feedback, this is why it's a
good idea to combine it with --fail-fast
, so you know as soon as possible when
a test fails, and you can focus on one test at a time. You can disable
randomization (--no-randomize
) to prevent having to jump back and forth
between different failing tests.
If your test suites takes a long time to run then watch mode will be a lot less
effective, in that case consider tagging your slowest tests with metadata, and
filtering them out. (--skip-meta :slow
)
tests.edn
is also watched for changes, and gets reloaded on every run, so
there's a lot you can do without having to restart Kaocha.
:fail-fast? true
Can you improve this documentation?Edit on GitHub
cljdoc is a website building & hosting documentation for Clojure/Script libraries
× close