eg

(deftest inc-test
  (is (= 1 (inc 0))))

in eg becomes:

(eg inc 0 1)

eg supports Clojure, ClojureScript JVM, and ClojureScript JS.

Vanilla clojure.test and eg test results are included in the same report. Also, no custom test runner is required.

Check the ideas driving eg.

Installation

Leiningen/Boot

Disclaimer: eg is unstable, marked by a history of buggy features. Use with caution.

[eg "0.4.11-alpha"]

Clojure CLI/deps.edn

eg {:mvn/version "0.4.11-alpha"}

Warning: versions 0.4.4-alpha, through 0.4.10-alpha break in ClojureScript JVM when using spec functionality combined with not explicitly requiring clojure.spec.alpha in a test namespace. This issue has ben fixed since 0.4.11-alpha.

Usage

Let's try eg! Start by creating a REPL session and then requiring eg and ge:

(require '[eg :refer [eg ge]])

eg stands for e.g. (short for example), and ge is just eg reversed.

Each eg test tests one function using examples. You could think of it as a function's test definition:

  (eg not  ; testing clojure.core/not
    false  ; with input parameter `false`
    true)  ; returning expected value `true`

a clojure.test test named not-test was generated.

If a function under test takes multiple parameters, we need to wrap these with []:

(eg * [3 2] 6)

When parameter is a vector, it needs to be wrapped with [] as well:

(eg set
  [[1 2]] #{1 2}) ; cannot do: [1 2] #{1 2}

Each eg test can contain an arbitrary number of examples:

  (eg *
    [3]   3
    [3 2] 6)

There are times when we prefer to have expected values on the left, and input parameters on the right. For that we use ge, a useful mnemonic for the inverted flow of the test example:

  (ge + 10 [3 7])

Expected values can be checked against a predicate or a spec:

(require '[clojure.spec.alpha :as spec])

(spec/def ::int integer?)

(eg dec
  [4] integer?
  [5] ::int)

=> or <= operators between input parameters and expected value can be used to improve readability, or override the default example direction of eg or ge.

(eg hash-map
  [:d 1] {:d 1}
  [:a 1 :b 2 :c 3 :d 4] => {:a 1 :b 2 :c 3 :d 4})

=> or <= can be read as is. {:a 1 :b 2 :c 3 :d 4} is a map?:

(eg hash-map
  map? <= {:a 1}
  {:a 1} coll?) ; when no operator is used, 'is' operator semantics are assumed

ex makes it possible to test the result of calling an arbitrary form expression. Typical scenarios include testing the result of calling a macro (eg, and ge only support function testing), or decomposing the assertion of different properties or values from calling a form:

; let must be used outside of 'ex' when surrounding examples
(let [test-eg-ret (ex (inc 0) 1)
      f-len (count "eg-test-")]
  ; arrows are compulsory
  (ex var? <= test-eg-ret
      (-> test-eg-ret meta :test) => boolean
      (-> test-eg-ret meta :test) => fn?
      (-> test-eg-ret meta :name name (subs f-len)) => not-empty))
  ;=> eg-test-<rand-id>

  (ex (true? false) => false) ;=> eg-test-<rand-id>

If we want to check if the expected value is a function or a spec, the operator = is used:

(defn foo [] inc)

(eg foo [] = inc)
; or
(ge foo [] = 2)

(ex (foo 2) = inc)

(ex inc = (foo))

(ex (foo) = inc)

(defn bar [] ::inc)

(eg bar [] ::inc)

There are times when we just want to test a certain input parameter value, but fill the remainder input parameters nevertheless. eg provides a don't care placeholder _, for these cases:

(eg vector
  [1 2 3 4] [1 2 3 4]
  [5 6 _ 8] vector?
  [4 _ 5]   vector?)

We can arbitrarily name a don't care parameter by prefixing its name with $. A named don't care can also be bound with parts on the expected result. Don't care parameters are generated from parameters on the same argument position:

(eg assoc-in
  [{} [:a :b] {:eggs "boiled"}] => {:a {:b {:eggs "boiled"}}}
  [_ $spam _] => map?
  [_ _ $eggs] => {:a {:b $eggs}})

When writing examples, don't cares enable us to spend less time writting fillers, and the reader is able to better understand the focus of the example.

Expecting arbitrarily nested JavaScript objects or arrays works out of the box:

(eg identity
  #js {:a [1]} => #js {:a [1]}
  #js {:a [1]} => (clj->js {:a [1]}))

(ex (identity #js {:a [1]}) => #js {:a [1]}))

Check if your specs are on the correct track using examples. eg validates examples against a spec defined with a qualified keyword:

(require '[clojure.spec.alpha :as spec])

(spec/def ::string (spec/nilable string?))
(spec/def ::pos-int pos-int?)

(eg ::string nil "foo") ; `^:focus` cannot be used here at the moment
;=> <current-ns>-:string-test

(ge ::pos-int
  1
  ; test invalid examples, i.e., near a spec's boundary, using `!`
  ! 0
  (! -1 -2 -3)) ; equivalent to: ! -1 ! -2 ! -3

Quite often, writing tests becomes an afterthought, because creating test boilerblate like a new test namespace, requiring test forms and functions under test is too much of a hassle, while being immersed on writing code. It would make sense to have test forms globally available that we use almost as often as defn. Introducing set-eg! – call it at the development entrypoint of your program:

(require '[eg :refer [set-eg!]])

To use eg, ge, and ex in any namespace without additional requires, run:

(set-eg!)
;=> :reloading ()

To use eg, and ge in any namespace without additional requires, run:

(set-eg! 'eg 'ge)

PS - This functionality is only supported in Clojure.

It's possible to run only selected tests by using metadata ^:focus on eg or ge:

(eg ^:focus false? [false] true)

There are some caveats to consider when using ^:focus with ClojureScript:

1. The tests report counts towards non focused tests, although examples under such tests are not executed.
2. Assertions for tests defined directly with clojure.test/deftest will still be executed, despite the presence of focused eg, or ge tests.

Skip running certain tests or examples using vanilla Clojure(Script) code:

#_(eg count '(9 8 7)
            3)

(eg count
 ; '(9 8 7) 3
 '(9 8 7 6) 4)

Between eg, and ge, choose the form that is most convenient for your combination of function examples and use it only once for testing a function. For example, don't do this:

(ge inc [1] 2)
(ge inc [0] 1)

or this:

(eg inc [1] 2)
(ge inc [0] 1)

When building with ClojureScript JVM, remove WARNING: eg is a single segment namespace warning with the compiler option single-segment-namespace:

{:cljsbuild
  {:builds
    [{:compiler
       {:warnings
         {:single-segment-namespace false}}}]}}

Run your tests

Finally, run your tests as you normally would with clojure.test.

Clojure tests in the REPL:

(clojure.test/run-all-tests)
; or
(clojure.test/run-tests some.ns)

Clojure tests in the terminal:

> lein test

ClojureScript tests in the REPL:

(cljs.test/run-all-tests)
; or
(cljs.test/run-tests some.ns)

Run eg's own tests

Run eg's own tests expected to pass, fail, targeting Clojure, ClojureScript JVM, and ClojureScript JS.

Test libraries which work great with eg

• eftest – Eftest is a fast and pretty Clojure test runner.
• humane-test-output – Humane test output for clojure.test

License

Copyright (c) 2019 Carlos da Cunha Fontes

The Universal Permissive License (UPL), Version 1.0