# 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"
~~~