hspec-2.2.1: A Testing Framework for Haskell

Stability | stable
Safe Haskell | None
Language | Haskell2010

Test.Hspec

Contents

- Types
- Setting expectations
- Defining a spec
- Hooks
- Running a spec

Description

Hspec is a testing framework for Haskell.

This is the library reference for Hspec. The User's Manual contains more in-depth documentation.

Synopsis

- type Spec = SpecWith ()
- type SpecWith a = SpecM a ()
- type family Arg e :: *
- class Example e where
  - type Arg e :: *
- module Test.Hspec.Expectations
- describe :: String -> SpecWith a -> SpecWith a
- context :: String -> SpecWith a -> SpecWith a
- it :: (?loc :: CallStack, Example a) => String -> a -> SpecWith (Arg a)
- specify :: Example a => String -> a -> SpecWith (Arg a)
- example :: Expectation -> Expectation
- pending :: Expectation
- pendingWith :: String -> Expectation
- parallel :: SpecWith a -> SpecWith a
- runIO :: IO r -> SpecM a r
- type ActionWith a = a -> IO ()
- before :: IO a -> SpecWith a -> Spec
- before_ :: IO () -> SpecWith a -> SpecWith a
- beforeWith :: (b -> IO a) -> SpecWith a -> SpecWith b
- beforeAll :: IO a -> SpecWith a -> Spec
- beforeAll_ :: IO () -> SpecWith a -> SpecWith a
- after :: ActionWith a -> SpecWith a -> SpecWith a
- after_ :: IO () -> SpecWith a -> SpecWith a
- afterAll :: ActionWith a -> SpecWith a -> SpecWith a
- afterAll_ :: IO () -> SpecWith a -> SpecWith a
- around :: (ActionWith a -> IO ()) -> SpecWith a -> Spec
- around_ :: (IO () -> IO ()) -> SpecWith a -> SpecWith a
- aroundWith :: (ActionWith a -> ActionWith b) -> SpecWith a -> SpecWith b
- hspec :: Spec -> IO ()

# Types

type Spec = SpecWith ()

type SpecWith a = SpecM a ()

type family Arg e :: *

Instances

type Arg Bool = () |
type Arg Property = () |
type Arg Result = () |
type Arg Expectation = () |
type Arg (a -> Property) = a |
type Arg (a -> Expectation) = a |

class Example e

A type class for examples

Minimal complete definition

evaluateExample

Associated Types

type Arg e :: *

Instances

Example Bool |
Example Property |
Example Result |
Example Expectation |
Example (a -> Expectation) |
Example (a -> Property) |

# Setting expectations

module Test.Hspec.Expectations

# Defining a spec

describe :: String -> SpecWith a -> SpecWith a

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

context :: String -> SpecWith a -> SpecWith a Source

`context` is an alias for `describe`.

it :: (?loc :: CallStack, Example a) => String -> a -> SpecWith (Arg a)

The `it` function creates a spec item.

A spec item consists of:

- a textual description of a desired behavior
- an example for that behavior

    describe "absolute" $ do
      it "returns a positive number when given a negative number" $
        absolute (-1) == 1

specify :: Example a => String -> a -> SpecWith (Arg a) Source

`specify` is an alias for `it`.

example :: Expectation -> Expectation Source

`example` is a type restricted version of `id`. It can be used to get better error messages on type mismatches.

Compare e.g.

    it "exposes some behavior" $ example $ do
      putStrLn

with

    it "exposes some behavior" $ do
      putStrLn

pending :: Expectation

`pending` can be used to indicate that an example is pending.

If you want to textually specify a behavior but do not have an example yet, use this:

    describe "fancyFormatter" $ do
      it "can format text in a way that everyone likes" $
        pending

pendingWith :: String -> Expectation

`pendingWith` is similar to `pending`, but it takes an additional string argument that can be used to specify the reason for why it's pending.

parallel :: SpecWith a -> SpecWith a

`parallel` marks all spec items of the given spec to be safe for parallel evaluation.

runIO :: IO r -> SpecM a r

Run an IO action while constructing the spec tree.

`SpecM` is a monad to construct a spec tree, without executing any spec items. `runIO` allows you to run IO actions during this construction phase. The IO action is always run when the spec tree is constructed (e.g. even when `--dry-run` is specified). If you do not need the result of the IO action to construct the spec tree, `beforeAll` may be more suitable for your use case.

# Hooks

type ActionWith a = a -> IO ()

An `IO` action that expects an argument of type `a`

before :: IO a -> SpecWith a -> Spec

Run a custom action before every spec item.

before_ :: IO () -> SpecWith a -> SpecWith a

Run a custom action before every spec item.

beforeWith :: (b -> IO a) -> SpecWith a -> SpecWith b

Run a custom action before every spec item.

beforeAll :: IO a -> SpecWith a -> Spec

Run a custom action before the first spec item.

beforeAll_ :: IO () -> SpecWith a -> SpecWith a

Run a custom action before the first spec item.

after :: ActionWith a -> SpecWith a -> SpecWith a

Run a custom action after every spec item.

after_ :: IO () -> SpecWith a -> SpecWith a

Run a custom action after every spec item.

afterAll :: ActionWith a -> SpecWith a -> SpecWith a

Run a custom action after the last spec item.

afterAll_ :: IO () -> SpecWith a -> SpecWith a

Run a custom action after the last spec item.

around :: (ActionWith a -> IO ()) -> SpecWith a -> Spec

Run a custom action before and/or after every spec item.

around_ :: (IO () -> IO ()) -> SpecWith a -> SpecWith a

Run a custom action before and/or after every spec item.

aroundWith :: (ActionWith a -> ActionWith b) -> SpecWith a -> SpecWith b

Run a custom action before and/or after every spec item.

# Running a spec

hspec :: Spec -> IO ()

Run given spec and write a report to `stdout`. Exit with `exitFailure` if at least one spec item fails.