hspec-2.11.16: A Testing Framework for Haskell

Stability | stable
Safe Haskell | None
Language | Haskell2010

Test.Hspec

Contents

- Types
- Setting expectations
- Defining a spec
- Pending spec items
- Focused 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 ()
- class Example e
- type family 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 :: HasCallStack => String -> SpecWith a -> SpecWith a
- context :: HasCallStack => String -> SpecWith a -> SpecWith a
- example :: Expectation -> Expectation
- parallel :: SpecWith a -> SpecWith a
- sequential :: SpecWith a -> SpecWith a
- runIO :: IO r -> SpecM a r
- pending :: HasCallStack => Expectation
- pendingWith :: HasCallStack => String -> Expectation
- xit :: (HasCallStack, Example a) => String -> a -> SpecWith (Arg a)
- xspecify :: (HasCallStack, Example a) => String -> a -> SpecWith (Arg a)
- xdescribe :: HasCallStack => String -> SpecWith a -> SpecWith a
- xcontext :: HasCallStack => String -> SpecWith a -> SpecWith a
- focus :: SpecWith a -> SpecWith a
- fit :: (HasCallStack, Example a) => String -> a -> SpecWith (Arg a)
- fspecify :: (HasCallStack, Example a) => String -> a -> SpecWith (Arg a)
- fdescribe :: HasCallStack => String -> SpecWith a -> SpecWith a
- fcontext :: HasCallStack => 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 :: HasCallStack => IO a -> SpecWith a -> Spec
- beforeAll_ :: HasCallStack => IO () -> SpecWith a -> SpecWith a
- beforeAllWith :: HasCallStack => (b -> IO a) -> SpecWith a -> SpecWith b
- after :: ActionWith a -> SpecWith a -> SpecWith a
- after_ :: IO () -> SpecWith a -> SpecWith a
- afterAll :: HasCallStack => ActionWith a -> SpecWith a -> SpecWith a
- afterAll_ :: HasCallStack => 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
- aroundAll :: HasCallStack => (ActionWith a -> IO ()) -> SpecWith a -> Spec
- aroundAll_ :: HasCallStack => (IO () -> IO ()) -> SpecWith a -> SpecWith a
- aroundAllWith :: HasCallStack => (ActionWith a -> ActionWith b) -> SpecWith a -> SpecWith b
- mapSubject :: (b -> a) -> SpecWith a -> SpecWith b
- ignoreSubject :: SpecWith () -> SpecWith a
- hspec :: Spec -> IO ()

# Types

type Spec = SpecWith () Source #

A `SpecWith` that can be evaluated directly by the `hspec` function as it does not require any parameters.

type SpecWith a = SpecM a () Source #

A ``SpecWith` a` represents a test or group of tests that require an `a` value to run.

In the common case, a `Spec` is a ``SpecWith` ()` which requires `()` and can thus be executed with `hspec`.

To supply an argument to `SpecWith` tests to turn them into `Spec`, use functions from Test.Hspec.Core.Hooks such as `around`, `before`, `mapSubject` and similar.

Values of this type are created by `it`, `describe` and similar.

class Example e Source #

A type class for examples, that is to say, test bodies as used in `it` and similar functions.

Minimal complete definition

evaluateExample

#### Instances

Instances details

Example Property |

Instance details

Defined in Test.Hspec.Core.QuickCheck

Associated Types

type Arg Property |
Instance details Defined in Test.Hspec.Core.QuickCheck type Arg Property = ()

Methods

evaluateExample :: Property -> Params -> (ActionWith (Arg Property) -> IO ()) -> ProgressCallback -> IO Result Source #

Example Result |

Instance details

Defined in Test.Hspec.Core.Example

Associated Types

type Arg Result |
Instance details Defined in Test.Hspec.Core.Example type Arg Result = ()

Methods

evaluateExample :: Result -> Params -> (ActionWith (Arg Result) -> IO ()) -> ProgressCallback -> IO Result Source #

Example Expectation |

Instance details

Defined in Test.Hspec.Core.Example

Associated Types

type Arg Expectation |
Instance details Defined in Test.Hspec.Core.Example type Arg Expectation = ()

