MIT licensed and maintained by Simon Hengel
This version can be pinned in stack with:hspec-expectations-,1320

Module documentation for

  • Test
    • Test.Hspec
      • Test.Hspec.Expectations
        • Test.Hspec.Expectations.Contrib
Depends on 2 packages(full list with versions):
Used by 4 packages in lts-0.7(full list with versions):
# Catchy combinators for HUnit

(inspired by [ScalaTest's ShouldMatchers](

The three main primitives are `shouldBe`, `shouldSatisfy` and
`shouldThrow`. They can be used with
[HUnit](, or any framework that
integrates with HUnit, like
[test-framework]( or

## An introductory example

Here is an example that uses Hspec. It's a partial specification of

~~~ {.haskell .literate}
import Test.Hspec
import Control.Exception

main :: IO ()
main = hspec $ do
describe "shouldBe" $ do
it "asserts equality" $ do
"foo" `shouldBe` "foo"

describe "shouldSatisfy" $ do
it "asserts that a predicate holds" $ do
"bar" `shouldSatisfy` (not . null)

describe "shouldThrow" $ do
it "asserts that an exception is thrown" $ do
evaluate (1 `div` 0 :: Int) `shouldThrow` (== DivideByZero)

## shouldBe

`shouldBe` is just an alias for HUnit's `@?=`.

## shouldSatisfy

`shouldSatisfy` asserts that some predicate holds for a given value.

~~~ {.haskell}
"bar" `shouldSatisfy` (not . null)

It is similar to HUnit's `assertBool`, but gives a useful error message.

>>> 23 `shouldSatisfy` (> 42)
*** Exception: HUnitFailure "23 did not satisfy predicate!"

## shouldReturn

`shouldReturn` asserts that an action returns a given value.

~~~ {.haskell}
launchMissiles `shouldReturn` Left "permission error"

## shouldThrow

`shouldThrow` asserts that an exception is thrown. The precise nature of
that exception is described with a `Selector`.

~~~ {.haskell}
error "foobar" `shouldThrow` anyException

A `Selector` is a predicate, it can simultaneously constrain the type
and value of an exception.

~~~ {.haskell}
throw DivideByZero `shouldThrow` (== DivideByZero)

To select all exceptions of a given type, `const True` can be used.

~~~ {.haskell}
error "foobar" `shouldThrow` (const True :: Selector ErrorCall)

For convenience, predefined selectors for some standard exceptions are

~~~ {.haskell}
error "foobar" `shouldThrow` anyErrorCall

Some exceptions (like `ErrorCall`) have no `Eq` instance, so checking
for a specific value requires pattern matching.

~~~ {.haskell}
error "foobar" `shouldThrow` (\e -> case e of
ErrorCall "foobar" -> True
_ -> False

For such exceptions, combinators that construct selectors are provided.
Each combinator corresponds to a constructor; it takes the same
arguments, and has the same name (but starting with a lower-case

~~~ {.haskell}
error "foobar" `shouldThrow` errorCall "foobar"