libghc-hspec-core-doc 2.2.4-3 / usr / share / doc / libghc-hspec-core-doc / html / hspec-core.txt

-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | A Testing Framework for Haskell
--   
--   This package exposes internal types and functions that can be used to
--   extend Hspec's functionality.
@package hspec-core
@version 2.2.4


module Test.Hspec.Core.Util

-- | <tt>pluralize count singular</tt> pluralizes the given
--   <tt>singular</tt> word unless given <tt>count</tt> is 1.
--   
--   Examples:
--   
--   <pre>
--   &gt;&gt;&gt; pluralize 0 "example"
--   "0 examples"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; pluralize 1 "example"
--   "1 example"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; pluralize 2 "example"
--   "2 examples"
--   </pre>
pluralize :: Int -> String -> String

-- | Strip leading and trailing whitespace
strip :: String -> String

-- | ensure that lines are not longer then given <tt>n</tt>, insert line
--   breaks at word boundaries
lineBreaksAt :: Int -> String -> [String]

-- | A <a>Path</a> represents the location of an example within the spec
--   tree.
--   
--   It consists of a list of group descriptions and a requirement
--   description.
type Path = ([String], String)

-- | Try to create a proper English sentence from a path by applying some
--   heuristics.
formatRequirement :: Path -> String

-- | A predicate that can be used to filter a spec tree.
filterPredicate :: String -> Path -> Bool

-- | <tt>safeTry</tt> evaluates given action and returns its result. If an
--   exception occurs, the exception is returned instead. Unlike <a>try</a>
--   it is agnostic to asynchronous exceptions.
safeTry :: IO a -> IO (Either SomeException a)

-- | The function <a>formatException</a> converts an exception to a string.
--   
--   This is different from <a>show</a>. The type of the exception is
--   included, e.g.:
--   
--   <pre>
--   &gt;&gt;&gt; formatException (toException DivideByZero)
--   "ArithException (divide by zero)"
--   </pre>
--   
--   For <a>IOException</a>s the <a>IOErrorType</a> is included, as well.
formatException :: SomeException -> String


-- | This module provides access to Hspec's internals. It is less stable
--   than other parts of the API. For most users <tt>Test.Hspec</tt> is
--   more suitable!
module Test.Hspec.Core.Spec

-- | The <tt>describe</tt> function combines a list of specs into a larger
--   spec.
describe :: String -> SpecWith a -> SpecWith a

-- | The <tt>it</tt> function creates a spec item.
--   
--   A spec item consists of:
--   
--   <ul>
--   <li>a textual description of a desired behavior</li>
--   <li>an example for that behavior</li>
--   </ul>
--   
--   <pre>
--   describe "absolute" $ do
--     it "returns a positive number when given a negative number" $
--       absolute (-1) == 1
--   </pre>
it :: (?loc :: CallStack, Example a) => String -> a -> SpecWith (Arg a)

-- | <a>pending</a> can be used to indicate that an example is
--   <i>pending</i>.
--   
--   If you want to textually specify a behavior but do not have an example
--   yet, use this:
--   
--   <pre>
--   describe "fancyFormatter" $ do
--     it "can format text in a way that everyone likes" $
--       pending
--   </pre>
pending :: Expectation

-- | <a>pendingWith</a> is similar to <a>pending</a>, but it takes an
--   additional string argument that can be used to specify the reason for
--   why it's pending.
pendingWith :: String -> Expectation

-- | <a>parallel</a> marks all spec items of the given spec to be safe for
--   parallel evaluation.
parallel :: SpecWith a -> SpecWith a
type Spec = SpecWith ()
type SpecWith a = SpecM a ()

-- | A writer monad for <a>SpecTree</a> forests
newtype SpecM a r
SpecM :: (WriterT [SpecTree a] IO r) -> SpecM a r

-- | Convert a <a>Spec</a> to a forest of <a>SpecTree</a>s.
runSpecM :: SpecWith a -> IO [SpecTree a]

-- | Create a <a>Spec</a> from a forest of <a>SpecTree</a>s.
fromSpecList :: [SpecTree a] -> SpecWith a

