Systematic concurrency testing meets Haskell.

Language: Haskell

Keywords: concurrency, haskell, testing

dejafu Build Status

[Déjà Fu is] A martial art in which the user's limbs move in time as well as space, […] It is best described as "the feeling that you have been kicked in the head this way before"

-- Terry Pratchett, Thief of Time

Déjà Fu is a unit-testing library for concurrent Haskell programs. Tests are deterministic and expressive, making it easy and convenient to test your threaded code. Available on GitHub, Hackage, and Stackage.


  • An abstraction over the concurrency functionality in IO
  • Deterministic testing of nondeterministic code
  • Both complete (slower) and incomplete (faster) modes
  • A unit-testing-like approach to writing test cases
  • A property-testing-like approach to comparing stateful operations
  • Testing of potentially nonterminating programs
  • Integration with HUnit and tasty

There are a few different packages under the Déjà Fu umbrella:

Version Summary
concurrency Typeclasses, functions, and data types for concurrency and STM.
dejafu Systematic testing for Haskell concurrency.
hunit-dejafu Deja Fu support for the HUnit test framework.
tasty-dejafu Deja Fu support for the Tasty test framework.

Each package has its own README and CHANGELOG in its subdirectory.

There is also dejafu-tests, the test suite for dejafu. This is in a separate package due to Cabal being bad with test suite transitive dependencies.


Install from Hackage globally:

$ cabal install dejafu

Or add it to your cabal file:

build-depends: ...
             , dejafu

Or to your package.yaml:

  - dejafu

Quick start guide

Déjà Fu supports unit testing, and comes with a helper function called autocheck to look for some common issues. Let's see it in action:

import Control.Concurrent.Classy

myFunction :: MonadConc m => m String
myFunction = do
  var <- newEmptyMVar
  fork (putMVar var "hello")
  fork (putMVar var "world")
  readMVar var

That MonadConc is a typeclass abstraction over concurrency, but we'll get onto that shortly. First, the result of testing:

> autocheck myFunction
[pass] Never Deadlocks
[pass] No Exceptions
[fail] Consistent Result
    "hello" S0----S1--S0--

    "world" S0----S2--S0--

There are no deadlocks or uncaught exceptions, which is good; but the program is (as you probably spotted) nondeterministic!

Along with each result, Déjà Fu gives us a representative execution trace in an abbreviated form. Sn means that thread n started executing, and Pn means that thread n pre-empted the previously running thread.

Why Déjà Fu?

Testing concurrent programs is difficult, because in general they are nondeterministic. This leads to people using work-arounds like running their testsuite many thousands of times; or running their testsuite while putting their machine under heavy load.

These approaches are inadequate for a few reasons:

  • How many runs is enough? When you are just hopping to spot a bug by coincidence, how do you know to stop?
  • How do you know if you've fixed a bug you saw previously? Because the scheduler is a black box, you don't know if the previously buggy schedule has been re-run.
  • You won't get that much scheduling variety! Operating systems and language runtimes like to run threads for long periods of time, which reduces the variety you get (and so drives up the number of runs you need).

Déjà Fu addresses these points by offering complete testing. You can run a test case and be guaranteed to find all results with some bounds. These bounds can be configured, or even disabled! The underlying approach used is smarter than merely trying all possible executions, and will in general explore the state-space quickly.

If your test case is just too big for complete testing, there is also a random scheduling mode, which is necessarily incomplete. However, Déjà Fu will tend to produce much more schedule variety than just running your test case in IO the same number of times, and so bugs will tend to crop up sooner. Furthermore, as you get execution traces out, you can be certain that a bug has been fixed by simply following the trace by eye.


See the "contributing" page on the website.

If you'd like to get involved with Déjà Fu, check out the "good first issue" label on the issue tracker.

Release notes

See the CHANGELOG.markdown file.

Questions, feedback, discussion


These libraries wouldn't be possible without prior research, which I mention in the documentation. Haddock comments get the full citation, whereas in-line comments just get the shortened name:

There are also a couple of papers on dejafu itself:

Project Statistics

Sourcerank 9
Repository Size 2.07 MB
Stars 126
Forks 16
Watchers 7
Open issues 29
Dependencies 46
Contributors 11
Tags 177
Last updated
Last pushed

Top Contributors See all

Michael Walker Kirill Zaborsky Pepe Iborra Henry Mercer Gilles Vaibhav Sagar Arnaud Bailly Lars Kuhtz Félix Raimundo Andreas Herrmann Gaël Deest

Packages Referencing this Repo

Integration between the dejafu library for concurrency testing and tasty. This lets you easily in...
Latest release - Updated - 126 stars
[Déjà Fu is] A martial art in which the user's limbs move in time as well as space, […] It is bes...
Latest release - Updated - 126 stars
Integration between the dejafu library for concurrency testing and HUnit. This lets you easily in...
Latest release - Updated - 126 stars
A typeclass abstraction over much of Control.Concurrent (and some extras!). If you're looking for...
Latest release - Updated - 126 stars
Systematic concurrency testing meets Haskell.
Latest release - Updated - 126 stars
Systematic concurrency testing meets Haskell.
Latest release - Updated - 126 stars

Recent Tags See all

dejafu- January 17, 2019
tasty-dejafu- December 02, 2018
dejafu- December 02, 2018
concurrency- November 28, 2018
concurrency- September 22, 2018
dejafu- July 15, 2018
dejafu- July 08, 2018
dejafu- July 02, 2018
tasty-dejafu- July 01, 2018
hunit-dejafu- July 01, 2018
dejafu- July 01, 2018
concurrency- July 01, 2018
dejafu- June 17, 2018
dejafu- June 17, 2018
tasty-dejafu- June 17, 2018

Something wrong with this page? Make a suggestion

Last synced: 2019-01-17 21:27:43 UTC

Login to resync this repository