Running midje

Although you could use Midje without Leiningen, I don't recommend it. That said, there are three ways to run Midje: via lein test, lein midje, and lein midje :autotest.

Two words to know

Lein midje

As explained below, lein test makes it awkward to get an accurate combined failure count from your clojure.test and Midje tests. Therefore I recommend lein midje, which you can install as a Leiningen plugin.

The simple way to run lein midje is like this:

% lein midje

That checks all facts and tests in your project's :test-paths and :source-paths. (Midje users sometimes add facts to their source as documentation.) You can also name one or more specific namespaces:

% lein midje behaviors.t-line-number-reporting midje.checkers.t-collection

You can also use * to abbreviate multiple namespaces:

% lein midje midje.emission.*

Note that * names a whole namespace subtree. That is, the previous command will check both midje.emission.t-api and midje.emission.plugins.t-default.

lein midje has other ways of limiting checking to a subset of facts. See lein midje or lein help midje for details.

lein midje shows output like this:

FAIL "a '`fact' that's not true" at (core.clj:7)      ;; FAIL is normally highlighted in red.
    Expected: 5
      Actual: 4
>>> Output from clojure.test tests:

FAIL in (a-test-that-fails) (core.clj:9)
expected: (= (+ 2 2) 5)
  actual: (not (= 4 5))

1 failures, 0 errors.                                 ;; Highlighted in red to mark failure
>>> Midje summary:
FAILURE: 1 claim was not confirmed. (But 1 was.)      ;; Highlighted in red.
Subprocess failed
$ echo $?
2

Notes:

• The clojure.test output only appears if any deftests were run. The Midje and clojure.test outputs are never mixed together, even if tests and facts appear in the same namespace.

• Colorizing can be changed.

• The exit status is the number of failures (whether from clojure.test or Midje), up to a maximum of 255. As a result, scripts on Unix-like systems can check for success or failure in the normal way.

Autotesting

It's often convenient to have lein midje make all its checks, then wait around to recheck when any file has changed. That's done like this:

lein-midje :autotest

In versions of lein-midje before 3.0, the argument was --lazytest.

Changes propagate. Therefore, if a source file changes, all files that depend on it, either directly or indirectly, are also considered changed. Therefore, a change to source will cause tests and facts to be rechecked. (File dependencies are discovered from namespace ns statements, so dependencies created by, say, load-file or (require (calculate-namespace)) aren't tracked.)

:autotest can be told to watch only certain subdirectories. See lein midje or lein help midje for details.

Continuing to use lein test

Midje reports to clojure.test's output, so if you combine Midje facts and clojure.test tests, you'll see all the output together.

Moreover, every Midje fact reports itself to clojure.test as a test, and each check reports to clojure.test whether it passed or failed. Such reports do not necessarily end up in the lein midje summary. Roughly speaking, clojure.test doesn't count assertions except when they're in deftest forms. For that reason, a freestanding is like this one:

(is (= 1 2))

... does not contribute to the failure count printed at the end of a lein test run. The same is true of freestanding facts. If you want their results counted, you need to include them in deftest. (You can wrap a deftest around the whole file below the ns form.)