-- 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.
--   
--   New to Hspec? Start with the introductory documentation:
--   <a>http://hspec.github.com/</a>
@package hspec
@version 1.1.2


-- | This module contains the core types, constructors, classes, instances,
--   and utility functions common to hspec.
module Test.Hspec.Core

-- | Internal representation of a spec.
--   
--   This will be made abstract with the next release. If you still need
--   access to any constructors, open an issue and describe your use case:
--   <a>https://github.com/hspec/hspec/issues</a>
data SpecTree a
SpecGroup :: String -> [SpecTree a] -> SpecTree a
SpecExample :: String -> a -> SpecTree a

-- | A type class for examples.
--   
--   To use an HUnit <a>Test</a> or an <a>Assertion</a> as an example you
--   need to import <a>Test.Hspec.HUnit</a>.
--   
--   To use a QuickCheck <a>Property</a> as an example you need to import
--   <a>Test.Hspec.QuickCheck</a>.
class Example a
evaluateExample :: Example a => a -> IO Result

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

-- | DEPRECATED: This is no longer needed (it's just an alias for <a>id</a>
--   now).
descriptions :: Specs -> Specs
describe :: String -> [Spec] -> Spec

-- | Create a set of specifications for a specific type being described.
--   Once you know what you want specs for, use this.
--   
--   <pre>
--   describe "abs" [
--     it "returns a positive number given a negative number"
--       (abs (-1) == 1)
--     ]
--   </pre>
it :: Example a => String -> a -> Spec
data Spec
type Specs = [Spec]
type UnevaluatedSpec = Spec
type EvaluatedSpec = SpecTree Result

-- | Create a more readable display of a quantity of something.
quantify :: (Show a, Num a, Eq a) => a -> String -> String
type AnyExample = IO Result
safeEvaluateExample :: AnyExample -> IO Result
success :: [EvaluatedSpec] -> Bool
failure :: [EvaluatedSpec] -> Bool
isFailure :: Result -> Bool
failedCount :: [EvaluatedSpec] -> Int


-- | This module contains formatters that take a set of specs and write to
--   a given handle. They follow a structure similar to RSpec formatters.
module Test.Hspec.Formatters
silent :: Formatter
specdoc :: Formatter
progress :: Formatter
failed_examples :: Formatter
data Formatter
Formatter :: String -> (Int -> String -> FormatM ()) -> (Int -> String -> FormatM ()) -> (Int -> String -> String -> FormatM ()) -> (Int -> String -> Maybe String -> FormatM ()) -> FormatM () -> FormatM () -> Formatter
formatterName :: Formatter -> String

-- | evaluated before each test group
exampleGroupStarted :: Formatter -> Int -> String -> FormatM ()

-- | evaluated after each successful example
exampleSucceeded :: Formatter -> Int -> String -> FormatM ()

-- | evaluated after each failed example
exampleFailed :: Formatter -> Int -> String -> String -> FormatM ()

-- | evaluated after each pending example
examplePending :: Formatter -> Int -> String -> 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

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

-- | Get the used CPU time since the test run has been started.
getCPUTime :: FormatM 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 ()

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


-- | This module contains the runners that take a set of specs, evaluate
--   their examples, and report to a given handle.
module Test.Hspec.Runner
type Specs = [Spec]

-- | Create a document of the given specs and write it to stdout.
hspec :: Specs -> IO [EvaluatedSpec]

-- | Use in place of <a>hspec</a> to also exit the program with an
--   <tt>ExitCode</tt>
hspecX :: Specs -> IO a

-- | Use in place of hspec to also give a <tt>Bool</tt> success indication
hspecB :: Specs -> IO Bool

-- | Create a document of the given specs and write it to the given handle.
--   
--   <pre>
--   writeReport filename specs = withFile filename WriteMode (\h -&gt; hHspec h specs)
--   </pre>
hHspec :: Handle -> Specs -> IO [EvaluatedSpec]

