Stability	provisional
Safe Haskell	Safe-Inferred
Language	Haskell2010

Test.Hspec.Core.Runner

Contents

Simple interface
- Summary
Running a spec
- Result
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 # mappend :: Summary -> Summary -> Summary # mconcat :: [Summary] -> Summary #
Semigroup Summary Source #
Instance details Defined in Test.Hspec.Core.Runner.Result Methods (<>) :: Summary -> Summary -> Summary # sconcat :: NonEmpty Summary -> Summary # stimes :: Integral b => b -> Summary -> Summary #
Show Summary Source #
Instance details Defined in Test.Hspec.Core.Runner.Result Methods showsPrec :: Int -> Summary -> ShowS # show :: Summary -> String # showList :: [Summary] -> ShowS #
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:

Evaluate a Spec to a forest of SpecTrees
Read config values from the command-line, config files and the process environment
Execute each spec item of the forest and report results to stdout
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

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 # show :: SpecResult -> String # showList :: [SpecResult] -> ShowS #
Eq SpecResult Source #
Instance details Defined in Test.Hspec.Core.Runner.Result Methods (==) :: SpecResult -> SpecResult -> Bool # (/=) :: SpecResult -> SpecResult -> Bool #

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 # show :: ResultItem -> String # showList :: [ResultItem] -> ShowS #
Eq ResultItem Source #
Instance details Defined in Test.Hspec.Core.Runner.Result Methods (==) :: ResultItem -> ResultItem -> Bool # (/=) :: ResultItem -> ResultItem -> Bool #

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 # show :: ResultItemStatus -> String # showList :: [ResultItemStatus] -> ShowS #
Eq ResultItemStatus Source #
Instance details Defined in Test.Hspec.Core.Runner.Result Methods (==) :: ResultItemStatus -> ResultItemStatus -> Bool # (/=) :: ResultItemStatus -> ResultItemStatus -> Bool #

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 # show :: ColorMode -> String # showList :: [ColorMode] -> ShowS #
Eq ColorMode Source #
Instance details Defined in Test.Hspec.Core.Config.Definition Methods (==) :: ColorMode -> ColorMode -> Bool # (/=) :: ColorMode -> ColorMode -> Bool #

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 # show :: UnicodeMode -> String # showList :: [UnicodeMode] -> ShowS #
Eq UnicodeMode Source #
Instance details Defined in Test.Hspec.Core.Config.Definition Methods (==) :: UnicodeMode -> UnicodeMode -> Bool # (/=) :: UnicodeMode -> UnicodeMode -> Bool #

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:

~/.hspec (a config file in the user's home directory)
.hspec (a config file in the current working directory)
environment variables starting with HSPEC_
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 #