-- | Run an IO action while constructing the spec tree.
--   
--   <a>SpecM</a> is a monad to construct a spec tree, without executing
--   any spec items. <tt>runIO</tt> allows you to run IO actions during
--   this construction phase. The IO action is always run when the spec
--   tree is constructed (e.g. even when <tt>--dry-run</tt> is specified).
--   If you do not need the result of the IO action to construct the spec
--   tree, <a>beforeAll</a> may be more suitable for your use case.
runIO :: IO r -> SpecM a r
mapSpecTree :: (SpecTree a -> SpecTree b) -> SpecWith a -> SpecWith b
mapSpecItem :: (ActionWith a -> ActionWith b) -> (Item a -> Item b) -> SpecWith a -> SpecWith b
mapSpecItem_ :: (Item a -> Item a) -> SpecWith a -> SpecWith a
modifyParams :: (Params -> Params) -> SpecWith a -> SpecWith a

-- | A type class for examples
class Example e where type Arg e type Arg e = () where {
    type family Arg e;
    type Arg e = ();
}
evaluateExample :: Example e => e -> Params -> (ActionWith (Arg e) -> IO ()) -> ProgressCallback -> IO Result
data Params
Params :: Args -> Int -> Params
[paramsQuickCheckArgs] :: Params -> Args
[paramsSmallCheckDepth] :: Params -> Int
defaultParams :: Params

-- | An <a>IO</a> action that expects an argument of type <tt>a</tt>
type ActionWith a = a -> IO ()
type Progress = (Int, Int)
type ProgressCallback = Progress -> IO ()

-- | The result of running an example
data Result
Success :: Result
Pending :: (Maybe String) -> Result
Fail :: (Maybe Location) -> String -> Result

-- | <tt>Location</tt> is used to represent source locations.
data Location
Location :: FilePath -> Int -> Int -> LocationAccuracy -> Location
[locationFile] :: Location -> FilePath
[locationLine] :: Location -> Int
[locationColumn] :: Location -> Int
[locationAccuracy] :: Location -> LocationAccuracy

-- | A marker for source locations
data LocationAccuracy

-- | The source location is accurate
ExactLocation :: LocationAccuracy

-- | The source location was determined on a best-effort basis and my be
--   wrong or inaccurate
BestEffort :: LocationAccuracy

-- | A tree is used to represent a spec internally. The tree is parametrize
--   over the type of cleanup actions and the type of the actual spec
--   items.
type SpecTree a = Tree (ActionWith a) (Item a)

-- | Internal tree data structure
data Tree c a
Node :: String -> [Tree c a] -> Tree c a
NodeWithCleanup :: c -> [Tree c a] -> Tree c a
Leaf :: a -> Tree c a

-- | <tt>Item</tt> is used to represent spec items internally. A spec item
--   consists of:
--   
--   <ul>
--   <li>a textual description of a desired behavior</li>
--   <li>an example for that behavior</li>
--   <li>additional meta information</li>
--   </ul>
--   
--   Everything that is an instance of the <a>Example</a> type class can be
--   used as an example, including QuickCheck properties, Hspec
--   expectations and HUnit assertions.
data Item a
Item :: String -> Maybe Location -> Bool -> (Params -> (ActionWith a -> IO ()) -> ProgressCallback -> IO Result) -> Item a

-- | Textual description of behavior
[itemRequirement] :: Item a -> String

-- | Source location of the spec item
[itemLocation] :: Item a -> Maybe Location

-- | A flag that indicates whether it is safe to evaluate this spec item in
--   parallel with other spec items
[itemIsParallelizable] :: Item a -> Bool

-- | Example for behavior
[itemExample] :: Item a -> Params -> (ActionWith a -> IO ()) -> ProgressCallback -> IO Result

-- | The <tt>specGroup</tt> function combines a list of specs into a larger
--   spec.
specGroup :: String -> [SpecTree a] -> SpecTree a

-- | The <tt>specItem</tt> function creates a spec item.
specItem :: (?loc :: CallStack, Example a) => String -> a -> SpecTree (Arg a)


module Test.Hspec.Core.Hooks

-- | Run a custom action before every spec item.
before :: IO a -> SpecWith a -> Spec

-- | Run a custom action before every spec item.
before_ :: IO () -> SpecWith a -> SpecWith a

-- | Run a custom action before every spec item.
beforeWith :: (b -> IO a) -> SpecWith a -> SpecWith b

-- | Run a custom action before the first spec item.
beforeAll :: IO a -> SpecWith a -> Spec

-- | Run a custom action before the first spec item.
beforeAll_ :: IO () -> SpecWith a -> SpecWith a

