Stability	stable
Safe Haskell	None
Language	Haskell2010

Test.Hspec.Api.Formatters.V3

Contents

Register a formatter
Formatters
Implementing a custom Formatter
Re-exports

Description

This module contains formatters that can be used with hspecWith:

import Test.Hspec
import Test.Hspec.Api.Formatters.V1

main :: IO ()
main = hspecWith (useFormatter ("my-formatter", formatter) defaultConfig) spec

formatter :: Formatter
formatter = ...

spec :: Spec
spec = ...

Synopsis

registerFormatter :: (String, Formatter) -> Config -> Config
useFormatter :: (String, Formatter) -> Config -> Config
formatterToFormat :: Formatter -> FormatConfig -> IO Format
silent :: Formatter
checks :: Formatter
specdoc :: Formatter
progress :: Formatter
failed_examples :: Formatter
data Formatter = Formatter {
- formatterStarted :: FormatM ()
- formatterGroupStarted :: Path -> FormatM ()
- formatterGroupDone :: Path -> FormatM ()
- formatterProgress :: Path -> Progress -> FormatM ()
- formatterItemStarted :: Path -> FormatM ()
- formatterItemDone :: Path -> Item -> FormatM ()
- formatterDone :: FormatM ()
}
type Path = ([String], String)
type Progress = (Int, Int)
data Location = Location {
- locationFile :: FilePath
- locationLine :: Int
- locationColumn :: Int
}
data Item = Item {
- itemLocation :: Maybe Location
- itemDuration :: Seconds
- itemInfo :: String
- itemResult :: Result
}
data Result
- = Success
- | Pending (Maybe Location) (Maybe String)
- | Failure (Maybe Location) FailureReason
data FailureReason
- = NoReason
- | Reason String
- | ColorizedReason String
- | ExpectedButGot (Maybe String) String String
- | Error (Maybe String) SomeException
data FormatM a
getConfig :: FormatM FormatConfig
getConfigValue :: (FormatConfig -> a) -> FormatM a
data FormatConfig = FormatConfig {
- formatConfigUseColor :: Bool
- formatConfigReportProgress :: Bool
- formatConfigOutputUnicode :: Bool
- formatConfigUseDiff :: Bool
- formatConfigDiffContext :: Maybe Int
- formatConfigExternalDiff :: Maybe (String -> String -> IO ())
- formatConfigPrettyPrintFunction :: Maybe (String -> String -> (String, String))
- formatConfigFormatException :: SomeException -> String
- formatConfigPrintTimes :: Bool
- formatConfigHtmlOutput :: Bool
- formatConfigPrintCpuTime :: Bool
- formatConfigUsedSeed :: Integer
- formatConfigExpectedTotalCount :: Int
}
defaultFormatConfig :: FormatConfig
getSuccessCount :: FormatM Int
getPendingCount :: FormatM Int
getFailCount :: FormatM Int
getTotalCount :: FormatM Int
getExpectedTotalCount :: FormatM Int
data FailureRecord = FailureRecord {
- failureRecordLocation :: Maybe Location
- failureRecordPath :: Path
- failureRecordMessage :: FailureReason
}
getFailMessages :: FormatM [FailureRecord]
usedSeed :: FormatM Integer
printTimes :: FormatM Bool
newtype Seconds = Seconds Double
getCPUTime :: FormatM (Maybe Seconds)
getRealTime :: FormatM Seconds
write :: String -> FormatM ()
writeLine :: String -> FormatM ()
writeTransient :: String -> FormatM ()
withInfoColor :: FormatM a -> FormatM a
withSuccessColor :: FormatM a -> FormatM a
withPendingColor :: FormatM a -> FormatM a
withFailColor :: FormatM a -> FormatM a
outputUnicode :: FormatM Bool
useDiff :: FormatM Bool
diffContext :: FormatM (Maybe Int)
externalDiffAction :: FormatM (Maybe (String -> String -> IO ()))
prettyPrint :: FormatM Bool
prettyPrintFunction :: FormatM (Maybe (String -> String -> (String, String)))
extraChunk :: String -> FormatM ()
missingChunk :: String -> FormatM ()
unlessExpert :: FormatM () -> FormatM ()
formatLocation :: Location -> String
formatException :: SomeException -> String
type SpecWith a = SpecM a ()
data Config
modifyConfig :: (Config -> Config) -> SpecWith a

Register a formatter

registerFormatter :: (String, Formatter) -> Config -> Config Source #

Make a formatter available for use with --format.

useFormatter :: (String, Formatter) -> Config -> Config Source #

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

formatterToFormat :: Formatter -> FormatConfig -> IO Format Source #

Formatters

silent :: Formatter Source #

checks :: Formatter Source #

specdoc :: Formatter Source #

progress :: Formatter Source #

failed_examples :: Formatter Source #

Implementing a custom Formatter

A formatter is a set of actions. Each action is evaluated when a certain situation is encountered during a test run.

Actions live in the FormatM monad. It provides access to the runner state and primitives for appending to the generated report.

