hspec-2.6.1: 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 ()
- type family Arg e :: Type
- class Example 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
- 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 :: 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 () Source #

type SpecWith a = SpecM a () Source #

type family Arg e :: Type Source #

Instances

type Arg Bool |
Instance details Defined in Test.Hspec.Core.Example type Arg Bool = ()
type Arg Property |
Instance details Defined in Test.Hspec.Core.Example 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 (a -> Property) |
Instance details Defined in Test.Hspec.Core.Example type Arg (a -> Property) = 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
type Arg (a -> Result) |
Instance details Defined in Test.Hspec.Core.Example type Arg (a -> Result) = a

class Example e Source #

A type class for examples

Minimal complete definition

evaluateExample

Instances

Example Bool |
Instance details Defined in Test.Hspec.Core.Example Associated Types type Arg Bool :: Type Source # Methods evaluateExample :: Bool -> Params -> (ActionWith (Arg Bool) -> IO ()) -> ProgressCallback -> IO Result Source #
Example Property |
Instance details Defined in Test.Hspec.Core.Example Associated Types type Arg Property :: Type Source # 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 :: Type Source # 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 :: Type Source # Methods evaluateExample :: Expectation -> Params -> (ActionWith (Arg Expectation) -> IO ()) -> ProgressCallback -> IO Result Source #
Example (a -> Result) |
Instance details Defined in Test.Hspec.Core.Example Associated Types type Arg (a -> Result) :: Type Source # Methods evaluateExample :: (a -> Result) -> Params -> (ActionWith (Arg (a -> Result)) -> IO ()) -> ProgressCallback -> IO Result Source #
Example (a -> Bool) |
Instance details Defined in Test.Hspec.Core.Example Associated Types type Arg (a -> Bool) :: Type Source # Methods evaluateExample :: (a -> Bool) -> Params -> (ActionWith (Arg (a -> Bool)) -> IO ()) -> ProgressCallback -> IO Result Source #
Example (a -> Expectation) |
Instance details Defined in Test.Hspec.Core.Example Associated Types type Arg (a -> Expectation) :: Type Source # Methods evaluateExample :: (a -> Expectation) -> Params -> (ActionWith (Arg (a -> Expectation)) -> IO ()) -> ProgressCallback -> IO Result Source #
Example (a -> Property) |
Instance details Defined in Test.Hspec.Core.Example Associated Types type Arg (a -> Property) :: Type Source # Methods evaluateExample :: (a -> Property) -> Params -> (ActionWith (Arg (a -> Property)) -> IO ()) -> ProgressCallback -> IO Result Source #

# 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

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.

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

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 :: IO a -> SpecWith a -> Spec Source #

Run a custom action before the first spec item.

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

Run a custom action 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 :: ActionWith a -> SpecWith a -> SpecWith a Source #

Run a custom action after the last spec item.

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

Run a custom action after the last spec item.

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

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

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.

# 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 desired. Use `runSpec` if you need more control over these aspects.