-- | Run a custom action after every spec item.
after :: ActionWith a -> SpecWith a -> SpecWith a

-- | Run a custom action after every spec item.
after_ :: IO () -> SpecWith a -> SpecWith a

-- | Run a custom action after the last spec item.
afterAll :: ActionWith a -> SpecWith a -> SpecWith a

-- | Run a custom action after the last spec item.
afterAll_ :: IO () -> SpecWith a -> SpecWith a

-- | Run a custom action before and/or after every spec item.
around :: (ActionWith a -> IO ()) -> SpecWith a -> Spec

-- | Run a custom action before and/or after every spec item.
around_ :: (IO () -> IO ()) -> SpecWith a -> SpecWith a

-- | Run a custom action before and/or after every spec item.
aroundWith :: (ActionWith a -> ActionWith b) -> SpecWith a -> SpecWith b


-- | This module contains formatters that can be used with
--   <a>hspecWith</a>.
module Test.Hspec.Core.Formatters
silent :: Formatter
specdoc :: Formatter
progress :: Formatter
failed_examples :: Formatter
data Formatter
Formatter :: FormatM () -> ([String] -> String -> FormatM ()) -> FormatM () -> (Handle -> Path -> Progress -> IO ()) -> (Path -> FormatM ()) -> (Path -> Either SomeException String -> FormatM ()) -> (Path -> Maybe String -> FormatM ()) -> FormatM () -> FormatM () -> Formatter
[headerFormatter] :: Formatter -> FormatM ()

-- | evaluated before each test group
--   
--   The given number indicates the position within the parent group.
[exampleGroupStarted] :: Formatter -> [String] -> String -> FormatM ()
[exampleGroupDone] :: Formatter -> FormatM ()

-- | used to notify the progress of the currently evaluated example
--   
--   <i>Note</i>: This is only called when interactive/color mode.
[exampleProgress] :: Formatter -> Handle -> Path -> Progress -> IO ()

-- | evaluated after each successful example
[exampleSucceeded] :: Formatter -> Path -> FormatM ()

-- | evaluated after each failed example
[exampleFailed] :: Formatter -> Path -> Either SomeException String -> FormatM ()

-- | evaluated after each pending example
[examplePending] :: Formatter -> Path -> Maybe String -> FormatM ()

-- | evaluated after a test run
[failedFormatter] :: Formatter -> FormatM ()

-- | evaluated after <tt>failuresFormatter</tt>
[footerFormatter] :: Formatter -> FormatM ()
data FormatM a

-- | Get the number of successful examples encountered so far.
getSuccessCount :: FormatM Int

-- | Get the number of pending examples encountered so far.
getPendingCount :: FormatM Int

-- | Get the number of failed examples encountered so far.
getFailCount :: FormatM Int

-- | Get the total number of examples encountered so far.
getTotalCount :: FormatM Int
data FailureRecord
FailureRecord :: Maybe Location -> Path -> Either SomeException String -> FailureRecord
[failureRecordLocation] :: FailureRecord -> Maybe Location
[failureRecordPath] :: FailureRecord -> Path
[failureRecordMessage] :: FailureRecord -> Either SomeException String

-- | Get the list of accumulated failure messages.
getFailMessages :: FormatM [FailureRecord]

-- | The random seed that is used for QuickCheck.
usedSeed :: FormatM Integer

-- | Get the used CPU time since the test run has been started.
getCPUTime :: FormatM (Maybe Double)

-- | Get the passed real time since the test run has been started.
getRealTime :: FormatM Double

-- | Append some output to the report.
write :: String -> FormatM ()

-- | The same as <a>write</a>, but adds a newline character.
writeLine :: String -> FormatM ()

-- | Append an empty line to the report.
--   
--   Calling this multiple times has the same effect as calling it once.

-- | <i>Deprecated: use <tt>writeLine ""</tt> instead</i>
newParagraph :: FormatM ()

-- | Set output color to cyan, run given action, and finally restore the
--   default color.
withInfoColor :: FormatM a -> FormatM a

-- | Set output color to green, run given action, and finally restore the
--   default color.
withSuccessColor :: FormatM a -> FormatM a

-- | Set output color to yellow, run given action, and finally restore the
--   default color.
withPendingColor :: FormatM a -> FormatM a