-- | Create a document of the given specs and write it to the given handle.
--   THIS IS LIKELY TO CHANGE
hHspecWithFormat :: Formatter -> Bool -> Handle -> Specs -> IO [EvaluatedSpec]
describe :: String -> [Spec] -> Spec

-- | Create a set of specifications for a specific type being described.
--   Once you know what you want specs for, use this.
--   
--   <pre>
--   describe "abs" [
--     it "returns a positive number given a negative number"
--       (abs (-1) == 1)
--     ]
--   </pre>
it :: Example a => String -> a -> Spec
toExitCode :: Bool -> ExitCode


-- | There is a monadic and a non-monadic API. This is the documentation
--   for the monadic API. The monadic API is suitable for most use cases,
--   and it is more stable than the non-monadic API.
--   
--   For documentation on the non-monadic API look at <a>Test.Hspec</a>.
module Test.Hspec.Monadic
type Spec = SpecM ()

-- | A type class for examples.
--   
--   To use an HUnit <a>Test</a> or an <a>Assertion</a> as an example you
--   need to import <a>Test.Hspec.HUnit</a>.
--   
--   To use a QuickCheck <a>Property</a> as an example you need to import
--   <a>Test.Hspec.QuickCheck</a>.
class Example a
data Pending
describe :: String -> Spec -> Spec
context :: String -> Spec -> Spec
it :: Example v => String -> v -> Spec

-- | A pending example.
--   
--   If you want to report on a behavior but don't have an example yet, use
--   this.
--   
--   <pre>
--   describe "fancyFormatter" $ do
--     it "can format text in a way that everyone likes" $
--       pending
--   </pre>
--   
--   You can give an optional reason for why it's pending.
--   
--   <pre>
--   describe "fancyFormatter" $ do
--     it "can format text in a way that everyone likes" $
--       pending "waiting for clarification from the designers"
--   </pre>
pending :: String -> Pending

-- | Create a document of the given specs and write it to stdout.
hspec :: Spec -> IO [EvaluatedSpec]

-- | Use in place of hspec to also give a <tt>Bool</tt> success indication
hspecB :: Spec -> IO Bool

-- | Use in place of <a>hspec</a> to also exit the program with an
--   <tt>ExitCode</tt>
hspecX :: Spec -> IO a

-- | Create a document of the given specs and write it to the given handle.
--   
--   <pre>
--   writeReport filename specs = withFile filename WriteMode (\h -&gt; hHspec h specs)
--   </pre>
hHspec :: Handle -> Spec -> IO [EvaluatedSpec]

-- | Convert a monadic spec into a non-monadic spec.
runSpecM :: Spec -> [Spec]

-- | Convert a non-monadic spec into a monadic spec.
fromSpecList :: [Spec] -> Spec

-- | DEPRECATED: Use <a>sequence_</a> instead.
descriptions :: [Spec] -> Spec

-- | DEPRECATED: Use <a>Spec</a> instead
type Specs = SpecM ()
instance Monad SpecM


-- | Importing this module allows you to use an <tt>HUnit</tt> <a>Test</a>
--   as an example for a behavior. You can use an explicit <a>TestCase</a>
--   data constructor or use an <a>Assertion</a>. For an
--   <tt>Assertion</tt>, any exception means the example failed; otherwise,
--   it's successfull.
--   
--   NOTE: Any output from the example to <tt>stdout</tt> is ignored. If
--   you need to write out for debugging, you can write to <tt>stderr</tt>
--   or a file handle.
--   
--   <pre>
--   import Test.Hspec.Monadic
--   import Test.Hspec.HUnit ()
--   import Test.HUnit
--   
--   main :: IO ()
--   main = hspecX $ do
--     describe "reverse" $ do
--       it "reverses a list" $ do
--         reverse [1, 2, 3] @?= [3, 2, 1]
--   
--       it "gives the original list, if applied twice" $ TestCase $
--         (reverse . reverse) [1, 2, 3] @?= [1, 2, 3]
--   </pre>
module Test.Hspec.HUnit
instance Example Test
instance Example Assertion


