hspec-core-2.11.16: A Testing Framework for Haskell

Stability | unstable
Safe Haskell | None
Language | Haskell2010

Test.Hspec.Core.Extension

Contents

- Lifecycle of a test run
  - Phase 1: Constructing a spec tree
  - Phase 2: Parsing command-line options
  - Phase 3: Transforming the spec tree
  - Phase 4: Reporting results
- Types

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:

1. A tree of spec items and a default `Config` are constructed in `SpecM`.
2. Command-line options are parsed. This transforms the default `Config` that was constructed in phase 1.
3. The tree of spec items is transformed in various ways, depending on specific `Config` values.
4. 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:

- Test.Hspec.Core.Extension.Config
- Test.Hspec.Core.Extension.Item
- Test.Hspec.Core.Extension.Spec
- Test.Hspec.Core.Extension.Tree

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

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 #