Stability	unstable
Safe Haskell	None
Language	Haskell2010

Test.Hspec.Core.Extension

Contents

Description

Warning: This API is experimental.

Synopsis

runIO :: IO r -> SpecM a r
modifyConfig :: (Config -> Config) -> SpecWith a
data Option
registerOptions :: HasCallStack => [Option] -> SpecWith a
registerTransformation :: (Config -> [SpecTree] -> [SpecTree]) -> SpecWith a
data Config
data Item a
data SpecM a r
type SpecWith a = SpecM a ()
type SpecTree = SpecTree ()

Lifecycle of a test run

A test run goes through four distinct phases:

A tree of spec items and a default Config are constructed in SpecM.
Command-line options are parsed. This transforms the default Config that was constructed in phase 1.
The tree of spec items is transformed in various ways, depending on specific Config values.
Each spec item is executed and its result is reported to the user.

An extension can directly influence phase 1, and indirectly influence phases 2-4.

When writing extensions the following imports are recommended:

import Test.Hspec.Core.Extension
import Test.Hspec.Core.Extension.Config qualified as Config
import Test.Hspec.Core.Extension.Option qualified as Option
import Test.Hspec.Core.Extension.Item qualified as Item
import Test.Hspec.Core.Extension.Spec qualified as Spec
import Test.Hspec.Core.Extension.Tree qualified as Tree

Phase 1: Constructing a spec tree

An extension can use Spec.mapItems to transform spec items in phase 1.
- Item.setAnnotation can be used to add custom metadata to a spec Item.
An extension can use modifyConfig to modify the default config.
- Config.setAnnotation can be used to add custom metadata to the default Config.

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.

modifyConfig :: (Config -> Config) -> SpecWith a Source #

Since: 2.10.0

Phase 2: Parsing command-line options

An extension can use registerOptions during phase 1 to register custom command-line options, and as a consequence indirectly influence this phase.

Options can use Config.setAnnotation to add custom metadata to the Config.

data Option Source #

registerOptions :: HasCallStack => [Option] -> SpecWith a Source #

Phase 3: Transforming the spec tree

An extension can use registerTransformation during phase 1 to indirectly influence this phase.

registerTransformation :: (Config -> [SpecTree] -> [SpecTree]) -> SpecWith a Source #

Register a transformation that transforms the spec tree in phase 3.

The registered transformation can use:

Tree.mapItems to modify spec items
Tree.filterItems to discard spec items
Config.getAnnotation to access custom config metadata
Item.getAnnotation to access custom item metadata

Phase 4: Reporting results

An extension can register a custom formatter in phase 1 to indirectly influence this phase.

Types

Operations on these types are provided by the following modules respectively:

data Config Source #

data Item a Source #

Item is used to represent spec items internally. A spec item consists of:

a textual description of a desired behavior
an example for that behavior
additional meta information

Everything that is an instance of the Example type class can be used as an example, including QuickCheck properties, Hspec expectations and HUnit assertions.

data SpecM a r Source #

A writer monad for SpecTree forests.

This is used by describe and is used to construct the forest of spec items.

It allows for dynamically generated spec trees, for example, by using data obtained by performing IO actions with runIO.

Instances

Instances details

Applicative (SpecM a) Source #
Instance details Defined in Test.Hspec.Core.Spec.Monad Methods pure :: a0 -> SpecM a a0 # (<>) :: SpecM a (a0 -> b) -> SpecM a a0 -> SpecM a b # liftA2 :: (a0 -> b -> c) -> SpecM a a0 -> SpecM a b -> SpecM a c # (>) :: SpecM a a0 -> SpecM a b -> SpecM a b # (<*) :: SpecM a a0 -> SpecM a b -> SpecM a a0 #
Functor (SpecM a) Source #
Instance details Defined in Test.Hspec.Core.Spec.Monad Methods fmap :: (a0 -> b) -> SpecM a a0 -> SpecM a b # (<$) :: a0 -> SpecM a b -> SpecM a a0 #
Monad (SpecM a) Source #
Instance details Defined in Test.Hspec.Core.Spec.Monad Methods (>>=) :: SpecM a a0 -> (a0 -> SpecM a b) -> SpecM a b # (>>) :: SpecM a a0 -> SpecM a b -> SpecM a b # return :: a0 -> SpecM a a0 #

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.

type SpecTree = SpecTree () Source #