Test.Hspec.Core.Runner

Simple interface

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.

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.

Summary

data Summary

Summary of a test run.

Constructors

Summary

Fields

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

Instances

Monoid Summary

Defined in Test.Hspec.Core.Runner.Result

Methods

mempty :: Summary

mappend :: Summary -> Summary -> Summary

mconcat :: [Summary] -> Summary

Semigroup Summary

Defined in Test.Hspec.Core.Runner.Result

Methods

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

sconcat :: NonEmpty Summary -> Summary

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

Show Summary

Defined in Test.Hspec.Core.Runner.Result

Methods

showsPrec :: Int -> Summary -> ShowS

show :: Summary -> String

showList :: [Summary] -> ShowS

Eq Summary

Defined in Test.Hspec.Core.Runner.Result

Methods

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

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

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.

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

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

Result

Spec Result

data SpecResult

Since: 2.10.0

Instances

Show SpecResult

Defined in Test.Hspec.Core.Runner.Result

Methods

showsPrec :: Int -> SpecResult -> ShowS

show :: SpecResult -> String

showList :: [SpecResult] -> ShowS

Eq SpecResult

Defined in Test.Hspec.Core.Runner.Result

Methods

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

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

specResultItems :: SpecResult -> [ResultItem]

Since: 2.10.0

specResultSuccess :: SpecResult -> Bool

Since: 2.10.0

toSummary :: SpecResult -> Summary

Result Item

data ResultItem

Since: 2.10.0

Instances

Show ResultItem

Defined in Test.Hspec.Core.Runner.Result

Methods

showsPrec :: Int -> ResultItem -> ShowS

show :: ResultItem -> String

showList :: [ResultItem] -> ShowS

Eq ResultItem

Defined in Test.Hspec.Core.Runner.Result

Methods

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

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

resultItemPath :: ResultItem -> Path

Since: 2.10.0

resultItemStatus :: ResultItem -> ResultItemStatus

Since: 2.10.0

resultItemIsFailure :: ResultItem -> Bool

Since: 2.10.0

Result Item Status

data ResultItemStatus

Constructors

ResultItemSuccess

ResultItemPending

ResultItemFailure

Instances

Show ResultItemStatus

Defined in Test.Hspec.Core.Runner.Result

Methods

showsPrec :: Int -> ResultItemStatus -> ShowS

show :: ResultItemStatus -> String

showList :: [ResultItemStatus] -> ShowS

Eq ResultItemStatus

Defined in Test.Hspec.Core.Runner.Result

Methods

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

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

Config

data Config

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
• configFailureReport :: Maybe FilePath
• configRerun :: Bool
• configRerunAllOnSuccess :: Bool
• configFilterPredicate :: Maybe (Path -> Bool)
• 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
• 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

data ColorMode

Constructors

ColorAuto

ColorNever

ColorAlways

Instances

Show ColorMode

Defined in Test.Hspec.Core.Config.Definition

Methods

showsPrec :: Int -> ColorMode -> ShowS

show :: ColorMode -> String

showList :: [ColorMode] -> ShowS

Eq ColorMode

Defined in Test.Hspec.Core.Config.Definition

Methods

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

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

data UnicodeMode

Constructors

UnicodeAuto

UnicodeNever

UnicodeAlways

Instances

Show UnicodeMode

Defined in Test.Hspec.Core.Config.Definition

Methods

showsPrec :: Int -> UnicodeMode -> ShowS

show :: UnicodeMode -> String

showList :: [UnicodeMode] -> ShowS

Eq UnicodeMode

Defined in Test.Hspec.Core.Config.Definition

Methods

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

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

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.

Since: 2.0.0

defaultConfig :: Config

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

Deprecated: Use registerFormatter instead.

Make a formatter available for use with --format.

Since: 2.10.5

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

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

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

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

Re-exports

type Spec = SpecWith ()

type SpecWith a = SpecM a ()