{"id":17524214,"url":"https://github.com/barrucadu/dejafu","last_synced_at":"2025-05-15T09:05:57.889Z","repository":{"id":24804828,"uuid":"28218918","full_name":"barrucadu/dejafu","owner":"barrucadu","description":"Systematic concurrency testing meets Haskell.","archived":false,"fork":false,"pushed_at":"2025-03-11T09:31:45.000Z","size":2765,"stargazers_count":197,"open_issues_count":22,"forks_count":19,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-05-14T23:44:29.594Z","etag":null,"topics":["concurrency","haskell","testing"],"latest_commit_sha":null,"homepage":"https://dejafu.docs.barrucadu.co.uk/","language":"Haskell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/barrucadu.png","metadata":{"files":{"readme":"README.markdown","changelog":"CHANGELOG.rst","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2014-12-19T07:21:45.000Z","updated_at":"2025-04-15T15:50:54.000Z","dependencies_parsed_at":"2024-01-15T10:15:27.920Z","dependency_job_id":"e9e9ea98-123a-4baa-bbd0-28f8abfa1799","html_url":"https://github.com/barrucadu/dejafu","commit_stats":{"total_commits":1241,"total_committers":14,"mean_commits":88.64285714285714,"dds":"0.055600322320709106","last_synced_commit":"d115bdfa0779f7297aa022ecdb68932362577b2e"},"previous_names":[],"tags_count":196,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/barrucadu%2Fdejafu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/barrucadu%2Fdejafu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/barrucadu%2Fdejafu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/barrucadu%2Fdejafu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/barrucadu","download_url":"https://codeload.github.com/barrucadu/dejafu/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254310513,"owners_count":22049468,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["concurrency","haskell","testing"],"created_at":"2024-10-20T14:07:06.068Z","updated_at":"2025-05-15T09:05:57.869Z","avatar_url":"https://github.com/barrucadu.png","language":"Haskell","funding_links":[],"categories":[],"sub_categories":[],"readme":"dejafu\n======\n\n\u003e [Déjà Fu is] A martial art in which the user's limbs move in time as\n\u003e well as space, […] It is best described as \"the feeling that you\n\u003e have been kicked in the head this way before\"\n\u003e\n\u003e -- Terry Pratchett, Thief of Time\n\n- [Installation](#installation)\n- [Quick start guide](#quick-start-guide)\n- [Why Déjà Fu?](#why-déjà-fu)\n- [Contributing](#contributing)\n- [Release notes](#release-notes)\n- [Questions, feedback, discussion](#questions-feedback-discussion)\n- [Bibliography](#bibliography)\n- **[The website!](https://dejafu.docs.barrucadu.co.uk/)**\n\nDéjà Fu is a unit-testing library for concurrent Haskell programs.\nTests are deterministic and expressive, making it easy and convenient\nto test your threaded code.\n\nAvailable on [GitHub][], [Hackage][], and [Stackage][].\n\n[GitHub]:   https://github.com/barrucadu/dejafu\n[Hackage]:  https://hackage.haskell.org/package/dejafu\n[Stackage]: https://www.stackage.org/package/dejafu\n\nFeatures:\n\n- An abstraction over the concurrency functionality in `IO`\n- Deterministic testing of nondeterministic code\n- Both complete (slower) and incomplete (faster) modes\n- A unit-testing-like approach to writing test cases\n- A property-testing-like approach to comparing stateful operations\n- Testing of potentially nonterminating programs\n- Integration with [HUnit][] and [tasty][]\n\n[HUnit]: https://hackage.haskell.org/package/HUnit\n[Tasty]: https://hackage.haskell.org/package/tasty\n\nThere are a few different packages under the Déjà Fu umbrella:\n\n|   | Version | Summary |\n| - | ------- | ------- |\n| [concurrency][h:conc]    | 1.11.0.3 | Typeclasses, functions, and data types for concurrency and STM. |\n| [dejafu][h:dejafu]       | 2.4.0.7  | Systematic testing for Haskell concurrency. |\n| [hunit-dejafu][h:hunit]  | 2.0.0.6  | Deja Fu support for the HUnit test framework. |\n| [tasty-dejafu][h:tasty]  | 2.1.0.2  | Deja Fu support for the Tasty test framework. |\n\nSee [the latest package documentation](https://dejafu.docs.barrucadu.co.uk/packages/).\n\nEach package has its own README and CHANGELOG in its subdirectory.\n\nThere is also dejafu-tests, the test suite for dejafu. This is in a\nseparate package due to Cabal being bad with test suite transitive\ndependencies.\n\n[h:conc]:   https://hackage.haskell.org/package/concurrency\n[h:dejafu]: https://hackage.haskell.org/package/dejafu\n[h:hunit]:  https://hackage.haskell.org/package/hunit-dejafu\n[h:tasty]:  https://hackage.haskell.org/package/tasty-dejafu\n\n\nInstallation\n------------\n\nInstall from Hackage globally:\n\n```\n$ cabal install dejafu\n```\n\nOr add it to your cabal file:\n\n```\nbuild-depends: ...\n             , dejafu\n```\n\nOr to your package.yaml:\n\n```\ndependencies:\n  ...\n  - dejafu\n```\n\n\nQuick start guide\n-----------------\n\nDéjà Fu supports unit testing, and comes with a helper function called\n`autocheck` to look for some common issues.  Let's see it in action:\n\n```haskell\nimport Control.Concurrent.Classy\n\nmyFunction :: MonadConc m =\u003e m String\nmyFunction = do\n  var \u003c- newEmptyMVar\n  fork (putMVar var \"hello\")\n  fork (putMVar var \"world\")\n  readMVar var\n```\n\nThat `MonadConc` is a typeclass abstraction over concurrency, but\nwe'll get onto that shortly.  First, the result of testing:\n\n```\n\u003e autocheck myFunction\n[pass] Never Deadlocks\n[pass] No Exceptions\n[fail] Consistent Result\n    \"hello\" S0----S1--S0--\n\n    \"world\" S0----S2--S0--\nFalse\n```\n\nThere are no deadlocks or uncaught exceptions, which is good; but the\nprogram is (as you probably spotted) nondeterministic!\n\nAlong with each result, Déjà Fu gives us a representative execution\ntrace in an abbreviated form.  `Sn` means that thread `n` started\nexecuting, and `Pn` means that thread `n` pre-empted the previously\nrunning thread.\n\n\nWhy Déjà Fu?\n------------\n\nTesting concurrent programs is difficult, because in general they are\nnondeterministic.  This leads to people using work-arounds like\nrunning their testsuite many thousands of times; or running their\ntestsuite while putting their machine under heavy load.\n\nThese approaches are inadequate for a few reasons:\n\n- **How many runs is enough?** When you are just hopping to spot a bug\n  by coincidence, how do you know to stop?\n- **How do you know if you've fixed a bug you saw previously?**\n  Because the scheduler is a black box, you don't know if the\n  previously buggy schedule has been re-run.\n- **You won't get that much scheduling variety!** Operating systems\n  and language runtimes like to run threads for long periods of time,\n  which reduces the variety you get (and so drives up the number of\n  runs you need).\n\nDéjà Fu addresses these points by offering *complete* testing.  You\ncan run a test case and be guaranteed to find all results with some\nbounds.  These bounds can be configured, or even disabled!  The\nunderlying approach used is smarter than merely trying all possible\nexecutions, and will in general explore the state-space quickly.\n\nIf your test case is just too big for complete testing, there is also\na random scheduling mode, which is necessarily *incomplete*.  However,\nDéjà Fu will tend to produce much more schedule variety than just\nrunning your test case in `IO` the same number of times, and so bugs\nwill tend to crop up sooner.  Furthermore, as you get execution traces\nout, you can be certain that a bug has been fixed by simply following\nthe trace by eye.\n\n\nContributing\n------------\n\nSee the \"contributing\" page on [the website](https://dejafu.docs.barrucadu.co.uk/dev-docs/contributing.html).\n\n**If you'd like to get involved with Déjà Fu**, check out [the\n\"good first issue\" label on the issue tracker][beginners].\n\n[beginners]: https://github.com/barrucadu/dejafu/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22\n\n\nRelease notes\n-------------\n\nSee the CHANGELOG.markdown file.\n\n\nQuestions, feedback, discussion\n-------------------------------\n\n- For general help talk to me in IRC (barrucadu in #haskell) or shoot\n  me an email (mike@barrucadu.co.uk)\n- For bugs, issues, or requests, please [file an issue][issues].\n\n[issues]:  https://github.com/barrucadu/dejafu/issues\n\n\nBibliography\n------------\n\nThese libraries wouldn't be possible without prior research, which I\nmention in the documentation. Haddock comments get the full citation,\nwhereas in-line comments just get the shortened name:\n\n- [BPOR] [Bounded partial-order reduction](http://research.microsoft.com/pubs/202164/bpor-oopsla-2013.pdf),\n  K. Coons, M. Musuvathi, and K. McKinley (2013)\n\n- [RDPOR] [Dynamic Partial Order Reduction for Relaxed Memory Models](http://www.faculty.ece.vt.edu/chaowang/pubDOC/ZhangKW15.pdf),\n  N. Zhang, M. Kusano, and C. Wang (2015)\n\n- [Empirical] [Concurrency Testing Using Schedule Bounding: an Empirical Study](http://www.doc.ic.ac.uk/~afd/homepages/papers/pdfs/2014/PPoPP.pdf),\n  P. Thompson, A. Donaldson, and A. Betts (2014)\n\n- [RMMVerification] [On the Verification of Programs on Relaxed Memory Models](https://orbi.ulg.ac.be/bitstream/2268/158670/1/thesis.pdf),\n  A. Linden (2014)\n\nThere are also a few papers on dejafu itself:\n\n- [Déjà Fu: A Concurrency Testing Library for Haskell](https://www.barrucadu.co.uk/publications/dejafu-hs15.pdf),\n  M. Walker and C. Runciman (2015)\n\n  This details dejafu-0.1, and was presented at the 2015 Haskell\n  Symposium.\n\n- [Déjà Fu: A Concurrency Testing Library for Haskell](https://www.barrucadu.co.uk/publications/YCS-2016-503.pdf),\n  M. Walker and C. Runciman (2016)\n\n  This is a more in-depth technical report, written between the\n  dejafu-0.2 and dejafu-0.3 releases.\n\n- [Revealing Behaviours of Concurrent Functional Programs by Systematic Testing](https://www.barrucadu.co.uk/publications/thesis.pdf),\n  M. Walker (2018)\n\n  This is my Ph.D thesis, which discusses dejafu and my other research projects.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbarrucadu%2Fdejafu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbarrucadu%2Fdejafu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbarrucadu%2Fdejafu/lists"}