Test.Hspec.Meta

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

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.

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

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.

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

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 Test.Hspec.Core.Spec.Spec (aka Test.Hspec.Core.Hspec.SpecWith ()), which can be executed, and Test.Hspec.Core.Spec.SpecWith a, which cannot be executed without turning it into Test.Hspec.Core.Spec.Spec first.

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

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 is an alias for it.

context is an alias for describe.

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 marks all spec items of the given spec to be safe for parallel evaluation.

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

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

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

This can be used to temporarily disable a spec item.

xspecify is an alias for xit.

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

This can be used to temporarily disable spec items.

xcontext is an alias for xdescribe.

focus focuses all spec items of the given spec.

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

fit is an alias for fmap focus . it

fspecify is an alias for fit.

fdescribe is an alias for fmap focus . describe

fcontext is an alias for fdescribe.

An IO action that expects an argument of type a.

This type is what Examples are ultimately unlifted into for execution.

Run a custom action before every spec item.

Run a custom action before every spec item.

Run a custom action before every spec item.

Run a custom action before the first spec item.

Run a custom action before the first spec item.

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

Run a custom action after every spec item.

Run a custom action after every spec item.

Run a custom action after the last spec item.

Run a custom action after the last spec item.

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.

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

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

Wrap an action around the given spec.

Wrap an action around the given spec.

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

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.

Ignore the subject under test for a given spec.

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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.