data Formatter Source #

Constructors

Formatter
Fields formatterStarted :: FormatM () formatterGroupStarted :: Path -> FormatM () formatterGroupDone :: Path -> FormatM () formatterProgress :: Path -> Progress -> FormatM () formatterItemStarted :: Path -> FormatM () formatterItemDone :: Path -> Item -> FormatM () formatterDone :: FormatM ()

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: hspec-core-2.0.0

type Progress = (Int, Int) Source #

(CurrentItem, TotalItems) tuple.

data Location Source #

Location is used to represent source locations.

Constructors

Location
Fields locationFile :: FilePath locationLine :: Int locationColumn :: Int

Instances

Instances details

Read Location
Instance details Defined in Test.Hspec.Core.Example.Location Methods readsPrec :: Int -> ReadS Location readList :: ReadS [Location] readPrec :: ReadPrec Location readListPrec :: ReadPrec [Location]
Show Location
Instance details Defined in Test.Hspec.Core.Example.Location Methods showsPrec :: Int -> Location -> ShowS show :: Location -> String showList :: [Location] -> ShowS
Eq Location
Instance details Defined in Test.Hspec.Core.Example.Location Methods (==) :: Location -> Location -> Bool (/=) :: Location -> Location -> Bool

data Item Source #

Constructors

Item
Fields itemLocation :: Maybe Location itemDuration :: Seconds itemInfo :: String itemResult :: Result

Instances

Instances details

Show Item
Instance details Defined in Test.Hspec.Core.Format Methods showsPrec :: Int -> Item -> ShowS show :: Item -> String showList :: [Item] -> ShowS

data Result Source #

Constructors

Success
Pending (Maybe Location) (Maybe String)
Failure (Maybe Location) FailureReason

Instances

Instances details

Show Result
Instance details Defined in Test.Hspec.Core.Format Methods showsPrec :: Int -> Result -> ShowS show :: Result -> String showList :: [Result] -> ShowS

data FailureReason Source #

Constructors

NoReason
Reason String
ColorizedReason String
ExpectedButGot (Maybe String) String String
Error (Maybe String) SomeException

Instances

Instances details

NFData FailureReason
Instance details Defined in Test.Hspec.Core.Example Methods rnf :: FailureReason -> ()
Show FailureReason
Instance details Defined in Test.Hspec.Core.Example Methods showsPrec :: Int -> FailureReason -> ShowS show :: FailureReason -> String showList :: [FailureReason] -> ShowS

data FormatM a Source #

Instances

Instances details

MonadIO FormatM
Instance details Defined in Test.Hspec.Core.Formatters.Internal Methods liftIO :: IO a -> FormatM a
Applicative FormatM
Instance details Defined in Test.Hspec.Core.Formatters.Internal Methods pure :: a -> FormatM a (<>) :: FormatM (a -> b) -> FormatM a -> FormatM b liftA2 :: (a -> b -> c) -> FormatM a -> FormatM b -> FormatM c (>) :: FormatM a -> FormatM b -> FormatM b (<*) :: FormatM a -> FormatM b -> FormatM a
Functor FormatM
Instance details Defined in Test.Hspec.Core.Formatters.Internal Methods fmap :: (a -> b) -> FormatM a -> FormatM b (<$) :: a -> FormatM b -> FormatM a
Monad FormatM
Instance details Defined in Test.Hspec.Core.Formatters.Internal Methods (>>=) :: FormatM a -> (a -> FormatM b) -> FormatM b (>>) :: FormatM a -> FormatM b -> FormatM b return :: a -> FormatM a

Accessing config values

getConfig :: FormatM FormatConfig Source #

Since: 2.11.5

getConfigValue :: (FormatConfig -> a) -> FormatM a Source #

Since: 2.11.5

data FormatConfig Source #

Since: 2.11.5

Constructors

FormatConfig

Fields

formatConfigUseColor :: Bool
formatConfigReportProgress :: Bool
formatConfigOutputUnicode :: Bool
formatConfigUseDiff :: Bool
formatConfigDiffContext :: Maybe Int
formatConfigExternalDiff :: Maybe (String -> String -> IO ())
formatConfigPrettyPrintFunction :: Maybe (String -> String -> (String, String))
formatConfigFormatException :: SomeException -> String
Since: 2.11.5
formatConfigPrintTimes :: Bool
formatConfigHtmlOutput :: Bool
formatConfigPrintCpuTime :: Bool
formatConfigUsedSeed :: Integer
formatConfigExpectedTotalCount :: Int

defaultFormatConfig :: FormatConfig Source #

Accessing the runner state

getSuccessCount :: FormatM Int Source #

Get the number of successful examples encountered so far.

getPendingCount :: FormatM Int Source #

Get the number of pending examples encountered so far.

getFailCount :: FormatM Int Source #

Get the number of failed examples encountered so far.

getTotalCount :: FormatM Int Source #

Get the total number of examples encountered so far.

