hspec-core-2.11.16: A Testing Framework for Haskell

Stability | provisional
Safe Haskell | None
Language | Haskell2010

Test.Hspec.Core.Runner

Contents

- Simple interface
  - Summary
- Running a spec
  - Result
    - Spec Result
    - Result Item
    - Result Item Status
- Config
- Legacy
- Re-exports

Description

Synopsis

- hspec :: Spec -> IO ()
- hspecWith :: Config -> Spec -> IO ()
- hspecResult :: Spec -> IO Summary
- hspecWithResult :: Config -> Spec -> IO Summary
- data Summary = Summary {
  - summaryExamples :: !Int
  - summaryFailures :: !Int
  }
- isSuccess :: Summary -> Bool
- evaluateSummary :: Summary -> IO ()
- evalSpec :: Config -> SpecWith a -> IO (Config, [SpecTree a])
- runSpecForest :: [SpecTree ()] -> Config -> IO SpecResult
- evaluateResult :: SpecResult -> IO ()
- data SpecResult
- specResultItems :: SpecResult -> [ResultItem]
- specResultSuccess :: SpecResult -> Bool
- toSummary :: SpecResult -> Summary
- data ResultItem
- resultItemPath :: ResultItem -> Path
- resultItemStatus :: ResultItem -> ResultItemStatus
- resultItemIsFailure :: ResultItem -> Bool
- data ResultItemStatus
  - = ResultItemSuccess
  - | ResultItemPending
  - | ResultItemFailure
- data Config = Config {
  - configIgnoreConfigFile :: Bool
  - configDryRun :: Bool
  - configFocusedOnly :: Bool
  - configFailOnEmpty :: Bool
  - configFailOnFocused :: Bool
  - configFailOnPending :: Bool
  - configFailOnEmptyDescription :: Bool
  - configPrintSlowItems :: Maybe Int
  - configPrintCpuTime :: Bool
  - configFailFast :: Bool
  - configRandomize :: Bool
  - configSeed :: Maybe Integer
  - configQuickCheckSeed :: Maybe Integer
  - configFailureReport :: Maybe FilePath
  - configRerun :: Bool
  - configRerunAllOnSuccess :: Bool
  - configFilterPredicate :: Maybe (Path -> Bool)
  - configSkipPredicate :: Maybe (Path -> Bool)
  - configQuickCheckMaxSuccess :: Maybe Int
  - configQuickCheckMaxDiscardRatio :: Maybe Int
  - configQuickCheckMaxSize :: Maybe Int
  - configQuickCheckMaxShrinks :: Maybe Int
  - configSmallCheckDepth :: Maybe Int
  - configColorMode :: ColorMode
  - configUnicodeMode :: UnicodeMode
  - configDiff :: Bool
  - configDiffContext :: Maybe Int
  - configExternalDiff :: Maybe (Maybe Int -> String -> String -> IO ())
  - configPrettyPrint :: Bool
  - configPrettyPrintFunction :: Bool -> String -> String -> (String, String)
  - configFormatException :: SomeException -> String
  - configTimes :: Bool
  - configExpertMode :: Bool
  - configAvailableFormatters :: [(String, FormatConfig -> IO Format)]
  - configFormat :: Maybe (FormatConfig -> IO Format)
  - configFormatter :: Maybe Formatter
  - configHtmlOutput :: Bool
  - configConcurrentJobs :: Maybe Int
  - configAnnotations :: Annotations
  }
- data ColorMode
  - = ColorAuto
  - | ColorNever
  - | ColorAlways
- data UnicodeMode
  - = UnicodeAuto
  - | UnicodeNever
  - | UnicodeAlways
- type Path = ([String], String)
- defaultConfig :: Config
- registerFormatter :: (String, FormatConfig -> IO Format) -> Config -> Config
- registerDefaultFormatter :: (String, FormatConfig -> IO Format) -> Config -> Config
- configAddFilter :: (Path -> Bool) -> Config -> Config
- readConfig :: Config -> [String] -> IO Config
- runSpec :: Spec -> Config -> IO Summary
- type Spec = SpecWith ()
- type SpecWith a = SpecM a ()

# Simple interface

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 desirable. Use `evalSpec` and `runSpecForest` if you need more control over these aspects.

hspecWith :: Config -> Spec -> IO () Source #

Run given spec with custom options. This is similar to `hspec`, but more flexible.

hspecResult :: Spec -> IO Summary Source #

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.

hspecWithResult :: Config -> Spec -> IO Summary Source #

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

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

## Summary

data Summary Source #

Summary of a test run.

Constructors

Summary |

Fields

- summaryExamples :: !Int
- summaryFailures :: !Int

#### Instances

Instances details

