Test.Hspec.Core.Runner

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:

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

If you need more control over how a spec is run use these primitives individually.

hspec :: Spec -> IO ()

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.

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

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

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 ()

Config

data Config

Constructors

Config

Fields

• configIgnoreConfigFile :: Bool
• configDryRun :: Bool
• configFocusedOnly :: Bool
• configFailOnFocused :: Bool
• configPrintSlowItems :: Maybe Int
• configPrintCpuTime :: Bool
• configFailFast :: Bool
• configRandomize :: Bool
• configFailureReport :: Maybe FilePath
• configRerun :: Bool
• configRerunAllOnSuccess :: Bool
• configFilterPredicate :: Maybe (Path -> Bool)

  A predicate that is used to filter the spec before it is run. Only examples that satisfy the predicate are run.

• configSkipPredicate :: Maybe (Path -> Bool)
• configQuickCheckSeed :: Maybe Integer
• configQuickCheckMaxSuccess :: Maybe Int
• configQuickCheckMaxDiscardRatio :: Maybe Int
• configQuickCheckMaxSize :: Maybe Int
• configQuickCheckMaxShrinks :: Maybe Int
• configSmallCheckDepth :: Maybe Int
• configColorMode :: ColorMode
• configUnicodeMode :: UnicodeMode
• configDiff :: Bool
• configPrettyPrint :: Bool
• configPrettyPrintFunction :: Bool -> String -> String -> (String, String)
• configTimes :: Bool
• configAvailableFormatters :: [(String, FormatConfig -> IO Format)]
• configFormat :: Maybe (FormatConfig -> IO Format)
• configFormatter :: Maybe Formatter

  deprecated, use configFormat instead

• configHtmlOutput :: Bool
• configConcurrentJobs :: Maybe Int

data ColorMode

Constructors

ColorAuto

ColorNever

ColorAlways

Instances

Eq ColorMode

Defined in Test.Hspec.Core.Config.Definition

Methods

(==) :: ColorMode -> ColorMode -> Bool

(/=) :: ColorMode -> ColorMode -> Bool

Show ColorMode

Defined in Test.Hspec.Core.Config.Definition

Methods

showsPrec :: Int -> ColorMode -> ShowS

show :: ColorMode -> String

showList :: [ColorMode] -> ShowS

data UnicodeMode

Constructors

UnicodeAuto

UnicodeNever

UnicodeAlways

Instances

Eq UnicodeMode

Defined in Test.Hspec.Core.Config.Definition

Methods

(==) :: UnicodeMode -> UnicodeMode -> Bool

(/=) :: UnicodeMode -> UnicodeMode -> Bool

Show UnicodeMode

Defined in Test.Hspec.Core.Config.Definition

Methods

showsPrec :: Int -> UnicodeMode -> ShowS

show :: UnicodeMode -> String

showList :: [UnicodeMode] -> ShowS

type Path = ([String], String)

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.

defaultConfig :: Config

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

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

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

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. the environment variable HSPEC_OPTIONS
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

Result

Spec Result

data SpecResult

Instances

Eq SpecResult

Defined in Test.Hspec.Core.Runner.Result

Methods

(==) :: SpecResult -> SpecResult -> Bool

(/=) :: SpecResult -> SpecResult -> Bool

Show SpecResult

Defined in Test.Hspec.Core.Runner.Result

Methods

showsPrec :: Int -> SpecResult -> ShowS

show :: SpecResult -> String

showList :: [SpecResult] -> ShowS

specResultItems :: SpecResult -> [ResultItem]

specResultSuccess :: SpecResult -> Bool

Result Item

data ResultItem

Instances

Eq ResultItem

Defined in Test.Hspec.Core.Runner.Result

Methods

(==) :: ResultItem -> ResultItem -> Bool

(/=) :: ResultItem -> ResultItem -> Bool

Show ResultItem

Defined in Test.Hspec.Core.Runner.Result

Methods

showsPrec :: Int -> ResultItem -> ShowS

show :: ResultItem -> String

showList :: [ResultItem] -> ShowS

resultItemPath :: ResultItem -> Path

resultItemStatus :: ResultItem -> ResultItemStatus

resultItemIsFailure :: ResultItem -> Bool

Result Item Status

data ResultItemStatus

Constructors

ResultItemSuccess

ResultItemPending

ResultItemFailure

Instances

Eq ResultItemStatus

Defined in Test.Hspec.Core.Runner.Result

Methods

(==) :: ResultItemStatus -> ResultItemStatus -> Bool

(/=) :: ResultItemStatus -> ResultItemStatus -> Bool

Show ResultItemStatus

Defined in Test.Hspec.Core.Runner.Result

Methods

showsPrec :: Int -> ResultItemStatus -> ShowS

show :: ResultItemStatus -> String

showList :: [ResultItemStatus] -> ShowS

Legacy

The following primitives are deprecated. Use runSpecForest instead.

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

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

hspecResult :: Spec -> IO Summary

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

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.

runSpec :: Spec -> Config -> IO Summary

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

Summary

data Summary

Summary of a test run.

Constructors

Summary

Fields

• summaryExamples :: !Int
• summaryFailures :: !Int

Instances

Eq Summary

Defined in Test.Hspec.Core.Runner

Methods

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

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

Show Summary

Defined in Test.Hspec.Core.Runner

Methods

showsPrec :: Int -> Summary -> ShowS

show :: Summary -> String

showList :: [Summary] -> ShowS

Semigroup Summary

Defined in Test.Hspec.Core.Runner

Methods

(<>) :: Summary -> Summary -> Summary

sconcat :: NonEmpty Summary -> Summary

stimes :: Integral b => b -> Summary -> Summary

Monoid Summary

Defined in Test.Hspec.Core.Runner

Methods

mempty :: Summary

mappend :: Summary -> Summary -> Summary

mconcat :: [Summary] -> Summary

toSummary :: SpecResult -> Summary

isSuccess :: Summary -> Bool

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

evaluateSummary :: Summary -> IO ()

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