hspec-api-2.11.16: A Testing Framework for Haskell

Stability | stable
Safe Haskell | None
Language | Haskell2010

Test.Hspec.Api.Formatters.V2

Contents

- Register a formatter
- Formatters
- Implementing a custom Formatter
  - Accessing the runner state
  - Appending to the generated report
  - Dealing with colors
  - Helpers
- 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
  - | ExpectedButGot (Maybe String) String String
  - | Error (Maybe String) SomeException
- data FormatM a
- 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 ()
- 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 Source # readList :: ReadS [Location] Source # readPrec :: ReadPrec Location Source # readListPrec :: ReadPrec [Location] Source #
Show Location |
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 |
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.Api.Format.V1.Internal 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.Api.Format.V1.Internal Methods showsPrec :: Int -> Result -> ShowS Source # show :: Result -> String Source # showList :: [Result] -> ShowS Source #

data FailureReason Source #

Constructors

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

#### Instances

Instances details

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

data FormatM a Source #

#### Instances

Instances details

MonadIO FormatM |
Instance details Defined in Test.Hspec.Core.Formatters.Internal Methods liftIO :: IO a -> FormatM a Source #
Applicative FormatM |
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 |
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 |
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 #

## 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 Source # parseFormat :: Seconds -> ModifierParser Source #
Num Seconds |
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 |
Instance details Defined in Test.Hspec.Core.Clock Methods (/) :: Seconds -> Seconds -> Seconds Source # recip :: Seconds -> Seconds Source # fromRational :: Rational -> Seconds Source #
Show Seconds |
Instance details Defined in Test.Hspec.Core.Clock Methods showsPrec :: Int -> Seconds -> ShowS Source # show :: Seconds -> String Source # showList :: [Seconds] -> ShowS Source #
Eq Seconds |
Instance details Defined in Test.Hspec.Core.Clock Methods (==) :: Seconds -> Seconds -> Bool Source # (/=) :: Seconds -> Seconds -> Bool Source #
Ord Seconds |
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: 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.

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