Monoid Summary Source # |
Instance details Defined in Test.Hspec.Core.Runner.Result Methods mempty :: Summary Source # mappend :: Summary -> Summary -> Summary Source # mconcat :: [Summary] -> Summary Source #
Semigroup Summary Source # |
Instance details Defined in Test.Hspec.Core.Runner.Result Methods (<>) :: Summary -> Summary -> Summary Source # sconcat :: NonEmpty Summary -> Summary Source # stimes :: Integral b => b -> Summary -> Summary Source #
Show Summary Source # |
Instance details Defined in Test.Hspec.Core.Runner.Result Methods showsPrec :: Int -> Summary -> ShowS Source # show :: Summary -> String Source # showList :: [Summary] -> ShowS Source #
Eq Summary Source # |
Instance details Defined in Test.Hspec.Core.Runner.Result Methods (==) :: Summary -> Summary -> Bool Source # (/=) :: Summary -> Summary -> Bool Source #

isSuccess :: Summary -> Bool Source #

`True` if the given `Summary` indicates that there were no failures, `False` otherwise.

evaluateSummary :: Summary -> IO () Source #

Exit with `exitFailure` if the given `Summary` indicates that there was at least one failure.

# Running a spec

To run a spec `hspec` performs a sequence of steps:

1. Evaluate a `Spec` to a forest of `SpecTree`s
2. Read config values from the command-line, config files and the process environment
3. Execute each spec item of the forest and report results to `stdout`
4. Exit with `exitFailure` if at least on spec item fails

The four primitives `evalSpec`, `readConfig`, `runSpecForest` and `evaluateResult` each perform one of these steps respectively.

`hspec` is defined in terms of these primitives. Loosely speaking, a definition for `hspec` is:

    hspec = evalSpec defaultConfig >=> \ (config, spec) ->
          getArgs
      >>= readConfig config
      >>= withArgs [] . runSpecForest spec
      >>= evaluateResult

Loosely speaking in the sense that this definition of `hspec` ignores `--rerun-all-on-success`.

Using these primitives individually gives you more control over how a spec is run. However, if you need support for `--rerun-all-on-success` then you should try hard to solve your use case with one of `hspec`, `hspecWith`, `hspecResult` or `hspecWithResult`.

evalSpec :: Config -> SpecWith a -> IO (Config, [SpecTree a]) Source #

Evaluate a `Spec` to a forest of `SpecTree`s. This does not execute any spec items, but it does run any IO that is used during spec construction time (see `runIO`).

A `Spec` may modify a `Config` through `modifyConfig`. These modifications are applied to the given config (the first argument).

Since: 2.10.0

runSpecForest :: [SpecTree ()] -> Config -> IO SpecResult Source #

`runSpecForest` is the most basic primitive to run a spec. `hspec` is defined in terms of `runSpecForest`:

    hspec = evalSpec defaultConfig >=> \ (config, spec) ->
          getArgs
      >>= readConfig config
      >>= withArgs [] . runSpecForest spec
      >>= evaluateResult

Since: 2.10.0

evaluateResult :: SpecResult -> IO () Source #

## Result

### Spec Result

data SpecResult Source #

Since: 2.10.0

#### Instances

Instances details

Show SpecResult Source # |
Instance details Defined in Test.Hspec.Core.Runner.Result Methods showsPrec :: Int -> SpecResult -> ShowS Source # show :: SpecResult -> String Source # showList :: [SpecResult] -> ShowS Source #
Eq SpecResult Source # |
Instance details Defined in Test.Hspec.Core.Runner.Result Methods (==) :: SpecResult -> SpecResult -> Bool Source # (/=) :: SpecResult -> SpecResult -> Bool Source #

specResultItems :: SpecResult -> [ResultItem] Source #

Since: 2.10.0

specResultSuccess :: SpecResult -> Bool Source #

Since: 2.10.0

toSummary :: SpecResult -> Summary Source #

### Result Item

data ResultItem Source #

Since: 2.10.0

#### Instances

Instances details

Show ResultItem Source # |
Instance details Defined in Test.Hspec.Core.Runner.Result Methods showsPrec :: Int -> ResultItem -> ShowS Source # show :: ResultItem -> String Source # showList :: [ResultItem] -> ShowS Source #
Eq ResultItem Source # |
Instance details Defined in Test.Hspec.Core.Runner.Result Methods (==) :: ResultItem -> ResultItem -> Bool Source # (/=) :: ResultItem -> ResultItem -> Bool Source #

resultItemPath :: ResultItem -> Path Source #

Since: 2.10.0

resultItemStatus :: ResultItem -> ResultItemStatus Source #

Since: 2.10.0

resultItemIsFailure :: ResultItem -> Bool Source #

Since: 2.10.0

### Result Item Status

data ResultItemStatus Source #

Constructors

ResultItemSuccess |
ResultItemPending |
ResultItemFailure |

#### Instances

Instances details

Show ResultItemStatus Source # |
Instance details Defined in Test.Hspec.Core.Runner.Result Methods showsPrec :: Int -> ResultItemStatus -> ShowS Source # show :: ResultItemStatus -> String Source # showList :: [ResultItemStatus] -> ShowS Source #
Eq ResultItemStatus Source # |
Instance details Defined in Test.Hspec.Core.Runner.Result Methods (==) :: ResultItemStatus -> ResultItemStatus -> Bool Source # (/=) :: ResultItemStatus -> ResultItemStatus -> Bool Source #

