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

Module documentation for 0.6.1.1

# Catchy combinators for HUnit

(inspired by [ScalaTest's ShouldMatchers](http://www.scalatest.org/))

The three main primitives are `shouldBe`, `shouldSatisfy` and
`shouldThrow`. They can be used with
[HUnit](http://hackage.haskell.org/package/HUnit), or any framework that
integrates with HUnit, like
[test-framework](http://hackage.haskell.org/package/test-framework) or
[Hspec](http://hackage.haskell.org/package/hspec).

## An introductory example

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

~~~ {.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
provided.

~~~ {.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
letter).

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