Safe Haskell	Safe-Infered

Test.Hspec.Core

Contents

Introduction
Types
Defining a spec
Running a spec
Internals

Description

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.

NOTE: There is a monadic and a non-monadic API. This is the documentation for the non-monadic API. The monadic API is more stable, so you may prefer it over this one. For documentation on the monadic API look at Test.Hspec.Monadic.

Synopsis

Introduction

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
 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 "(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 Test can act as a behavior's example. (must import Test.Hspec.HUnit)

   it "removes the \"ext\" prefix of the extension" $ TestCase $ do
     let expected = "5555551234135"
         actual   = unformatPhoneNumber "(555) 555-1234 ext 135"
     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"
         actual   = unformatPhoneNumber "NUMBERS"
     actual @?= expected
   ,

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

   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")

Types

data Spec

Internal representation of a spec.

type Specs = [Spec]

A list of specs.

class Example a where

A type class for examples.

To use an HUnit Test or an Assertion as an example you need to import Test.Hspec.HUnit.

To use a QuickCheck Property as an example you need to import Test.Hspec.QuickCheck.

Methods

evaluateExample :: a -> IO Result

Instances

Example Bool
Example Test
Example Assertion
Example Property
Example Result
Example Pending
Example (String -> Pending)

data Pending

A pending example.

Instances

Example Pending
Example (String -> Pending)

Defining a spec

describe :: String -> [Spec] -> Spec

The describe function combines a list of specs into a larger spec.

it :: Example a => String -> a -> 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)
   ]

pending :: String -> Pending

A pending example.

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
 ]

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

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

Running a spec

hspec :: Specs -> IO ()

Create a document of the given specs and write it to stdout.

Exit the program with exitSuccess if all examples passed, with exitFailure otherwise.

hspecB :: Specs -> IO Bool

Create a document of the given specs and write it to stdout.

Return True if all examples passed, False otherwise.

hHspec :: Handle -> Specs -> IO Summary

Create a document of the given specs and write it to the given handle.

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

data Summary

Summary of a test run.

Constructors

Summary
Fields summaryExamples :: Int summaryFailures :: Int

Instances

Eq Summary
Show Summary
Monoid Summary

Internals

quantify :: Int -> String -> String

Create a more readable display of a quantity of something.

Examples:

>>> quantify 0 "example"
"0 examples"

>>> quantify 1 "example"
"1 example"

>>> quantify 2 "example"
"2 examples"

data Result

The result of running an example.

Constructors

Success
Pending (Maybe String)
Fail String

Instances

Eq Result
Show Result
Example Result