Hspec and QuickCheck: Property-Based Testing in Haskell

Hspec and QuickCheck: Property-Based Testing in Haskell

QuickCheck is one of the most influential ideas in testing — it originated in Haskell and has been ported to dozens of languages. The core idea: instead of writing specific test cases, you describe properties that should hold for all valid inputs, and QuickCheck generates hundreds of random test cases to find counterexamples. Combined with Hspec's readable structure, this becomes a powerful testing approach.

QuickCheck Basics

QuickCheck works by generating random test data and checking that your property holds:

import Test.QuickCheck

-- Property: reversing a list twice returns the original
prop_reverseReverse :: [Int] -> Bool
prop_reverseReverse xs = reverse (reverse xs) == xs

-- Run it
main :: IO ()
main = quickCheck prop_reverseReverse

Output: +++ OK, passed 100 tests.

If it finds a failing case: *** Failed! Falsified (after 3 tests): [1,2,3]

Integrating with Hspec

import Test.Hspec
import Test.Hspec.QuickCheck
import Test.QuickCheck

spec :: Spec
spec = do
  describe "List operations" $ do
    prop "reverse . reverse == id" $
      \xs -> reverse (reverse xs) == (xs :: [Int])

    prop "length doesn't change on reverse" $
      \xs -> length (reverse xs) == length (xs :: [Int])

    prop "sort is idempotent" $
      \xs -> sort (sort xs) == sort (xs :: [Int])

  describe "String operations" $ do
    prop "intercalate . splitOn round-trips" $
      \s -> intercalate "," (splitOn "," s) == s

prop from Test.Hspec.QuickCheck runs a QuickCheck property within Hspec, reporting failures as Hspec failures.

The Arbitrary Typeclass

QuickCheck uses the Arbitrary typeclass to know how to generate values for a type:

class Arbitrary a where
  arbitrary :: Gen a
  shrink :: a -> [a]  -- optional

Built-in instances exist for most standard types: Int, Integer, Double, Bool, Char, String, [a], Maybe a, tuples, etc.

Writing Custom Arbitrary Instances

data Email = Email { localPart :: String, domain :: String }
  deriving (Show, Eq)

