hspec-2.4.3: A Testing Framework for Haskell

Stability | stable
Safe Haskell | None
Language | Haskell2010

Test.Hspec

Contents

- Types
- Setting expectations
- Defining a spec
- Pending spec items
- 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
- it :: (HasCallStack, Example a) => String -> a -> SpecWith (Arg a)
- specify :: (HasCallStack, Example a) => String -> a -> SpecWith (Arg a)
- describe :: String -> SpecWith a -> SpecWith a
- context :: String -> SpecWith a -> SpecWith a
- example :: Expectation -> Expectation
- parallel :: SpecWith a -> SpecWith a
- runIO :: IO r -> SpecM a r
- pending :: Expectation
- pendingWith :: String -> Expectation
- xit :: (HasCallStack, Example a) => String -> a -> SpecWith (Arg a)
- xspecify :: (HasCallStack, Example a) => String -> a -> SpecWith (Arg a)
- xdescribe :: String -> SpecWith a -> SpecWith a
- xcontext :: String -> SpecWith a -> SpecWith a
- 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 Bool = ()
type Arg Property |
type Arg Property = ()
type Arg Result |
type Arg Result = ()
type Arg Expectation |
type Arg Expectation = ()
type Arg (a -> Property) |
type Arg (a -> Property) = a
type Arg (a -> Expectation) |
type Arg (a -> Expectation) = a
type Arg (a -> Bool) |
type Arg (a -> Bool) = a
type Arg (a -> Result) |
type Arg (a -> Result) = a

class Example e #

A type class for examples

Minimal complete definition

evaluateExample

Associated Types

type Arg e :: * #

Instances

Example Bool |
Associated Types type Arg Bool :: * # Methods evaluateExample :: Bool -> Params -> (ActionWith (Arg Bool) -> IO ()) -> ProgressCallback -> IO Result #
Example Property |
Associated Types type Arg Property :: * # Methods evaluateExample :: Property -> Params -> (ActionWith (Arg Property) -> IO ()) -> ProgressCallback -> IO Result #
Example Result |
Associated Types type Arg Result :: * # Methods evaluateExample :: Result -> Params -> (ActionWith (Arg Result) -> IO ()) -> ProgressCallback -> IO Result #
Example Expectation |
Associated Types type Arg Expectation :: * # Methods evaluateExample :: Expectation -> Params -> (ActionWith (Arg Expectation) -> IO ()) -> ProgressCallback -> IO Result #
Example (a -> Result) |
Associated Types type Arg (a -> Result) :: * # Methods evaluateExample :: (a -> Result) -> Params -> (ActionWith (Arg (a -> Result)) -> IO ()) -> ProgressCallback -> IO Result #
Example (a -> Bool) |
Associated Types type Arg (a -> Bool) :: * # Methods evaluateExample :: (a -> Bool) -> Params -> (ActionWith (Arg (a -> Bool)) -> IO ()) -> ProgressCallback -> IO Result #
Example (a -> Expectation) |
Associated Types type Arg (a -> Expectation) :: * # Methods evaluateExample :: (a -> Expectation) -> Params -> (ActionWith (Arg (a -> Expectation)) -> IO ()) -> ProgressCallback -> IO Result #
Example (a -> Property) |
Associated Types type Arg (a -> Property) :: * # Methods evaluateExample :: (a -> Property) -> Params -> (ActionWith (Arg (a -> Property)) -> IO ()) -> ProgressCallback -> IO Result #

# Setting expectations

module Test.Hspec.Expectations

# Defining a spec

it :: (HasCallStack, 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 :: (HasCallStack, Example a) => String -> a -> SpecWith (Arg a) #

`specify` is an alias for `it`.

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

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

context :: String -> SpecWith a -> SpecWith a #

`context` is an alias for `describe`.

example :: Expectation -> Expectation #

`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

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.

# Pending spec items

During a test run a pending spec item is:

1. not executed
2. reported as "pending"

pending :: Expectation #

`pending` can be used to mark a spec item as 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 the spec item is pending.

xit :: (HasCallStack, Example a) => String -> a -> SpecWith (Arg a) #

Changing `it` to `xit` marks the corresponding spec item as pending.

This can be used to temporarily disable a spec item.

xspecify :: (HasCallStack, Example a) => String -> a -> SpecWith (Arg a) #

`xspecify` is an alias for `xit`.

xdescribe :: String -> SpecWith a -> SpecWith a #

Changing `describe` to `xdescribe` marks all spec items of the corresponding subtree as pending.

This can be used to temporarily disable spec items.

xcontext :: String -> SpecWith a -> SpecWith a #

`xcontext` is an alias for `xdescribe`.

# 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.