test.check

Property-based testing generates random test data to verify properties hold across many inputs. Instead of specific test cases, define universal properties.

Core Pattern

(require '[clojure.test.check :as tc]
         '[clojure.test.check.generators :as gen]
         '[clojure.test.check.properties :as prop])

(def my-property
  (prop/for-all [v (gen/vector gen/small-integer)]
    (= (count v) (count (reverse v)))))

(tc/quick-check 100 my-property)
;; => {:result true, :pass? true, :num-tests 100, ...}

clojure.test Integration

(require '[clojure.test.check.clojure-test :refer [defspec]])

(defspec sort-is-idempotent ;; 100 optional  iterations value here
  (prop/for-all [v (gen/vector gen/small-integer)]
    (= (sort v) (sort (sort v)))))

Important! Prefer NOT to supply an iterations, prefer the framework defaults

Essential Generators

gen/small-integer

gen/large-integer

gen/nat

gen/boolean

gen/string

gen/keyword

(gen/vector g)

(gen/tuple g1 g2)

(gen/elements coll)

(gen/one-of [g1 g2])

See references/cheatsheet.md for complete generator reference.

Generator Combinators

fmap - Transform generated values:

(gen/fmap sort (gen/vector gen/small-integer))  ; sorted vectors
(gen/fmap set (gen/vector gen/nat))             ; sets from vectors

such-that - Filter values (use sparingly, only for likely predicates):

(gen/such-that not-empty (gen/vector gen/boolean))

bind - Chain generators (value from first determines second):

(gen/bind (gen/not-empty (gen/vector gen/small-integer))
          #(gen/tuple (gen/return %) (gen/elements %)))

let - Macro combining fmap/bind:

(gen/let [a gen/nat
          b gen/nat]
  {:sum (+ a b) :a a :b b})

Custom Record Generators

(defrecord User [name id email])

(def user-gen
  (gen/fmap (partial apply ->User)
            (gen/tuple gen/string-alphanumeric
                       gen/nat
                       (gen/fmap #(str % "@example.com") gen/string-alphanumeric))))

Recursive Generators

(def json-like
  (gen/recursive-gen
    (fn [inner] (gen/one-of [(gen/list inner)
                             (gen/map gen/keyword inner)]))
    (gen/one-of [gen/small-integer gen/boolean gen/string])))

Shrinking Failures

When a test fails, test.check automatically shrinks to minimal failing case:

;; Fails on vectors containing 42
(tc/quick-check 100
  (prop/for-all [v (gen/vector gen/small-integer)]
    (not-any? #{42} v)))
;; :fail [[-35 -9 42 8 31 ...]]  <- original failure
;; :shrunk {:smallest [[42]]}    <- minimal case

Critical Pitfalls

Avoid gen/bind when gen/fmap suffices - bind hampers shrinking:

;; Bad: shrinks poorly
(gen/let [n (gen/fmap #(* 2 %) gen/nat)]
  (gen/vector gen/large-integer n))

;; Good: shrinks well
(gen/fmap #(cond-> % (odd? (count %)) pop)
          (gen/vector gen/large-integer))

Use gen/large-integer for real integer testing - small-integer/nat cap at ~200.

Run at least 100 tests - Size cycles through 0-199, fewer tests means poor coverage.

Don't use such-that for unlikely predicates - Will timeout. Use fmap to construct valid values instead.

See references/advanced.md for sizing/shrinking details.

Common Property Patterns

Roundtrip:

(= x (decode (encode x)))

(= (f x) (f (f x)))

(= (count v) (count (sort v)))

(= (f a b) (f b a))

(= (my-impl x) (reference-impl x))

See references/examples.md for generator recipes.