-- | Importing this module allows you to use a QuickCheck <a>Property</a>
--   as an example for a behavior. Use <a>property</a> to turn any
--   <a>Testable</a> into a <tt>Property</tt>.
--   
--   NOTE: Any output from the example to <tt>stdout</tt> is ignored. If
--   you need to write out for debugging, you can write to <tt>stderr</tt>
--   or a file handle.
--   
--   <pre>
--   import Test.Hspec.Monadic
--   import Test.Hspec.QuickCheck
--   
--   main :: IO ()
--   main = hspecX $ do
--     describe "reverse" $ do
--       it "gives the original list, if applied twice" $ property $
--         \xs -&gt; (reverse . reverse) xs == (xs :: [Int])
--   </pre>
module Test.Hspec.QuickCheck
property :: Testable prop => prop -> Property

-- | Monadic DSL shortcut, use this instead of <a>it</a>.
prop :: Testable t => String -> t -> Spec
instance Example Property


-- | Hspec is a Behaviour-Driven Development tool for Haskell programmers.
--   BDD is an approach to software development that combines Test-Driven
--   Development, Domain Driven Design, and Acceptance Test-Driven
--   Planning. Hspec helps you do the TDD part of that equation, focusing
--   on the documentation and design aspects of TDD.
--   
--   Hspec (and the preceding intro) are based on the Ruby library RSpec.
--   Much of what applies to RSpec also applies to Hspec. Hspec ties
--   together <i>descriptions</i> of behavior and <i>examples</i> of that
--   behavior. The examples can also be run as tests and the output
--   summarises what needs to be implemented.
--   
--   NOTE: There is a monadic and a non-monadic API. This is the
--   documentation for the non-monadic API. The monadic API is more stable,
--   so you may prefer it over this one. For documentation on the monadic
--   API look at <a>Test.Hspec.Monadic</a>.
module Test.Hspec
data Spec
type Specs = [Spec]

-- | A type class for examples.
--   
--   To use an HUnit <a>Test</a> or an <a>Assertion</a> as an example you
--   need to import <a>Test.Hspec.HUnit</a>.
--   
--   To use a QuickCheck <a>Property</a> as an example you need to import
--   <a>Test.Hspec.QuickCheck</a>.
class Example a
data Pending
describe :: String -> [Spec] -> Spec

-- | Create a set of specifications for a specific type being described.
--   Once you know what you want specs for, use this.
--   
--   <pre>
--   describe "abs" [
--     it "returns a positive number given a negative number"
--       (abs (-1) == 1)
--     ]
--   </pre>
it :: Example a => String -> a -> Spec

-- | A pending example.
--   
--   If you want to report on a behavior but don't have an example yet, use
--   this.
--   
--   <pre>
--   describe "fancyFormatter" [
--     it "can format text in a way that everyone likes" $
--       pending
--   ]
--   </pre>
--   
--   You can give an optional reason for why it's pending.
--   
--   <pre>
--   describe "fancyFormatter" [
--     it "can format text in a way that everyone likes" $
--       pending "waiting for clarification from the designers"
--   ]
--   </pre>
pending :: String -> Pending

-- | Create a document of the given specs and write it to stdout.
hspec :: Specs -> IO [EvaluatedSpec]

-- | Use in place of hspec to also give a <tt>Bool</tt> success indication
hspecB :: Specs -> IO Bool

-- | Use in place of <a>hspec</a> to also exit the program with an
--   <tt>ExitCode</tt>
hspecX :: Specs -> IO a

-- | Create a document of the given specs and write it to the given handle.
--   
--   <pre>
--   writeReport filename specs = withFile filename WriteMode (\h -&gt; hHspec h specs)
--   </pre>
hHspec :: Handle -> Specs -> IO [EvaluatedSpec]

-- | DEPRECATED: This is no longer needed (it's just an alias for <a>id</a>
--   now).
descriptions :: Specs -> Specs