Test.Hspec.Meta

Types

type Spec = SpecWith ()

type SpecWith a = SpecM a ()

type family Arg e

Instances

type Arg Bool

Defined in Test.Hspec.Core.Example

type Arg Bool = ()

type Arg Property

Defined in Test.Hspec.Core.Example

type Arg Property = ()

type Arg Expectation

Defined in Test.Hspec.Core.Example

type Arg Expectation = ()

type Arg (a -> Property)

Defined in Test.Hspec.Core.Example

type Arg (a -> Property) = a

type Arg (a -> Expectation)

Defined in Test.Hspec.Core.Example

type Arg (a -> Expectation) = a

type Arg (a -> Bool)

Defined in Test.Hspec.Core.Example

type Arg (a -> Bool) = a

class Example e

A type class for examples

Minimal complete definition

evaluateExample

Instances

Example Bool

Defined in Test.Hspec.Core.Example

Associated Types

type Arg Bool

Methods

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

Example Property

Defined in Test.Hspec.Core.Example

Associated Types

type Arg Property

Methods

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

Example Expectation

Defined in Test.Hspec.Core.Example

Associated Types

type Arg Expectation

Methods

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

Example (a -> Property)

Defined in Test.Hspec.Core.Example

Associated Types

type Arg (a -> Property)

Methods

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

Example (a -> Expectation)

Defined in Test.Hspec.Core.Example

Associated Types

type Arg (a -> Expectation)

Methods

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

Example (a -> Bool)

Defined in Test.Hspec.Core.Example

Associated Types

type Arg (a -> Bool)

Methods

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

Setting expectations

Setting expectations

type Expectation = Assertion

expectationFailure :: HasCallStack => String -> Expectation

shouldBe :: (HasCallStack, Show a, Eq a) => a -> a -> Expectation infix 1

actual `shouldBe` expected sets the expectation that actual is equal to expected.

shouldSatisfy :: (HasCallStack, Show a) => a -> (a -> Bool) -> Expectation infix 1

v `shouldSatisfy` p sets the expectation that p v is True.

shouldStartWith :: (HasCallStack, Show a, Eq a) => [a] -> [a] -> Expectation infix 1

list `shouldStartWith` prefix sets the expectation that list starts with prefix,

shouldEndWith :: (HasCallStack, Show a, Eq a) => [a] -> [a] -> Expectation infix 1

list `shouldEndWith` suffix sets the expectation that list ends with suffix,

shouldContain :: (HasCallStack, Show a, Eq a) => [a] -> [a] -> Expectation infix 1

list `shouldContain` sublist sets the expectation that sublist is contained, wholly and intact, anywhere in list.

shouldMatchList :: (HasCallStack, Show a, Eq a) => [a] -> [a] -> Expectation infix 1

xs `shouldMatchList` ys sets the expectation that xs has the same elements that ys has, possibly in another order

shouldReturn :: (HasCallStack, Show a, Eq a) => IO a -> a -> Expectation infix 1

action `shouldReturn` expected sets the expectation that action returns expected.

shouldNotBe :: (HasCallStack, Show a, Eq a) => a -> a -> Expectation infix 1

actual `shouldNotBe` notExpected sets the expectation that actual is not equal to notExpected

shouldNotSatisfy :: (HasCallStack, Show a) => a -> (a -> Bool) -> Expectation infix 1

v `shouldNotSatisfy` p sets the expectation that p v is False.

shouldNotContain :: (HasCallStack, Show a, Eq a) => [a] -> [a] -> Expectation infix 1

list `shouldNotContain` sublist sets the expectation that sublist is not contained anywhere in list.

shouldNotReturn :: (HasCallStack, Show a, Eq a) => IO a -> a -> Expectation infix 1

action `shouldNotReturn` notExpected sets the expectation that action does not return notExpected.

Expecting exceptions

shouldThrow :: (HasCallStack, Exception e) => IO a -> Selector e -> Expectation infix 1

action `shouldThrow` selector sets the expectation that action throws an exception. The precise nature of the expected exception is described with a Selector.

Selecting exceptions

type Selector a = a -> Bool

A Selector is a predicate; it can simultaneously constrain the type and value of an exception.

Predefined type-based selectors

There are predefined selectors for some standard exceptions. Each selector is just const True with an appropriate type.

anyException :: Selector SomeException

anyErrorCall :: Selector ErrorCall

anyIOException :: Selector IOException

anyArithException :: Selector ArithException

Combinators for defining value-based selectors

Some exceptions (most prominently ErrorCall) have no Eq instance. Selecting a specific value would require pattern matching.

For such exceptions, combinators that construct selectors are provided. Each combinator corresponds to a constructor; it takes the same arguments, and has the same name (but starting with a lower-case letter).

errorCall :: String -> Selector ErrorCall

Re-exports

type HasCallStack = ?callStack :: CallStack

Request a CallStack.

NOTE: The implicit parameter ?callStack :: CallStack is an implementation detail and should not be considered part of the CallStack API, we may decide to change the implementation in the future.

Since: base-4.9.0.0

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 :: HasCallStack => String -> SpecWith a -> SpecWith a

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

context :: HasCallStack => 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 :: HasCallStack => 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 :: HasCallStack => 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 :: HasCallStack => 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 :: HasCallStack => String -> SpecWith a -> SpecWith a

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

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)

fit is an alias for fmap focus . it

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

fspecify is an alias for fit.

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

fdescribe is an alias for fmap focus . describe

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

fcontext is an alias for fdescribe.

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.

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

Run a custom action with an argument 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 :: HasCallStack => ActionWith a -> SpecWith a -> SpecWith a

Run a custom action after the last spec item.

afterAll_ :: HasCallStack => 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.

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

Wrap an action around the given spec.

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

Wrap an action around the given spec.

aroundAllWith :: forall a b. (ActionWith a -> ActionWith b) -> SpecWith a -> SpecWith b

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

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

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

Ignore the subject under test for a given spec.

Running a spec

hspec :: Spec -> IO ()

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.

type Spec = SpecWith ()

hspec :: Spec -> IO ()

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.

class IsFormatter a where

Methods

toFormatter :: a -> IO Formatter

hspecWithFormatter :: IsFormatter a => a -> Spec -> IO ()

postProcessSpec :: FilePath -> Spec -> Spec

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

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

hspecResult :: Spec -> IO Summary

Run given spec and returns a summary of the test run.

Note: hspecResult does not exit with exitFailure on failing spec items. If you need this, you have to check the Summary yourself and act accordingly.