Haskell World logo Haskell WorldWrite code, build worlds
Tutorials

Haskell QuickCheck Tutorial for Property Based Testing

You wrote ten unit tests, they all pass, and a user still finds the one input that breaks your function.

A laptop on a wooden desk showing a terminal full of passing test results next to a notebook with handwritten function signatures

You wrote ten unit tests, they all pass, and a user still finds the one input that breaks your function. That gap is exactly what a Haskell QuickCheck tutorial should close: instead of picking examples by hand, you describe a rule your code must obey and let the library throw hundreds of random inputs at it.

This guide starts after the "reverse twice equals the original list" demo that every introduction shows. We will write properties for a small real module, build a custom generator, read a shrunk counterexample, and wire it all into a test suite you can run in CI. If you are still getting comfortable with the language itself, the beginner's guide to Haskell covers the ground this article assumes.

What Haskell QuickCheck actually does for you

QuickCheck takes a function that returns a Bool, generates random arguments for it, and runs it 100 times by default. If any run returns False, it stops and tries to make the failing input smaller before reporting it. That last step, shrinking, is the part people underestimate. A failing list of 47 elements is useless for debugging. A failing list of two elements usually tells you the bug in one glance.

The generation relies on the Arbitrary type class. Every type with an Arbitrary instance knows how to produce random values of itself and how to shrink them. Int, Char, lists, Maybe, tuples and Map from containers already have instances. If type classes still feel abstract, our walkthrough on type classes with real examples explains why this design lets QuickCheck build a generator for [(Int, Maybe Char)] without you writing a single line.

Setting up a test suite in five minutes

Add a test stanza to your cabal file with type exitcode-stdio-1.0, a main-is pointing at test/Spec.hs, and build-depends on base, QuickCheck and your library. QuickCheck 2.14 and later works with every GHC from 9.2 up, so you rarely need version bounds tighter than QuickCheck 2.14 or newer.

The simplest runnable file looks like this:

  1. Import Test.QuickCheck and the module under test.
  2. Write each property as a top level function, for example prop_roundTrip.
  3. In main, call quickCheck on each property, or use quickCheckWith stdArgs { maxSuccess = 1000 } when you want more runs.

Run cabal test and you will see lines such as "+++ OK, passed 100 tests." for each property.

Writing properties for a real module

Toy examples hide the hard part, which is deciding what to assert. Let us use a realistic target: a module that encodes a list of key value pairs into a query string and decodes it back. Two kinds of properties cover most real code.

Round trip properties

If you have an encoder and a decoder, decoding what you encoded must give back the original. Written out, prop_roundTrip pairs = decode (encode pairs) == Just pairs. This line found two bugs in our first encoder: an unescaped equals sign in a value, and an empty key the decoder dropped.

Invariant properties

Some facts hold no matter what the input is. The encoded string never contains a raw space. The number of ampersand separators is always one fewer than the number of pairs, unless the list is empty. They catch what a round trip misses, because a buggy encoder and a matching buggy decoder can cancel out.

Custom generators with Gen and Arbitrary

Default generators are not always realistic. Random Strings contain control characters and unpaired surrogates, which may be valid for your encoder but drown the interesting cases. The fix is to describe the data you care about.

Inside the Gen monad you have a small, useful toolbox:

  • elements picks from a fixed list, such as a set of 20 common header names.
  • choose picks a number in a range, for example choose (0, 255) for a byte.
  • listOf and vectorOf build lists of random or exact length.
  • frequency weights several generators, so you can make empty strings appear 10 percent of the time instead of almost never.

Wrap the result in a newtype, such as newtype Key = Key String, and give it an Arbitrary instance where arbitrary uses your generator and shrink maps the default String shrinker back into Key.

Reading a shrunk counterexample

When a property fails, QuickCheck prints something like "Falsified (after 23 tests and 9 shrinks)" followed by the arguments. Read it in this order. First, the shrunk input, because it is the smallest case the shrinker could find. Second, the number of shrinks: a high number with a still large input often means your custom type has no shrink function, so you are seeing the raw random value.

