hspec-core-2.11.1: A Testing Framework for Haskell
Stabilityprovisional
Safe HaskellSafe-Inferred
LanguageHaskell2010

Test.Hspec.Core.Runner

Description

 
Synopsis

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 

Instances

Instances details
Monoid Summary Source # 
Instance details

Defined in Test.Hspec.Core.Runner.Result

Semigroup Summary Source # 
Instance details

Defined in Test.Hspec.Core.Runner.Result

Show Summary Source # 
Instance details

Defined in Test.Hspec.Core.Runner.Result

Eq Summary Source # 
Instance details

Defined in Test.Hspec.Core.Runner.Result

Methods

(==) :: Summary -> Summary -> Bool #

(/=) :: Summary -> Summary -> Bool #

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

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

Eq SpecResult Source # 
Instance details

Defined in Test.Hspec.Core.Runner.Result

Result Item

data ResultItem Source #

Since: 2.10.0

Instances

Instances details
Show ResultItem Source # 
Instance details

Defined in Test.Hspec.Core.Runner.Result

Eq ResultItem Source # 
Instance details

Defined in Test.Hspec.Core.Runner.Result

Result Item Status

Config

data ColorMode Source #

Instances

Instances details
Show ColorMode Source # 
Instance details

Defined in Test.Hspec.Core.Config.Definition

Eq ColorMode Source # 
Instance details

Defined in Test.Hspec.Core.Config.Definition

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

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 #

type SpecWith a = SpecM a () Source #