instance Arbitrary Email where
  arbitrary = do
    local <- listOf1 (elements $ ['a'..'z'] ++ ['0'..'9'])
    dom <- listOf1 (elements ['a'..'z'])
    tld <- elements ["com", "org", "net", "io"]
    return $ Email local (dom ++ "." ++ tld)

  shrink (Email l d) =
    [Email l' d | l' <- shrink l, not (null l')] ++
    [Email l d' | d' <- shrink d, not (null d')]

Usage:

spec :: Spec
spec = do
  describe "Email validation" $ do
    prop "generated emails are always valid" $
      \email -> isValid email `shouldBe` True
    
    prop "email round-trips through serialization" $
      \email -> (parseEmail . renderEmail) email `shouldBe` Just email

Generators

QuickCheck provides combinators for building generators:

import Test.QuickCheck

-- Basic generators
arbitraryBoundedIntegral :: (Bounded a, Integral a) => Gen a
arbitraryPrintableChar :: Gen Char

-- Combinators
elements :: [a] -> Gen a          -- pick from list
oneof :: [Gen a] -> Gen a          -- pick one generator
frequency :: [(Int, Gen a)] -> Gen a  -- weighted choice
listOf :: Gen a -> Gen [a]         -- list of any length
listOf1 :: Gen a -> Gen [a]        -- non-empty list
vectorOf :: Int -> Gen a -> Gen [a]  -- exact length list
suchThat :: Gen a -> (a -> Bool) -> Gen a  -- filter

-- Ranges
choose :: Random a => (a, a) -> Gen a
chooseInt :: (Int, Int) -> Gen Int

-- Composing
do
  n <- choose (1, 100)
  xs <- vectorOf n arbitrary
  return xs

Practical Generator Examples

-- Positive integers
positiveInt :: Gen Int
positiveInt = abs <$> arbitrary `suchThat` (> 0)

-- Valid port numbers
portNumber :: Gen Int
portNumber = chooseInt (1024, 65535)

-- HTTP methods
httpMethod :: Gen String
httpMethod = elements ["GET", "POST", "PUT", "DELETE", "PATCH"]

-- Non-empty string
nonEmptyString :: Gen String
nonEmptyString = listOf1 arbitraryPrintableChar

-- Domain model
data Priority = Low | Medium | High | Critical deriving (Show, Eq, Enum, Bounded)

instance Arbitrary Priority where
  arbitrary = arbitraryBoundedEnum

-- Complex structure
data Order = Order
  { orderId :: Int
  , items :: [Item]
  , total :: Decimal
  } deriving (Show)

genOrder :: Gen Order
genOrder = do
  oid <- positiveInt
  itemCount <- chooseInt (1, 20)
  items <- vectorOf itemCount arbitrary
  let total = sum (map itemPrice items)
  return $ Order oid items total

Shrinking

When QuickCheck finds a failing case, it tries to shrink the input to the smallest failing example. This makes debugging much easier:

-- Without shrinking, you might get:
-- *** Failed! Input: [5, 3, 1, 4, 1, 5, 9, 2, 6]

-- With shrinking, QuickCheck finds the minimal case:
-- *** Failed! Input: [1, 0]

The shrink method returns smaller versions of a value:

instance Arbitrary Email where
  arbitrary = genEmail
  
  shrink (Email local domain) =
    -- Try shorter local parts
    [ Email l domain | l <- shrink local, not (null l) ]
    ++
    -- Try shorter domains
    [ Email local d | d <- shrink domain, '.' `elem` d ]

For newtype wrappers, genericShrink often works automatically:

{-# LANGUAGE DeriveGeneric #-}
import GHC.Generics

newtype UserId = UserId Int deriving (Show, Eq, Generic)

instance Arbitrary UserId where
  arbitrary = UserId <$> positiveInt
  shrink = genericShrink

Property Patterns

Round-Trip Properties

prop "JSON round-trips" :: User -> Bool
prop "JSON round-trips" user =
  (decode . encode) user == Just user

prop "Base64 encode/decode" :: ByteString -> Bool
prop "Base64 encode/decode" bs =
  (Base64.decode . Base64.encode) bs == Right bs

Idempotency

prop "sort is idempotent" :: [Int] -> Bool
prop "sort is idempotent" xs =
  sort (sort xs) == sort xs

prop "trim is idempotent" :: String -> Bool
prop "trim is idempotent" s =
  trim (trim s) == trim s

Commutativity and Associativity

prop "addition is commutative" :: Int -> Int -> Bool
prop "addition is commutative" x y = x + y == y + x

prop "list append is associative" :: [Int] -> [Int] -> [Int] -> Bool
prop "list append is associative" xs ys zs =
  (xs ++ ys) ++ zs == xs ++ (ys ++ zs)

Model-Based Testing

Compare a fast implementation against a known-correct (slow) reference:

-- Reference implementation: simple but slow
slowSearch :: Eq a => a -> [a] -> Maybe Int
slowSearch x xs = fmap fst $ find ((== x) . snd) (zip [0..] xs)

-- Optimized implementation
fastSearch :: Ord a => a -> [a] -> Maybe Int
fastSearch = binarySearch

prop "fast search matches slow search" :: Int -> [Int] -> Bool
prop "fast search matches slow search" x xs =
  let sorted = sort xs
  in fastSearch x sorted == slowSearch x sorted

Configuring QuickCheck

import Test.QuickCheck

-- Change number of tests
quickCheckWith stdArgs { maxSuccess = 1000 } prop_reverse

-- Within Hspec
modifyMaxSuccess (const 500) $ do
  prop "heavy property" $ \x -> ...

-- Within a single property
spec = do
  it "runs 1000 cases" $
    withMaxSuccess 1000 $ property $ \x -> ...

Configuration options:

  • maxSuccess — number of passing tests needed (default: 100)
  • maxDiscardRatio — ratio of discarded to generated tests
  • maxSize — maximum size parameter for generators
  • maxShrinks — maximum shrink steps

Hedgehog: A Modern Alternative

Hedgehog is a newer property testing library with integrated shrinking (no separate shrink method):

import Hedgehog
import qualified Hedgehog.Gen as Gen
import qualified Hedgehog.Range as Range

prop_reverseReverse :: Property
prop_reverseReverse = property $ do
  xs <- forAll $ Gen.list (Range.linear 0 100) Gen.int
  reverse (reverse xs) === xs

-- Hspec integration
import Test.Hspec.Hedgehog

spec :: Spec
spec = describe "List" $ do
  it "reverse . reverse == id" $ hedgehog prop_reverseReverse
  
  it "generated emails are valid" $ hedgehog $ property $ do
    email <- forAll genEmail
    isValid email === True

Hedgehog generators are explicit (no typeclass) — you always know exactly what data is being generated:

genEmail :: Gen Email
genEmail = do
  local <- Gen.text (Range.linear 1 20) Gen.alphaNum
  domain <- Gen.text (Range.linear 1 15) Gen.alpha
  tld <- Gen.element ["com", "org", "net", "io"]
  pure $ Email (T.unpack local) (T.unpack domain <> "." <> T.unpack tld)

Combining QuickCheck and Unit Tests

Mix property tests and unit tests freely in Hspec:

spec :: Spec
spec = do
  describe "validateEmail" $ do
    -- Unit tests for specific edge cases
    it "rejects empty string" $
      validateEmail "" `shouldBe` Left EmptyEmail

    it "rejects missing @" $
      validateEmail "notanemail" `shouldBe` Left MissingAtSign

    it "accepts standard email" $
      validateEmail "user@example.com" `shouldBe` Right (Email "user" "example.com")

    -- Property tests for general behavior
    prop "generated emails always validate" $
      \email -> validateEmail (renderEmail email) `shouldSatisfy` isRight

    prop "invalid emails always fail" $
      \badEmail -> validateEmail badEmail `shouldSatisfy` isLeft
      where
        badEmail = Gen.filter (not . isValidEmail) arbitrary

Common Pitfalls

Filtering too aggressively with suchThat:

-- ❌ Very slow — most generated integers fail the filter
arbitrary `suchThat` isPrime

-- ✅ Generate primes directly
primeGen :: Gen Int
primeGen = elements [2, 3, 5, 7, 11, 13, 17, 19, 23, 29]

Properties that are always true:

-- ❌ Trivially true — not testing what you think
prop "user is valid or not" :: User -> Bool
prop "user is valid or not" u = isValid u || not (isValid u)

Not writing a shrink instance:

Without shrink, QuickCheck reports the first failing input, which may be large and hard to debug. Always write shrink for custom types used in properties.

Summary

QuickCheck with Hspec gives you two complementary testing approaches:

  • Unit tests for specific known cases and edge cases you've identified
  • Property tests for general invariants that should hold for all inputs

The combination catches bugs that neither approach finds alone. Unit tests verify your known cases. Properties find the cases you didn't think of. The shrinking mechanism ensures that when properties fail, you get the smallest possible counterexample — not a random 50-element list, but the single value that breaks your code.

Start with simple properties like round-trips and idempotency, then build up to model-based testing as you identify more complex invariants.

Read more

Start now free