getExpectedTotalCount :: FormatM Int Source #

Get the number of spec items that will have been encountered when this run completes (if it is not terminated early).

Since: hspec-core-2.9.0

data FailureRecord Source #

Constructors

FailureRecord
Fields failureRecordLocation :: Maybe Location failureRecordPath :: Path failureRecordMessage :: FailureReason

getFailMessages :: FormatM [FailureRecord] Source #

Get the list of accumulated failure messages.

usedSeed :: FormatM Integer Source #

The random seed that is used for QuickCheck.

printTimes :: FormatM Bool Source #

Return True if the user requested time reporting for individual spec items, False otherwise.

newtype Seconds Source #

Constructors

Seconds Double

Instances

Instances details

PrintfArg Seconds
Instance details Defined in Test.Hspec.Core.Clock Methods formatArg :: Seconds -> FieldFormatter parseFormat :: Seconds -> ModifierParser
Num Seconds
Instance details Defined in Test.Hspec.Core.Clock Methods (+) :: Seconds -> Seconds -> Seconds (-) :: Seconds -> Seconds -> Seconds (*) :: Seconds -> Seconds -> Seconds negate :: Seconds -> Seconds abs :: Seconds -> Seconds signum :: Seconds -> Seconds fromInteger :: Integer -> Seconds
Fractional Seconds
Instance details Defined in Test.Hspec.Core.Clock Methods (/) :: Seconds -> Seconds -> Seconds recip :: Seconds -> Seconds fromRational :: Rational -> Seconds
Show Seconds
Instance details Defined in Test.Hspec.Core.Clock Methods showsPrec :: Int -> Seconds -> ShowS show :: Seconds -> String showList :: [Seconds] -> ShowS
Eq Seconds
Instance details Defined in Test.Hspec.Core.Clock Methods (==) :: Seconds -> Seconds -> Bool (/=) :: Seconds -> Seconds -> Bool
Ord Seconds
Instance details Defined in Test.Hspec.Core.Clock Methods compare :: Seconds -> Seconds -> Ordering (<) :: Seconds -> Seconds -> Bool (<=) :: Seconds -> Seconds -> Bool (>) :: Seconds -> Seconds -> Bool (>=) :: Seconds -> Seconds -> Bool max :: Seconds -> Seconds -> Seconds min :: Seconds -> Seconds -> Seconds

getCPUTime :: FormatM (Maybe Seconds) Source #

Get the used CPU time since the test run has been started.

getRealTime :: FormatM Seconds Source #

Get the passed real time since the test run has been started.

Appending to the generated report

write :: String -> FormatM () Source #

Append some output to the report.

writeLine :: String -> FormatM () Source #

The same as write, but adds a newline character.

writeTransient :: String -> FormatM () Source #

Dealing with colors

withInfoColor :: FormatM a -> FormatM a Source #

Set output color to cyan, run given action, and finally restore the default color.

withSuccessColor :: FormatM a -> FormatM a Source #

Set output color to green, run given action, and finally restore the default color.

withPendingColor :: FormatM a -> FormatM a Source #

Set output color to yellow, run given action, and finally restore the default color.

withFailColor :: FormatM a -> FormatM a Source #

Set output color to red, run given action, and finally restore the default color.

outputUnicode :: FormatM Bool Source #

Return True if the user requested unicode output, False otherwise.

Since: hspec-core-2.9.0

useDiff :: FormatM Bool Source #

Return True if the user requested colorized diffs, False otherwise.

diffContext :: FormatM (Maybe Int) Source #

Return the value of configDiffContext.

Since: hspec-core-2.10.6

externalDiffAction :: FormatM (Maybe (String -> String -> IO ())) Source #

An action for printing diffs.

The action takes expected and actual as arguments.

When this is a Just-value then it should be used instead of any built-in diff implementation. A Just-value also implies that useDiff returns True.

Since: hspec-core-2.10.6

prettyPrint :: FormatM Bool Source #

Return True if the user requested pretty diffs, False otherwise.

prettyPrintFunction :: FormatM (Maybe (String -> String -> (String, String))) Source #

Return a function for pretty-printing if the user requested pretty diffs, Nothing otherwise.

Since: hspec-core-2.10.0

extraChunk :: String -> FormatM () Source #

Output given chunk in red.

missingChunk :: String -> FormatM () Source #

Output given chunk in green.

expert mode

unlessExpert :: FormatM () -> FormatM () Source #

Do nothing on `--expert`, otherwise run the given action.

Since: hspec-core-2.11.2

Helpers

formatLocation :: Location -> String Source #

formatException :: SomeException -> String Source #

The function formatException converts an exception to a string.

This is different from show. The type of the exception is included, e.g.:

>>> formatException (toException DivideByZero)
"ArithException\ndivide by zero"

For IOExceptions the IOErrorType is included, as well.

Since: hspec-core-2.0.0

Re-exports

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.

data Config Source #

modifyConfig :: (Config -> Config) -> SpecWith a Source #

Since: hspec-core-2.10.0