hspec-meta-1.4.3: A version of Hspec which is used to test Hspec itself

Safe HaskellNone





The three functions you'll use the most are hspec, describe, and it. Here is an example of functions that format and unformat phone numbers and the specs for them.

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

 main :: IO ()
 main = hspec spec

Since the specs are often used to tell you what to implement, it's best to start with undefined functions. Once we have some specs, then you can implement each behavior one at a time, ensuring that each behavior is met and there is no undocumented behavior.

 unformatPhoneNumber :: String -> String
 unformatPhoneNumber = undefined

 formatPhoneNumber :: String -> String
 formatPhoneNumber = undefined

The describe function takes a list of behaviors and examples bound together with the it function

 spec :: Spec
 spec = do
   describe "unformatPhoneNumber" $ do

A Bool can be used as an example.

     it "removes dashes, spaces, and parenthesies" $
       unformatPhoneNumber "(555) 555-1234" == "5555551234"

The pending function marks a behavior as pending an example. The example doesn't count as failing.

     it "handles non-US phone numbers" $
       pending "need to look up how other cultures format phone numbers"

An HUnit Assertion can be used as an example.

     it "converts letters to numbers" $ do
       let expected = "6862377"
           actual   = unformatPhoneNumber "NUMBERS"
       actual @?= expected

A QuickCheck Property can be used as an example.

     it "can add and remove formatting without changing the number" $ property $
       forAll phoneNumber $ \n -> unformatPhoneNumber (formatPhoneNumber n) == n

 phoneNumber :: Gen String
 phoneNumber = do
   n <- elements [7,10,11,12,13,14,15]
   vectorOf n (elements "0123456789")


type Spec = SpecM ()Source

class Example a Source

A type class for examples.


Example Bool 
Example Test

This instance is deprecated, use fromHUnitTest instead!

Example Property 
Example Expectation 
Example Result 
Example Pending 
Example (String -> Pending) 

data Pending Source

A pending example.

Setting expectations

Defining a spec

describe :: String -> Spec -> SpecSource

Combine a list of specs into a larger spec.

context :: String -> Spec -> SpecSource

An alias for describe.

it :: Example v => String -> v -> SpecSource

Create a spec item.

A spec item consists of:

  • a textual description of a desired behavior
  • an example for that behavior
 describe "absolute" $ do
   it "returns a positive number when given a negative number" $
     absolute (-1) == 1

pending :: String -> PendingSource

A pending example.

If you want to textually specify a behavior but do not have an example yet, use this:

 describe "fancyFormatter" $ do
   it "can format text in a way that everyone likes" $

You can give an optional reason for why it's pending:

 describe "fancyFormatter" $ do
   it "can format text in a way that everyone likes" $
     pending "waiting for clarification from the designers"

Running a spec

hspec :: Spec -> IO ()Source

Run given spec and write a report to stdout. Exit with exitFailure if at least one spec item fails.

(see also hspecWith)