Methods

evaluateExample :: Expectation -> Params -> (ActionWith (Arg Expectation) -> IO ()) -> ProgressCallback -> IO Result Source #

Example Bool |

Instance details

Defined in Test.Hspec.Core.Example

Associated Types

type Arg Bool |
Instance details Defined in Test.Hspec.Core.Example type Arg Bool = ()

Methods

evaluateExample :: Bool -> Params -> (ActionWith (Arg Bool) -> IO ()) -> ProgressCallback -> IO Result Source #

Example (a -> Property) |

Instance details

Defined in Test.Hspec.Core.QuickCheck

Associated Types

type Arg (a -> Property) |
Instance details Defined in Test.Hspec.Core.QuickCheck type Arg (a -> Property) = a

Methods

evaluateExample :: (a -> Property) -> Params -> (ActionWith (Arg (a -> Property)) -> IO ()) -> ProgressCallback -> IO Result Source #

Example (a -> Result) |

Instance details

Defined in Test.Hspec.Core.Example

Associated Types

type Arg (a -> Result) |
Instance details Defined in Test.Hspec.Core.Example type Arg (a -> Result) = a

Methods

evaluateExample :: (a -> Result) -> Params -> (ActionWith (Arg (a -> Result)) -> IO ()) -> ProgressCallback -> IO Result Source #

Example (a -> Expectation) |

Instance details

Defined in Test.Hspec.Core.Example

Associated Types

type Arg (a -> Expectation) |
Instance details Defined in Test.Hspec.Core.Example type Arg (a -> Expectation) = a

Methods

evaluateExample :: (a -> Expectation) -> Params -> (ActionWith (Arg (a -> Expectation)) -> IO ()) -> ProgressCallback -> IO Result Source #

Example (a -> Bool) |

Instance details

Defined in Test.Hspec.Core.Example

Associated Types

type Arg (a -> Bool) |
Instance details Defined in Test.Hspec.Core.Example type Arg (a -> Bool) = a

Methods

evaluateExample :: (a -> Bool) -> Params -> (ActionWith (Arg (a -> Bool)) -> IO ()) -> ProgressCallback -> IO Result Source #

type family Arg e Source #

The argument type that is needed to run this `Example`. If `Arg` is `()`, no argument is required and the `Example` can be run as-is.

The value of `Arg` is the difference between `Spec` (aka ``SpecWith` ()`), which can be executed, and ``SpecWith` a`, which cannot be executed without turning it into `Spec` first.

To supply an argument to examples, use the functions in Test.Hspec.Core.Hooks such as `around`, `before`, `mapSubject` and similar.

#### Instances

Instances details

type Arg Property |
Instance details Defined in Test.Hspec.Core.QuickCheck type Arg Property = ()
type Arg Result |
Instance details Defined in Test.Hspec.Core.Example type Arg Result = ()
type Arg Expectation |
Instance details Defined in Test.Hspec.Core.Example type Arg Expectation = ()
type Arg Bool |
Instance details Defined in Test.Hspec.Core.Example type Arg Bool = ()
type Arg (a -> Property) |
Instance details Defined in Test.Hspec.Core.QuickCheck type Arg (a -> Property) = a
type Arg (a -> Result) |
Instance details Defined in Test.Hspec.Core.Example type Arg (a -> Result) = a
type Arg (a -> Expectation) |
Instance details Defined in Test.Hspec.Core.Example type Arg (a -> Expectation) = a
type Arg (a -> Bool) |
Instance details Defined in Test.Hspec.Core.Example type Arg (a -> Bool) = a

# Setting expectations

module Test.Hspec.Expectations

# Defining a spec

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

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

``Example` a` optionally accepts an argument ``Arg` a`, which is then given to the test body. This is useful for provisioning resources for a test which are created and cleaned up outside the test itself. See `Arg` for details.

Note that this function is often on the scene of nasty type errors due to GHC failing to infer the type of `do` notation in the test body. It can be helpful to use TypeApplications to explicitly specify the intended `Example` type.

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

`specify` is an alias for `it`.

