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


-- | Behavior-Driven Development for Haskell
--   
--   Behavior-Driven Development for Haskell
--   
--   Hspec is roughly based on the Ruby library RSpec. However, Hspec is
--   just a framework for running HUnit and QuickCheck tests. Compared to
--   other options, it provides a much nicer syntax that makes tests very
--   easy to read.
--   
--   The Hspec Manual is at <a>http://hspec.github.io/</a>.
@package hspec
@version 1.8.1.1

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
instance Example Test


-- | 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) -> Args -> 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)
configQuickCheckArgs :: Config -> Args
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 a
evaluateExample :: Example a => a -> Params -> (IO () -> IO ()) -> IO Result
data Params
Params :: Args -> Int -> (Progress -> IO ()) -> Params
paramsQuickCheckArgs :: Params -> Args
paramsSmallCheckDepth :: Params -> Int
paramsReportProgress :: Params -> Progress -> IO ()
type Progress = (Int, Int)

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

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

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

-- | Internal representation of a spec.
data SpecTree
SpecGroup :: String -> [SpecTree] -> SpecTree
SpecItem :: Item -> SpecTree
data Item
Item :: Bool -> String -> (Params -> (IO () -> IO ()) -> IO Result) -> Item
itemIsParallelizable :: Item -> Bool
itemRequirement :: Item -> String
itemExample :: Item -> Params -> (IO () -> IO ()) -> IO Result
mapSpecItem :: (Item -> Item) -> Spec -> Spec
modifyParams :: (Params -> Params) -> Spec -> Spec

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

-- | Create a spec item.
it :: Example a => String -> a -> SpecTree

-- | <i>Deprecated: use `[SpecTree]` instead </i>
type Specs = [SpecTree]

-- | <i>Deprecated: use <a>hspecWith</a> instead </i>
hspecB :: [SpecTree] -> IO Bool

-- | <i>Deprecated: use <a>hspec</a> instead </i>
hspecX :: [SpecTree] -> IO ()

-- | <i>Deprecated: use <a>hspecWith</a> instead </i>
hHspec :: Handle -> [SpecTree] -> IO Summary

-- | <i>Deprecated: use <a>hspec</a> instead </i>
hspec :: [SpecTree] -> IO ()


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

-- | A type class for examples.
class Example a

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

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

-- | 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 a => String -> a -> Spec

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

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

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

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

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


-- | <i>Deprecated: use <a>Test.Hspec</a>, <a>Test.Hspec.Runner</a> or
--   <a>Test.Hspec.Core</a> instead </i>
module Test.Hspec.Monadic
type Spec = SpecM ()

-- | A type class for examples.
class Example a

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

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

-- | 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 a => String -> a -> Spec

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

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

-- | Summary of a test run.
data Summary
Summary :: Int -> Int -> Summary
summaryExamples :: Summary -> Int
summaryFailures :: Summary -> Int

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

-- | Create a <a>Spec</a> from a forest of <a>SpecTree</a>s.
fromSpecList :: [SpecTree] -> Spec
type Specs = Spec
descriptions :: [Spec] -> Spec
hspecB :: Spec -> IO Bool
hspecX :: Spec -> IO ()
hHspec :: Handle -> Spec -> IO Summary


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
property :: Testable prop => prop -> Property

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