Then reproduce it in GHCi by pasting the input straight into the function. Because the function is pure, it will fail the same way every time, which is the same reason pure functions make debugging predictable in general. If the output surprises you, the type error or runtime message often makes more sense after a quick read of how to read GHC error messages.

Two settings help when chasing a stubborn failure. The replay field in Args lets you rerun the exact seed QuickCheck printed. And counterexample lets you attach extra text, such as the encoded string, so the failure report shows the intermediate value instead of making you recompute it.

Where the usual advice goes wrong

A common recommendation is to crank maxSuccess to 10,000 or more so you "really" test the code. In practice, more runs of a bad generator buy you very little. If your generator produces lists of length 0 to 30 and your bug only appears at length 300, a million runs will not find it. Spend that effort on the generator instead: check what it produces with sample, look at the distribution with label or classify, and make sure the edge cases you fear show up at least a few percent of the time.

The second piece of advice worth questioning is "replace your unit tests with properties". Keep a handful of hand written examples. They document intent for the next reader and they pin down specific regressions, such as the empty key bug above, so it can never quietly come back if someone later narrows the generator. A good suite in our experience is roughly five to ten properties per module plus two or three named examples for past bugs.

Running properties in CI without flaky failures

Random failures in CI are the point, but you need to reproduce them. Print the seed on failure, which QuickCheck does by default, and keep the CI log for at least 30 days. If you use Hspec or Tasty as a runner, both accept a seed on the command line so you can replay the exact run locally.

Frequently asked questions

Is QuickCheck still used in Haskell projects today?

Yes. It ships as a dependency of a large share of the packages on Hackage and remains the default property testing library in the ecosystem. Hedgehog and falsify are good alternatives with integrated shrinking, but QuickCheck is still what most codebases already use.

How many tests should a QuickCheck property run?

The default of 100 is a fine starting point for local runs. Raise it to 500 or 1,000 in CI for core modules, but improve the generator first, because a better spread of inputs finds more bugs than extra repetitions of the same narrow cases.

What is the difference between QuickCheck and unit tests?

A unit test checks one input against one expected output that you chose. A QuickCheck property states a rule and checks it against many random inputs, then shrinks any failure to a minimal case. Most projects benefit from both, with properties for general behaviour and named examples for specific past bugs.

AS
Adil Sato

Adil Sato teaches programming concepts at a community college and writes online guides for the questions students ask most in the second week of class, not the first. His focus is on making type systems, monads, and functional patterns understandable without reducing them to metaphors that break down the moment you try to use them for real work.

More posts by Adil

More in Tutorials

01doorganico 084goad 3hot8 4465456 after5internprogram ahandfulofblessings ahmadpc ahomcybersecurity allodialresources annodex antiquesandperiodcollectibles aotc asianworldkashmir beedlectrics bloggertemplatefree bluefeatheragency bodyweightsolution campaign08blog carfixadvisor catstreetcollective cbstvsports cnfanspurchasing committeeof500yearsofdignityandresistance covertopsdjs cs-kaiyuangame cuestacomunicaciontotal cxoutlet dancebetgame deskgearhub destinyvillastay detectmagazine di33 diamondsteelbuildings donmo dyanadropship emarsysfinance emimattl escapechan eskitarih evautoplay everythingweddings-orlando farmzone feedviewerapp foxstudiosscratch gamevui123 gleasongrade greetingsday hacklabasu iw-kaiyun jagoanproperti jilidskripsi joltbusinessfinance juegodepokergratis juegospucca kaeru-festival latestmehndidesigns lestanzediottaviano litemagazines localcommunityhero lustrsazan mariashebets menswheels newwebstechs1 nikkit ootheday oxigenvpn plurfitness prefetial probudgetcarpetcleaning psychicmrsmartin pyaten qvantor rejoignezlogis rexzbot riselayouts ruchin rwxqsgd5 sakaltime shibiaowang shop-bot skrtips spotlesshaven strcoding tetapatrium topselller uneplanteartificielle vipertechcr webtech1223411 wo-kygaming yamaha-mekar yeknava yoybuysheets zenunwa yamaha-mekar jilidskripsi ankertoto ankertoto ankertoto