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


-- | Alpha version of Hspec 2.0
--   
--   This is an alpha release of Hspec 2.0. If you are looking for a stable
--   solution for testing Haskell code, use the 1.x series of Hspec:
--   <a>http://hspec.github.io/</a>
@package hspec2
@version 0.3.4

module Test.Hspec.HUnit

-- | Convert a HUnit test suite to a spec. This can be used to run existing
--   HUnit tests with Hspec.
fromHUnitTest :: Test -> Spec


-- | This module contains formatters that can be used with
--   <a>hspecWith</a>.
module Test.Hspec.Formatters
silent :: Formatter
specdoc :: Formatter
progress :: Formatter
failed_examples :: Formatter
data Formatter
Formatter :: FormatM () -> (Int -> [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 -> Int -> [String] -> String -> FormatM ()
exampleGroupDone :: Formatter -> FormatM ()

-- | used to notify the progress of the currently evaluated example
--   
--   NOTE: 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 :: Path -> Either SomeException String -> FailureRecord
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.
newParagraph :: FormatM ()

-- | Set output to color 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

-- | Convert an exception to a string.
--   
--   The type of the exception is included. Here is an example:
--   
--   <pre>
--   &gt;&gt;&gt; import Control.Applicative
--   
--   &gt;&gt;&gt; import Control.Exception
--   
--   &gt;&gt;&gt; either formatException show &lt;$&gt; (try . evaluate) (1 `div` 0)
--   "ArithException (divide by zero)"
--   </pre>
formatException :: SomeException -> String
class IsFormatter a
toFormatter :: IsFormatter a => a -> IO Formatter
instance IsFormatter Formatter
instance IsFormatter (IO Formatter)


module Test.Hspec.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 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>hspecWith</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.
hspecWith :: 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 -> Maybe (Path -> Bool) -> Maybe Integer -> Maybe Int -> Maybe Int -> Maybe Int -> Int -> ColorMode -> Formatter -> Bool -> Either Handle FilePath -> 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.
configFilterPredicate :: 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 -> Formatter
configHtmlOutput :: Config -> Bool
configHandle :: Config -> Either Handle FilePath
data ColorMode
ColorAuto :: ColorMode
ColorNever :: ColorMode
ColorAlways :: ColorMode

-- | A tuple that represents the location of an example within a spec.
--   
--   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

-- | This function is used by <tt>hspec-discover</tt>. It is not part of
--   the public API and may change at any time.
hspecWithFormatter :: IsFormatter a => a -> Spec -> IO ()
instance Eq Summary
instance Show Summary
instance Monoid Summary


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

-- | A type class for examples.
class Example e where type family 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
type Progress = (Int, Int)
type ProgressCallback = Progress -> IO ()

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

-- | A writer monad for <a>SpecTree</a> forests.
data SpecM a r

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

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

-- | Internal representation of a spec.
data SpecTree a
SpecGroup :: String -> [SpecTree a] -> SpecTree a
BuildSpecs :: (IO [SpecTree a]) -> SpecTree a
SpecItem :: String -> (Item a) -> SpecTree a
data Item a
Item :: Bool -> (Params -> (ActionWith a -> IO ()) -> ProgressCallback -> IO Result) -> Item a
itemIsParallelizable :: Item a -> Bool
itemExample :: Item a -> Params -> (ActionWith a -> IO ()) -> ProgressCallback -> IO Result

-- | An <a>IO</a> action that expects an argument of type <tt>a</tt>.
type ActionWith a = a -> IO ()
mapSpecItem :: (Item a -> Item b) -> SpecWith a -> SpecWith b
modifyParams :: (Params -> Params) -> SpecWith a -> SpecWith a

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

-- | Create a spec item.
it :: Example e => String -> e -> SpecTree (Arg e)


-- | Hspec is a testing library for Haskell.
--   
--   This is the library reference for Hspec. The <a>User's Manual</a>
--   contains more in-depth documentation.
module Test.Hspec
type Spec = SpecWith ()
type SpecWith a = SpecM a ()

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

-- | A type class for examples.
class Example e where type family Arg e

-- | Combine a list of specs into a larger spec.
describe :: String -> SpecWith a -> SpecWith a

-- | An alias for <a>describe</a>.
context :: String -> SpecWith a -> SpecWith a

-- | Create 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 :: Example e => String -> e -> SpecWith (Arg e)

-- | This is a type restricted version of <a>id</a>. It can be used to get
--   better error messages on type mismatches.
--   
--   Compare e.g.
--   
--   <pre>
--   it "exposes some behavior" $ example $ do
--     putStrLn
--   </pre>
--   
--   with
--   
--   <pre>
--   it "exposes some behavior" $ do
--     putStrLn
--   </pre>
example :: Expectation -> Expectation

-- | Specifies a pending example.
--   
--   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

-- | Specifies a pending example with a reason for why it's pending.
--   
--   <pre>
--   describe "fancyFormatter" $ do
--     it "can format text in a way that everyone likes" $
--       pendingWith "waiting for clarification from the designers"
--   </pre>
pendingWith :: String -> Expectation

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

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

-- | Run a custom action before all spec items.
beforeAll :: IO a -> SpecWith a -> SpecWith ()

-- | Run a custom action before all spec items.
beforeAllWith :: (b -> IO a) -> SpecWith a -> SpecWith b

-- | 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 () -> Spec -> Spec

-- | 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 ()) -> Spec -> Spec

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

-- | Run examples of given spec in parallel.
parallel :: SpecWith a -> SpecWith a

-- | 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 ()


module Test.Hspec.QuickCheck

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

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

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

-- | <pre>
--   prop ".." $
--     ..
--   </pre>
--   
--   is a shortcut for
--   
--   <pre>
--   it ".." $ property $
--     ..
--   </pre>
prop :: Testable prop => String -> prop -> Spec