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


-- | A Testing Framework for Haskell
--   
--   Hspec is a testing framework for Haskell. It is inspired by the Ruby
--   library RSpec. Some of Hspec's distinctive features are:
--   
--   <ul>
--   <li>a friendly DSL for defining tests</li>
--   <li>integration with QuickCheck, SmallCheck, and HUnit</li>
--   <li>parallel test execution</li>
--   <li>automatic discovery of test files</li>
--   </ul>
--   
--   The Hspec Manual is at <a>http://hspec.github.io/</a>.
@package hspec
@version 1.11.2

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
--   
--   <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 :: 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.
--   
--   This is different from <a>show</a>. The type of the exception is
--   included, e.g. <a>ArithException</a> is turned into:
--   
--   <pre>
--   <a>ArithException (divide by zero)</a>
--   </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 a
evaluateExample :: Example a => a -> Params -> (IO () -> 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

-- | Convert a <a>Spec</a> to a forest of <a>SpecTree</a>s.
runSpecM :: Spec -> IO [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
BuildSpecs :: (IO [SpecTree]) -> SpecTree
SpecItem :: String -> Item -> SpecTree
data Item
Item :: Bool -> (Params -> (IO () -> IO ()) -> ProgressCallback -> IO Result) -> Item
itemIsParallelizable :: Item -> Bool
itemExample :: Item -> Params -> (IO () -> IO ()) -> ProgressCallback -> 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


-- | Hspec is a testing framework 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

-- | An alias for <a>it</a>.
specify :: 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 before all spec items.
beforeAll :: 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 an IO action while constructing the spec tree.
--   
--   <a>SpecM</a> is a monad to construct a spec tree, without executing
--   any spec items. <a>runIO</a> 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).
runIO :: IO a -> SpecM 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