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_reverseReverseOutput: +++ 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) == sprop 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] -- optionalBuilt-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 emailGenerators
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 xsPractical 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 totalShrinking
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 = genericShrinkProperty 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 bsIdempotency
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 sCommutativity 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 sortedConfiguring 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 testsmaxSize— maximum size parameter for generatorsmaxShrinks— 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 === TrueHedgehog 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) arbitraryCommon 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.