hspec-core-2.11.16: A Testing Framework for Haskell

Stability | unstable
Safe Haskell | None
Language | Haskell2010

Test.Hspec.Core.Formatters.V2

Contents

- Formatters
- Implementing a custom Formatter
  - Accessing config values
  - Accessing the runner state
  - Appending to the generated report
  - Dealing with colors
  - expert mode
  - Helpers

Description

This is an unstable API. Use Test.Hspec.Api.Formatters.V3 instead.

Synopsis

- 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
- formatterToFormat :: Formatter -> FormatConfig -> IO Format
- 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 ())
  - formatConfigPrettyPrint :: Bool
  - formatConfigPrettyPrintFunction :: Maybe (String -> String -> (String, String))
  - formatConfigFormatException :: SomeException -> String
  - formatConfigPrintTimes :: Bool
  - formatConfigHtmlOutput :: Bool
  - formatConfigPrintCpuTime :: Bool
  - formatConfigUsedSeed :: Integer
  - formatConfigExpectedTotalCount :: Int
  - formatConfigExpertMode :: Bool
  }
- 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

# 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: 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 Source # |
Instance details Defined in Test.Hspec.Core.Example.Location Methods readsPrec :: Int -> ReadS Location Source # readList :: ReadS [Location] Source # readPrec :: ReadPrec Location Source # readListPrec :: ReadPrec [Location] Source #
Show Location Source # |
Instance details Defined in Test.Hspec.Core.Example.Location Methods showsPrec :: Int -> Location -> ShowS Source # show :: Location -> String Source # showList :: [Location] -> ShowS Source #
Eq Location Source # |
Instance details Defined in Test.Hspec.Core.Example.Location Methods (==) :: Location -> Location -> Bool Source # (/=) :: Location -> Location -> Bool Source #

data Item Source #

Constructors

Item |

Fields

- itemLocation :: Maybe Location
- itemDuration :: Seconds
- itemInfo :: String
- itemResult :: Result

#### Instances

Instances details

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

data Result Source #

Constructors

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

#### Instances

Instances details

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

data FailureReason Source #

Constructors

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

#### Instances

Instances details

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

data FormatM a Source #

#### Instances

Instances details

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

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

## 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 ())
- formatConfigPrettyPrint :: Bool

  Deprecated: Use `formatConfigPrettyPrintFunction` instead

- formatConfigPrettyPrintFunction :: Maybe (String -> String -> (String, String))
- formatConfigFormatException :: SomeException -> String

  Since: 2.11.5

- formatConfigPrintTimes :: Bool
- formatConfigHtmlOutput :: Bool
- formatConfigPrintCpuTime :: Bool
- formatConfigUsedSeed :: Integer
- formatConfigExpectedTotalCount :: Int
- formatConfigExpertMode :: Bool

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

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: 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: 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: 2.10.6

prettyPrint :: FormatM Bool Source #

Deprecated: use `prettyPrintFunction` instead

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: 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: 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 `IOException`s the `IOErrorType` is included, as well.

Since: 2.0.0