There is a monadic and a non-monadic API. This is the documentation for the monadic API. The monadic API is suitable for most use cases, and it is more stable than the non-monadic API.
For documentation on the non-monadic API look at Test.Hspec.
- type Specs = SpecM ()
- class Example a
- data Pending
- describe :: String -> Specs -> Specs
- it :: Example v => String -> v -> Specs
- pending :: String -> Pending
- hspec :: Specs -> IO [EvaluatedSpec]
- hspecB :: Specs -> IO Bool
- hspecX :: Specs -> IO a
- hHspec :: Handle -> Specs -> IO [EvaluatedSpec]
- runSpecM :: Specs -> [Spec]
- fromSpecList :: [Spec] -> Specs
- descriptions :: [Specs] -> Specs
import Test.Hspec.Monadic import Test.Hspec.QuickCheck import Test.Hspec.HUnit () import Test.QuickCheck import Test.HUnit main = hspecX 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
mySpecs = describe "unformatPhoneNumber" $ do
A boolean expression can act as a behavior's example.
it "removes dashes, spaces, and parenthesies" $ unformatPhoneNumber "(555) 555-1234" == "5555551234"
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"
it "removes the \"ext\" prefix of the extension" $ TestCase $ do let expected = "5555551234135" actual = unformatPhoneNumber "(555) 555-1234 ext 135" expected @?= actual
IO() action is treated like an HUnit
TestCase. (must import
it "converts letters to numbers" $ do let expected = "6862377" actual = unformatPhoneNumber "NUMBERS" actual @?= expected
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")
A type class for examples.
Defining a spec
A pending example.
If you want to report on a behavior but don't have an example yet, use this.
describe "fancyFormatter" $ do it "can format text in a way that everyone likes" $ pending
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
Create a document of the given specs and write it to stdout.
Create a document of the given specs and write it to the given handle.
writeReport filename specs = withFile filename WriteMode (\h -> hHspec h specs)