hspec aims to be a simple, extendable, and useful tool for Behavior Driven Development in Haskell.


Step 1, write descriptions and examples of your desired behavior
> module Myabs where
>
> specs :: IO Specs
> specs = describe "myabs" [
>   it "returns the original number when given a positive input"
>     (myabs 1 == 1),
> 
>   it "returns a positive number when given a negative input"
>     (myabs (-1) == 1),
> 
>   it "returns zero when given zero"
>     (myabs 0 == 0)
>   ]

Step 2, write whatever you are describing
> myabs n = undefined

Step 3, watch your examples fail with red text by running from the .hs file itself
> main = hspec specs

myabs
 x returns the original number when given a positive input FAILED [1]
 x returns a positive number when given a negative input FAILED [2]
 x returns zero when given zero FAILED [3]

1) myabs returns the original number when given a positive input FAILED
Prelude.undefined

2) myabs returns a positive number when given a negative input FAILED
Prelude.undefined

3) myabs returns zero when given zero FAILED
Prelude.undefined

Finished in 0.0002 seconds

3 examples, 3 failures


Specs can also be run from the command line using the hspec program
  $ hspec myabs.hs

Step 4, implement your desired behavior
> myabs n = if n < 0 then negate n else n

Step 5, watch your examples pass with green text when rerun
myabs
 - returns the original number when given a positive input
 - returns a positive number when given a negative input
 - returns zero when given zero

Finished in 0.0000 seconds

3 examples, 0 failures




Here's the report of hspec's behavior:


the "describe" function
 - takes a description of what the behavior is for
 - groups behaviors for what's being described

  a nested description
   - has it's own specs
   - may be displayed indented

the "it" function
 - takes a description of a desired behavior
 - takes an example of that behavior
 - can use a Bool, HUnit Test, QuickCheck property, or "pending" as an example
 - will treat exceptions as failures

the "hspec" function
 - displays a header for each thing being described
 - displays one row for each behavior
 - displays a '-' for successfull examples
 - displays an 'x' for failed examples
 - displays a detailed list of failed examples
 - displays a '-' for pending examples
 - displays a '#' and an additional message for pending examples
 - summarizes the time it takes to finish
 - summarizes the number of examples and failures
 - outputs failed examples in red, pending in yellow, and passing in green

Bool as an example
 - is just an expression that evaluates to a Bool

HUnit TestCase as an example
 - is specified with the HUnit "TestCase" data constructor
 - is the assumed example for IO() actions
 - will show the failed assertion text if available (e.g. assertBool)
 - will show the failed assertion expected and actual values if available (e.g. assertEqual)

QuickCheck property as an example
 - is specified with the "property" function
 - will show what falsified it

pending as an example
 - is specified with the "pending" function and an explanation
 - accepts a message to display in the report

the "hHspecWithFormat" function
 - can use the "silent" formatter to show no output
 - can use the "progress" formatter to show '..F...FF.F' style output
 - can use the "specdoc" formatter to show all examples (default)
 - can use the "failed_examples" formatter to show only failed examples

quantify (an internal function)
 - returns an amount and a word given an amount and word
 - returns a singular word given the number 1
 - returns a plural word given a number greater than 1
 - returns a plural word given the number 0

Finished in 0.0489 seconds

35 examples, 0 failures