Liking cljdoc? Tell your friends :D

clj-fakes is an isolation framework for Clojure/ClojureScript that makes creating test doubles much easier.

Clojars Project Gitter


  • All test doubles are named "fakes" to simplify the terminology.
  • Fakes can be created for:
    • functions
    • instances of protocols and Java interfaces
  • "Nice" and "strict" protocol fakes are supported.
  • Monkey patching is supported to fake implicit dependencies.
  • Several functions are provided for asserting recorded calls.
  • Self-testing: automatically checks for unused fakes.
  • Informative error messages.
  • Test runner agnostic.
  • Arrange-Act-Assert style testing.


Requirements: Clojure 1.7.0+ and/or ClojureScript 1.10.238+.

Add this to your dependencies:

[clj-fakes "0.12.0"]

Require framework namespace in your unit test source file:

(ns unit.example
    [clj-fakes.core :as f]    
    ; and/or:
    [clj-fakes.context :as fc]))

Cheat Sheet

Creating Faking Context

Explicit context:

(let [ctx (fc/context)]
  ; use clj-fakes.context API here

Implicit context:

  ; use clj-fakes.core API here 
; on exit block will automatically unpatch all patched vars and execute self-tests

All the following examples are assumed to be used inside an implicit context.


Function Stub

(let [foo (f/fake [[1 2] "foo"
                   [3 4 5] "bar"])]
  (foo 1 2) ; => "foo"
  (foo 3 4 5) ; => "bar"
  (foo 100 200)) ; => raises "Unexpected args are passed into fake: (100 200) ..."

Method Stub

(let [cow (f/reify-fake p/AnimalProtocol
                        (sleep :fake [[] "zzz"]))]
  (p/sleep cow) ; => "zzz"
  (p/speak cow)) ; => undefined method exception

Nice Method Stub

(let [cow (f/reify-nice-fake p/AnimalProtocol)]
  (p/sleep cow) ; => FakeReturnValue
  (p/speak cow)) ; => FakeReturnValue 


Function Mock

(let [foo (f/recorded-fake [[(f/arg integer?) (f/arg integer?)] #(+ %1 %2)])
      bar (f/recorded-fake [[(f/arg integer?) (f/arg integer?)] #(* %1 %2)])]
  (foo 1 2)
  (bar 5 6)
  (foo 7 8)
  (f/calls foo)
  ; => [{:args [1 2] :return-value 3}
  ;     {:args [7 8] :return-value 15}]

  ; => [[foo {:args [1 2] :return-value 3}]
  ;     [bar {:args [5 6] :return-value 30}]
  ;     [foo {:args [7 8] :return-value 15}]]

Method Mock

(let [cow (f/reify-fake p/AnimalProtocol
                        (speak :recorded-fake [f/any "moo"]))]
  (p/speak cow)
  (f/calls (f/method cow p/speak))) ; => [{:args ..., :return-value moo}]


These functions return true or raise an exception and can be used only with recorded fakes.

Strictly One Call

(f/was-called-once foo [1 2])

(f/method-was-called-once p/speak cow ["Bob"])

At Least One Call

(f/was-called foo [1 2])

(f/method-was-called p/speak cow ["Bob"])

Strictly One Call Matched The Provided Args Matcher

(f/was-matched-once foo [1 2])

(f/method-was-matched-once p/speak cow ["Bob"])

No Calls

(f/was-not-called foo)

(f/method-was-not-called p/speak cow)

Calls In The Specified Order

  foo [1 2 3]
  foo [(f/arg integer?)]
  bar [100 200]
  baz [300])

  p/speak cow []
  p/sleep cow []
  p/eat dog ["dog food" "water"]
  p/speak cow ["Bob"])

Monkey Patching

Caution: this feature is not thread-safe. Strongly consider avoiding it in Clojure code if you plan to someday run your tests concurrently.

Patch Function With Stub

  (f/patch! #'funcs/sum (f/fake [[1 2] "foo"
                                 [3 4] "bar"]))
  (funcs/sum 1 2) ; => "foo"
  (funcs/sum 3 4)) ; => "bar"

; patching is reverted on exiting with-fakes block
(funcs/sum 1 2) ; => 3

Patch To Spy

(f/patch! #'funcs/sum (f/recorded-fake [f/any funcs/sum]))
(funcs/sum 1 2) ; => 3
(f/was-called funcs/sum [1 2]) ; => true


  (f/fake [f/any nil]))
; => raises "Self-test: no call detected for: non-optional fake ..."

; => raises "Self-test: no check performed on: recorded fake ..."


More documentation can be found at the project site:


The API was mainly inspired by jMock and unittest.mock frameworks with design decisions loosely based on the "Fifteen things I look for in an Isolation framework" by Roy Osherove.

Some alternative frameworks with isolation capabilities:

Also take at look at the article "Isolating External Dependencies in Clojure" by Joseph Wilk.

For more detailed information about unit testing, TDD and test double patterns I'd recommend the books below:

  • "Test Driven Development: By Example" by Kent Beck
  • "Growing Object-Oriented Software, Guided by Tests" by Steve Freeman and Nat Pryce [site]
  • "xUnit Test Patterns: Refactoring Test Code" by Gerard Meszaros [site]


Copyright © 2015 Yuri Govorushchenko.

Released under an MIT license.

Can you improve this documentation? These fine people already did:
metametadata & Yuri Govorushchenko
Edit on GitHub

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

× close