Test.Hspec

Hspec is a Behaviour-Driven Development tool for Haskell programmers. BDD is an approach to software development that combines Test-Driven Development, Domain Driven Design, and Acceptance Test-Driven Planning. Hspec helps you do the TDD part of that equation, focusing on the documentation and design aspects of TDD.

Hspec (and the preceding intro) are based on the Ruby library RSpec. Much of what applies to RSpec also applies to Hspec. Hspec ties together descriptions of behavior and examples of that behavior. The examples can also be run as tests and the output summarises what needs to be implemented.

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.Hspec.QuickCheck
 import Test.Hspec.HUnit
 import Test.QuickCheck hiding (property)
 import Test.HUnit

 main = hspec mySpecs

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 number = undefined

 formatPhoneNumber :: String -> String
 formatPhoneNumber number = undefined

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

 mySpecs = describe "unformatPhoneNumber" [

A boolean expression can act as a behavior's example.

   it "removes dashes, spaces, and parenthesies"
       (unformatPhoneNumber "[phone]" == "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 Test can act as a behavior's example. (must import Test.Hspec.HUnit)

   it "removes the \"ext\" prefix of the extension"
       (TestCase $ let expected = "5555551234135"
                       actual   = unformatPhoneNumber "[phone] ext 135"
                   in assertEqual "remove extension" expected actual),

An IO() action is treated like an HUnit TestCase. (must import Test.Hspec.HUnit)

   it "converts letters to numbers"
       (do
         let expected = "6862377"
         let actual   = unformatPhoneNumber "NUMBERS"
         assertEqual "letters to numbers" expected actual),

The property function allows a QuickCheck property to act as an example. (must import Test.Hspec.HUnit)

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

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

Documentation

data Spec

Everything needed to specify and show a specific behavior.

data Result

The result of running an example.

Instances

Eq Result

SpecVerifier Result

describe

Arguments

:: String

The name of what is being described, usually a function or type.

-> [IO (String, Result)]

A list of behaviors and examples, created by a list of it.

-> IO [Spec]

Create a set of specifications for a specific type being described. Once you know what you want specs for, use this.

 describe "abs" [
   it "returns a positive number given a negative number"
     (abs (-1) == 1)
   ]

it

Arguments

:: SpecVerifier a

=> String

A description of this behavior.

-> a

An example for this behavior.

-> IO (String, Result)

Create a description and example of a behavior, a list of these is used by describe. Once you know what you want to specify, use this.

 describe "closeEnough" [
   it "is true if two numbers are almost the same"
     (1.001 `closeEnough` 1.002),

   it "is false if two numbers are not almost the same"
     (not $ 1.001 `closeEnough` 1.003)
   ]

hspec :: IO [Spec] -> IO ()

Create a document of the given specs and write it to stdout. This does track how much time it took to check the examples. Use this if you want a description of each spec and do need to know how long it tacks to check the examples or want to write to stdout.

pending

Arguments

:: String

An explanation for why this behavior is pending.

-> Result

Declare an example as not successful or failing but pending some other work. If you want to report on a behavior but don't have an example yet, use this.

 describe "fancyFormatter" [
   it "can format text in a way that everyone likes"
     (pending "waiting for clarification from the designers")
   ]

descriptions :: [IO [Spec]] -> IO [Spec]

Combine a list of descriptions.

hHspec

Arguments

:: Handle

A handle for the stream you want to write to.

-> IO [Spec]

The specs you are interested in.

-> IO Bool

Create a document of the given specs and write it to the given handle. This does track how much time it took to check the examples. Use this if you want a description of each spec and do need to know how long it tacks to check the examples or want to write to a file or other handle.

 writeReport filename specs = withFile filename WriteMode (\ h -> hHspec h specs)

hspecX :: IO [Spec] -> IO a

Same as hspec except the program exits successfull if all examples ran without failures or with an errorcode of 1 if any examples failed.

hspecB :: IO [Spec] -> IO Bool

Same as hspec except it returns a bool indicating if all examples ran without failures

pureHspec

Arguments

:: [Spec]

The specs you are interested in.

-> [String]

Create a document of the given specs. This does not track how much time it took to check the examples. If you want a description of each spec and don't need to know how long it tacks to check, use this.

pureHspecB

Arguments

:: [Spec]

The specs you are interested in.

-> ([String], Bool)