hspec-1.8.1.1: Behavior-Driven Development for Haskell

Stability | experimental
Safe Haskell | None

Test.Hspec.Formatters

Contents

- Formatters
- Implementing a custom Formatter
  - Accessing the runner state
  - Appending to the gerenated report
  - Dealing with colors
  - Helpers
- Using custom formatters with `hspec-discover`

Description

This module contains formatters that can be used with `hspecWith`.

Synopsis

- silent :: Formatter
- specdoc :: Formatter
- progress :: Formatter
- failed_examples :: Formatter
- data Formatter = Formatter {
  - headerFormatter :: FormatM ()
  - exampleGroupStarted :: Int -> [String] -> String -> FormatM ()
  - exampleGroupDone :: FormatM ()
  - exampleProgress :: Handle -> Path -> Progress -> IO ()
  - exampleSucceeded :: Path -> FormatM ()
  - exampleFailed :: Path -> Either SomeException String -> FormatM ()
  - examplePending :: Path -> Maybe String -> FormatM ()
  - failedFormatter :: FormatM ()
  - footerFormatter :: FormatM ()
  }
- data FormatM a
- getSuccessCount :: FormatM Int
- getPendingCount :: FormatM Int
- getFailCount :: FormatM Int
- getTotalCount :: FormatM Int
- data FailureRecord = FailureRecord {
  - failureRecordPath :: Path
  - failureRecordMessage :: Either SomeException String
  }
- getFailMessages :: FormatM [FailureRecord]
- usedSeed :: FormatM Integer
- getCPUTime :: FormatM (Maybe Double)
- getRealTime :: FormatM Double
- write :: String -> FormatM ()
- writeLine :: String -> FormatM ()
- newParagraph :: FormatM ()
- withSuccessColor :: FormatM a -> FormatM a
- withPendingColor :: FormatM a -> FormatM a
- withFailColor :: FormatM a -> FormatM a
- formatException :: SomeException -> String
- class IsFormatter a where
  - toFormatter :: a -> IO Formatter

# Formatters

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

headerFormatter :: FormatM ()
exampleGroupStarted :: Int -> [String] -> String -> FormatM ()

  evaluated before each test group

  The given number indicates the position within the parent group.

exampleGroupDone :: FormatM ()
exampleProgress :: Handle -> Path -> Progress -> IO ()

  used to notify the progress of the currently evaluated example

  NOTE: This is only called when interactive/color mode.

exampleSucceeded :: Path -> FormatM ()

  evaluated after each successful example

exampleFailed :: Path -> Either SomeException String -> FormatM ()

  evaluated after each failed example

examplePending :: Path -> Maybe String -> FormatM ()

  evaluated after each pending example

failedFormatter :: FormatM ()

  evaluated after a test run

footerFormatter :: FormatM ()

  evaluated after `failuresFormatter`

Instances

IsFormatter Formatter |
IsFormatter (IO Formatter) |

data FormatM a Source

Instances

Monad FormatM |
Functor FormatM |
Applicative FormatM |
MonadIO FormatM |

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

data FailureRecord Source

Constructors

FailureRecord |

Fields

failureRecordPath :: Path
failureRecordMessage :: Either SomeException String

getFailMessages :: FormatM [FailureRecord]Source

Get the list of accumulated failure messages.

usedSeed :: FormatM Integer Source

The random seed that is used for QuickCheck.

getCPUTime :: FormatM (Maybe Double)Source

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

getRealTime :: FormatM Double Source

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

## Appending to the gerenated report

write :: String -> FormatM ()Source

Append some output to the report.

writeLine :: String -> FormatM ()Source

The same as `write`, but adds a newline character.

newParagraph :: FormatM ()Source

Append an empty line to the report.

Calling this multiple times has the same effect as calling it once.

## Dealing with colors

withSuccessColor :: FormatM a -> FormatM aSource

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

withPendingColor :: FormatM a -> FormatM aSource

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

withFailColor :: FormatM a -> FormatM aSource

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

## Helpers

formatException :: SomeException -> String Source

Convert an exception to a string.

The type of the exception is included. Here is an example:

    >>> import Control.Applicative
    >>> import Control.Exception
    >>> either formatException show <$> (try . evaluate) (1 `div` 0)
    "ArithException (divide by zero)"

# Using custom formatters with `hspec-discover`

Anything that is an instance of `IsFormatter` can be used by `hspec-discover` as the default formatter for a spec. If you have a formatter `myFormatter` in the module `Custom.Formatters` you can use it by passing an additional argument to `hspec-discover`.

    {-# OPTIONS_GHC -F -pgmF hspec-discover -optF --formatter=Custom.Formatters.myFormatter #-}

class IsFormatter a where Source

Methods

toFormatter :: a -> IO Formatter Source

Instances

IsFormatter Formatter |
IsFormatter (IO Formatter) |