# Config

data Config Source #

Constructors

Config |

Fields

- configIgnoreConfigFile :: Bool
- configDryRun :: Bool
- configFocusedOnly :: Bool
- configFailOnEmpty :: Bool
- configFailOnFocused :: Bool
- configFailOnPending :: Bool
- configFailOnEmptyDescription :: Bool
- configPrintSlowItems :: Maybe Int
- configPrintCpuTime :: Bool
- configFailFast :: Bool
- configRandomize :: Bool
- configSeed :: Maybe Integer
- configQuickCheckSeed :: Maybe Integer

  Deprecated: Use `configSeed` instead.

- configFailureReport :: Maybe FilePath
- configRerun :: Bool
- configRerunAllOnSuccess :: Bool
- configFilterPredicate :: Maybe (Path -> Bool)
- configSkipPredicate :: Maybe (Path -> Bool)
- configQuickCheckMaxSuccess :: Maybe Int
- configQuickCheckMaxDiscardRatio :: Maybe Int
- configQuickCheckMaxSize :: Maybe Int
- configQuickCheckMaxShrinks :: Maybe Int
- configSmallCheckDepth :: Maybe Int
- configColorMode :: ColorMode
- configUnicodeMode :: UnicodeMode
- configDiff :: Bool
- configDiffContext :: Maybe Int
- configExternalDiff :: Maybe (Maybe Int -> String -> String -> IO ())
- configPrettyPrint :: Bool
- configPrettyPrintFunction :: Bool -> String -> String -> (String, String)
- configFormatException :: SomeException -> String

  Since: 2.11.5

- configTimes :: Bool
- configExpertMode :: Bool

  Since: 2.11.2

- configAvailableFormatters :: [(String, FormatConfig -> IO Format)]

  Since: 2.9.0

- configFormat :: Maybe (FormatConfig -> IO Format)
- configFormatter :: Maybe Formatter

  Deprecated: Use `useFormatter` instead.

- configHtmlOutput :: Bool
- configConcurrentJobs :: Maybe Int
- configAnnotations :: Annotations

data ColorMode Source #

Constructors

ColorAuto |
ColorNever |
ColorAlways |

#### Instances

Instances details

Show ColorMode Source # |
Instance details Defined in Test.Hspec.Core.Config.Definition Methods showsPrec :: Int -> ColorMode -> ShowS Source # show :: ColorMode -> String Source # showList :: [ColorMode] -> ShowS Source #
Eq ColorMode Source # |
Instance details Defined in Test.Hspec.Core.Config.Definition Methods (==) :: ColorMode -> ColorMode -> Bool Source # (/=) :: ColorMode -> ColorMode -> Bool Source #

data UnicodeMode Source #

Constructors

UnicodeAuto |
UnicodeNever |
UnicodeAlways |

#### Instances

Instances details

Show UnicodeMode Source # |
Instance details Defined in Test.Hspec.Core.Config.Definition Methods showsPrec :: Int -> UnicodeMode -> ShowS Source # show :: UnicodeMode -> String Source # showList :: [UnicodeMode] -> ShowS Source #
Eq UnicodeMode Source # |
Instance details Defined in Test.Hspec.Core.Config.Definition Methods (==) :: UnicodeMode -> UnicodeMode -> Bool Source # (/=) :: UnicodeMode -> UnicodeMode -> Bool Source #

type Path = ([String], String) Source #

A `Path` describes the location of a spec item within a spec tree.

It consists of a list of group descriptions and a requirement description.

Since: 2.0.0

defaultConfig :: Config Source #

registerFormatter :: (String, FormatConfig -> IO Format) -> Config -> Config Source #

Deprecated: Use `registerFormatter` instead.

Make a formatter available for use with `--format`.

Since: 2.10.5

registerDefaultFormatter :: (String, FormatConfig -> IO Format) -> Config -> Config Source #

Deprecated: Use `useFormatter` instead.

Make a formatter available for use with `--format` and use it by default.

Since: 2.10.5

configAddFilter :: (Path -> Bool) -> Config -> Config Source #

Add a filter predicate to config. If there is already a filter predicate, then combine them with `||`.

readConfig :: Config -> [String] -> IO Config Source #

`readConfig` parses config options from several sources and constructs a `Config` value. It takes options from:

1. `~/.hspec` (a config file in the user's home directory)
2. `.hspec` (a config file in the current working directory)
3. environment variables starting with `HSPEC_`
4. the provided list of command-line options (the second argument to `readConfig`)

(precedence from low to high)

When parsing fails then `readConfig` writes an error message to `stderr` and exits with `exitFailure`.

When `--help` is provided as a command-line option then `readConfig` writes a help message to `stdout` and exits with `exitSuccess`.

A common way to use `readConfig` is:

    getArgs >>= readConfig defaultConfig

# Legacy

runSpec :: Spec -> Config -> IO Summary Source #

Note: `runSpec` is deprecated. It ignores any modifications applied through `modifyConfig`. Use `evalSpec` and `runSpecForest` instead.

# Re-exports

type Spec = SpecWith () Source #

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

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.