-- | Set output color to red, run given action, and finally restore the
--   default color.
withFailColor :: FormatM a -> FormatM a

-- | The function <a>formatException</a> converts an exception to a string.
--   
--   This is different from <a>show</a>. The type of the exception is
--   included, e.g.:
--   
--   <pre>
--   &gt;&gt;&gt; formatException (toException DivideByZero)
--   "ArithException (divide by zero)"
--   </pre>
--   
--   For <a>IOException</a>s the <a>IOErrorType</a> is included, as well.
formatException :: SomeException -> String


module Test.Hspec.Core.Runner

-- | Run given spec and write a report to <a>stdout</a>. Exit with
--   <a>exitFailure</a> if at least one spec item fails.
hspec :: Spec -> IO ()

-- | Run given spec with custom options. This is similar to <a>hspec</a>,
--   but more flexible.
hspecWith :: Config -> Spec -> IO ()

-- | Run given spec and returns a summary of the test run.
--   
--   <i>Note</i>: <a>hspecResult</a> does not exit with <a>exitFailure</a>
--   on failing spec items. If you need this, you have to check the
--   <a>Summary</a> yourself and act accordingly.
hspecResult :: Spec -> IO Summary

-- | Run given spec with custom options and returns a summary of the test
--   run.
--   
--   <i>Note</i>: <a>hspecWithResult</a> does not exit with
--   <a>exitFailure</a> on failing spec items. If you need this, you have
--   to check the <a>Summary</a> yourself and act accordingly.
hspecWithResult :: Config -> Spec -> IO Summary

-- | Summary of a test run.
data Summary
Summary :: Int -> Int -> Summary
[summaryExamples] :: Summary -> Int
[summaryFailures] :: Summary -> Int
data Config
Config :: Bool -> Bool -> Bool -> Bool -> Maybe (Path -> Bool) -> Maybe (Path -> Bool) -> Maybe Integer -> Maybe Int -> Maybe Int -> Maybe Int -> Int -> ColorMode -> Maybe Formatter -> Bool -> Either Handle FilePath -> Maybe Int -> Config
[configDryRun] :: Config -> Bool
[configPrintCpuTime] :: Config -> Bool
[configFastFail] :: Config -> Bool

-- | A predicate that is used to filter the spec before it is run. Only
--   examples that satisfy the predicate are run.
[configRerun] :: Config -> Bool
[configFilterPredicate] :: Config -> Maybe (Path -> Bool)
[configSkipPredicate] :: Config -> Maybe (Path -> Bool)
[configQuickCheckSeed] :: Config -> Maybe Integer
[configQuickCheckMaxSuccess] :: Config -> Maybe Int
[configQuickCheckMaxDiscardRatio] :: Config -> Maybe Int
[configQuickCheckMaxSize] :: Config -> Maybe Int
[configSmallCheckDepth] :: Config -> Int
[configColorMode] :: Config -> ColorMode
[configFormatter] :: Config -> Maybe Formatter
[configHtmlOutput] :: Config -> Bool
[configOutputFile] :: Config -> Either Handle FilePath
[configConcurrentJobs] :: Config -> Maybe Int
data ColorMode
ColorAuto :: ColorMode
ColorNever :: ColorMode
ColorAlways :: ColorMode

-- | A <a>Path</a> represents the location of an example within the spec
--   tree.
--   
--   It consists of a list of group descriptions and a requirement
--   description.
type Path = ([String], String)
defaultConfig :: Config

-- | Add a filter predicate to config. If there is already a filter
--   predicate, then combine them with <a>||</a>.
configAddFilter :: (Path -> Bool) -> Config -> Config
instance GHC.Show.Show Test.Hspec.Core.Runner.Summary
instance GHC.Classes.Eq Test.Hspec.Core.Runner.Summary
instance GHC.Base.Monoid Test.Hspec.Core.Runner.Summary


module Test.Hspec.Core.QuickCheck

-- | Use a modified <a>maxSuccess</a> for given spec.
modifyMaxSuccess :: (Int -> Int) -> SpecWith a -> SpecWith a

-- | Use a modified <a>maxDiscardRatio</a> for given spec.
modifyMaxDiscardRatio :: (Int -> Int) -> SpecWith a -> SpecWith a

-- | Use a modified <a>maxSize</a> for given spec.
modifyMaxSize :: (Int -> Int) -> SpecWith a -> SpecWith a