describe :: HasCallStack => String -> SpecWith a -> SpecWith a Source #

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

context :: HasCallStack => String -> SpecWith a -> SpecWith a Source #

`context` is an alias for `describe`.

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

parallel :: SpecWith a -> SpecWith a Source #

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

sequential :: SpecWith a -> SpecWith a Source #

`sequential` marks all spec items of the given spec to be evaluated sequentially.

runIO :: IO r -> SpecM a r Source #

Run an IO action while constructing the spec tree.

`SpecM` is a monad to construct a spec tree, without executing any spec items itself. `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 :: HasCallStack => Expectation Source #

`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 :: HasCallStack => String -> Expectation Source #

`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) Source #

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) Source #

`xspecify` is an alias for `xit`.

xdescribe :: HasCallStack => String -> SpecWith a -> SpecWith a Source #

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

This can be used to temporarily disable spec items.

xcontext :: HasCallStack => String -> SpecWith a -> SpecWith a Source #

`xcontext` is an alias for `xdescribe`.

# Focused spec items

During a test run, when a spec contains focused spec items, all other spec items are ignored.

focus :: SpecWith a -> SpecWith a Source #

`focus` focuses all spec items of the given spec.

Applying `focus` to a spec with focused spec items has no effect.

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

`fit` is an alias for `fmap focus . it`

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

`fspecify` is an alias for `fit`.

fdescribe :: HasCallStack => String -> SpecWith a -> SpecWith a Source #

`fdescribe` is an alias for `fmap focus . describe`

fcontext :: HasCallStack => String -> SpecWith a -> SpecWith a Source #

`fcontext` is an alias for `fdescribe`.

# Hooks

type ActionWith a = a -> IO () Source #

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

This type is what `Example`s are ultimately unlifted into for execution.

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

Run a custom action before every spec item.

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

Run a custom action before every spec item.

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

Run a custom action before every spec item.

beforeAll :: HasCallStack => IO a -> SpecWith a -> Spec Source #

Run a custom action before the first spec item.

beforeAll_ :: HasCallStack => IO () -> SpecWith a -> SpecWith a Source #

Run a custom action before the first spec item.

beforeAllWith :: HasCallStack => (b -> IO a) -> SpecWith a -> SpecWith b Source #

Run a custom action with an argument before the first spec item.

after :: ActionWith a -> SpecWith a -> SpecWith a Source #

Run a custom action after every spec item.

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

Run a custom action after every spec item.

afterAll :: HasCallStack => ActionWith a -> SpecWith a -> SpecWith a Source #

Run a custom action after the last spec item.

afterAll_ :: HasCallStack => IO () -> SpecWith a -> SpecWith a Source #

Run a custom action after the last spec item.

around Source #

Arguments

:: (ActionWith a -> IO ()) | Function provided with an action to run the spec item as argument. It should return the action to actually execute the item.
-> SpecWith a | Spec to modify
-> Spec |

Run a custom action before and/or after every spec item, supplying it with an argument obtained via IO.

This is useful for tasks like creating a file handle or similar resource before a test and destroying it after the test.

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

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

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

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

aroundAll :: HasCallStack => (ActionWith a -> IO ()) -> SpecWith a -> Spec Source #

Wrap an action around the given spec.

aroundAll_ :: HasCallStack => (IO () -> IO ()) -> SpecWith a -> SpecWith a Source #

Wrap an action around the given spec.

aroundAllWith :: HasCallStack => (ActionWith a -> ActionWith b) -> SpecWith a -> SpecWith b Source #

Wrap an action around the given spec. Changes the arg type inside.

mapSubject :: (b -> a) -> SpecWith a -> SpecWith b Source #

Modify the subject under test.

Note that this resembles a contravariant functor on the first type parameter of `SpecM`. This is because the subject is passed inwards, as an argument to the spec item.

ignoreSubject :: SpecWith () -> SpecWith a Source #

Ignore the subject under test for a given spec.

# Running a spec

hspec :: Spec -> IO () Source #

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

Note: `hspec` handles command-line options and reads config files. This is not always desirable. Use `evalSpec` and `runSpecForest` if you need more control over these aspects.