This module contains the runners that take a set of specs, specified in a monadic style, evaluate their examples, and report to a given handle.
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 = hspecX $ do
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
describe "unformatPhoneNumber" $ do
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 $ let expected = "5555551234135" actual = unformatPhoneNumber "(555) 555-1234 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")
- data Spec
- data Result
- type Specs = Writer [IO [IO Spec]] ()
- describe :: String -> Writer [ItSpec] () -> Specs
- it :: SpecVerifier v => String -> v -> Writer [ItSpec] ()
- hspec :: Specs -> IO [Spec]
- hspecB :: Specs -> IO Bool
- hspecX :: Specs -> IO a
- pending :: String -> Result
- descriptions :: [Specs] -> Specs
- hHspec :: Handle -> Specs -> IO [Spec]
- type ItSpec = IO (String, Result)
Documentation
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 :: [Specs] -> SpecsSource
Combine a list of descriptions. (Note that descriptions can also be combined with monadic sequencing.)