-- 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.
@package hspec
@version 1.0.0


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

-- | The result of running an example.
data Result
Success :: Result
Pending :: String -> Result
Fail :: String -> Result
type UnevaluatedSpec = Spec AnyExample
type EvaluatedSpec = Spec Result
data Spec a
SpecGroup :: String -> [Spec a] -> Spec a
SpecExample :: String -> a -> Spec a
describe :: String -> [Spec a] -> Spec a

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

-- | 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 -> UnevaluatedSpec
class Example a
evaluateExample :: Example a => a -> IO Result

-- | An existentially quantified <tt>Example</tt>. This way they can be
--   mixed within the same set of Specs
data AnyExample
AnyExample :: a -> AnyExample

-- | Declare an example as not successful or failing but pending some other
--   work. 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 "waiting for clarification from the designers")
--     ]
--   </pre>
pending :: String -> Result
failedCount :: [EvaluatedSpec] -> Int
failure :: [EvaluatedSpec] -> Bool
success :: [EvaluatedSpec] -> Bool
isFailure :: Result -> Bool

-- | Create a more readable display of a quantity of something.
quantify :: (Show a, Num a, Eq a) => a -> String -> String
instance Eq Result
instance Example AnyExample
instance Example Result
instance Example Bool


-- | 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 -> 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 -> 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 = [UnevaluatedSpec]

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

-- | Use in place of <tt>hspec</tt> 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 a] -> Spec a

-- | 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 -> UnevaluatedSpec
toExitCode :: Bool -> ExitCode


-- | This module contains the runners that take a set of specs, specified
--   in a monadic style, evaluate their examples, and report to a given
--   handle.
--   
--   The three functions you'll use the most are <a>hspec</a>,
--   <a>describe</a>, and <a>it</a>. Here is an example of functions that
--   format and unformat phone numbers and the specs for them.
--   
--   <pre>
--   import Test.Hspec.Monadic
--   import Test.Hspec.QuickCheck
--   import Test.Hspec.HUnit
--   import Test.QuickCheck
--   import Test.HUnit
--   
--   main = hspec mySpecs
--   </pre>
--   
--   Since the specs are often used to tell you what to implement, it's
--   best to start with undefined functions. Once we have some specs, then
--   you can implement each behavior one at a time, ensuring that each
--   behavior is met and there is no undocumented behavior.
--   
--   <pre>
--   unformatPhoneNumber :: String -&gt; String
--   unformatPhoneNumber number = undefined
--   
--   formatPhoneNumber :: String -&gt; String
--   formatPhoneNumber number = undefined
--   </pre>
--   
--   The <a>describe</a> function takes a list of behaviors and examples
--   bound together with the <a>it</a> function
--   
--   <pre>
--   mySpecs = describe "unformatPhoneNumber" $ do
--   </pre>
--   
--   A boolean expression can act as a behavior's example.
--   
--   <pre>
--   it "removes dashes, spaces, and parenthesies" $
--     unformatPhoneNumber "(555) 555-1234" == "5555551234"
--   </pre>
--   
--   The <a>pending</a> function marks a behavior as pending an example.
--   The example doesn't count as failing.
--   
--   <pre>
--   it "handles non-US phone numbers" $
--     pending "need to look up how other cultures format phone numbers"
--   </pre>
--   
--   An HUnit <tt>Test</tt> can act as a behavior's example. (must import
--   <tt>Test.Hspec.HUnit</tt>)
--   
--   <pre>
--   it "removes the \"ext\" prefix of the extension" $ do
--     let expected = "5555551234135"
--         actual   = unformatPhoneNumber "(555) 555-1234 ext 135"
--     assertEqual "remove extension" expected actual
--   </pre>
--   
--   An <tt>IO()</tt> action is treated like an HUnit <tt>TestCase</tt>.
--   (must import <tt>Test.Hspec.HUnit</tt>)
--   
--   <pre>
--   it "converts letters to numbers" $ do
--     let expected = "6862377"
--         actual   = unformatPhoneNumber "NUMBERS"
--     assertEqual "letters to numbers" expected actual
--   </pre>
--   
--   The <tt>property</tt> function allows a QuickCheck property to act as
--   an example. (must import <tt>Test.Hspec.HUnit</tt>)
--   
--   <pre>
--     it "can add and remove formatting without changing the number" $ property $
--       forAll phoneNumber $ \ n -&gt; unformatPhoneNumber (formatPhoneNumber n) == n
--   
--   phoneNumber :: Gen String
--   phoneNumber = do
--     nums &lt;- elements [7,10,11,12,13,14,15]
--     vectorOf nums (elements "0123456789")
--   </pre>
module Test.Hspec.Monadic
data Spec a

-- | The result of running an example.
data Result
type Specs = SpecM ()
describe :: String -> Specs -> Specs
it :: Example v => String -> v -> Specs

-- | Declare an example as not successful or failing but pending some other
--   work. 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 "waiting for clarification from the designers")
--     ]
--   </pre>
pending :: String -> Result

-- | 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 <tt>hspec</tt> 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]

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

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

-- | DEPRECATED: Use <a>sequence_</a> instead.
descriptions :: [Specs] -> Specs
instance Monad SpecM


-- | Importing this module allows you to use an <tt>HUnit</tt> test case as
--   an example for a behavior. You can use an explicit <tt>TestCase</tt>
--   data constructor or use an <tt>IO()</tt> action. For an <tt>IO()</tt>
--   action, any exception means the example failed; otherwise, it's
--   successfull. Any output from the example to stdout is ignored. If you
--   need to write out for debugging, you can write to stderr or a file
--   handle.
--   
--   <pre>
--   describe "cutTheDeck" [
--     it "puts the first half of a list after the last half"
--        (TestCase $ assertEqual "cut the deck" [3,4,1,2] (cutTheDeck [1,2,3,4])),
--   
--     it "restores an even sized list when cut twice"
--        (assertEqual "cut the deck twice" [3,4,1,2] (cutTheDeck (cutTheDeck [1,2,3,4]))),
--     ]
--   </pre>
module Test.Hspec.HUnit
instance Example Test
instance Example (IO ())


-- | Importing this module allows you to use a QuickCheck property as an
--   example for a behavior. Use the <tt>property</tt> function to indicate
--   a QuickCkeck property. Any output from the example to stdout is
--   ignored. If you need to write out for debugging, you can write to
--   stderr or a file handle.
--   
--   <pre>
--   describe "cutTheDeck" [
--     it "puts the first half of a list after the last half"
--        (property $ \ xs -&gt; let top = take (length xs `div` 2) xs
--                                bot = drop (length xs `div` 2) xs
--                            in cutTheDeck xs == bot ++ top),
--   
--     it "restores an even sized list when cut twice"
--        (property $ \ xs -&gt; even (length xs) ==&gt; cutTheDeck (cutTheDeck xs) == xs)
--     ]
--   </pre>
module Test.Hspec.QuickCheck
property :: Testable prop => prop -> Property

-- | Monadic DSL shortcut, use this instead of <tt>it</tt>
prop :: Testable t => String -> t -> Specs
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.
--   
--   The three functions you'll use the most are <a>hspec</a>,
--   <a>describe</a>, and <a>it</a>. Here is an example of functions that
--   format and unformat phone numbers and the specs for them.
--   
--   <pre>
--   import Test.Hspec
--   import Test.Hspec.QuickCheck
--   import Test.Hspec.HUnit
--   import Test.QuickCheck
--   import Test.HUnit
--   
--   main = hspec mySpecs
--   </pre>
--   
--   Since the specs are often used to tell you what to implement, it's
--   best to start with undefined functions. Once we have some specs, then
--   you can implement each behavior one at a time, ensuring that each
--   behavior is met and there is no undocumented behavior.
--   
--   <pre>
--   unformatPhoneNumber :: String -&gt; String
--   unformatPhoneNumber number = undefined
--   
--   formatPhoneNumber :: String -&gt; String
--   formatPhoneNumber number = undefined
--   </pre>
--   
--   The <a>describe</a> function takes a list of behaviors and examples
--   bound together with the <a>it</a> function
--   
--   <pre>
--   mySpecs = [describe "unformatPhoneNumber" [
--   </pre>
--   
--   A boolean expression can act as a behavior's example.
--   
--   <pre>
--   it "removes dashes, spaces, and parenthesies"
--       (unformatPhoneNumber "(555) 555-1234" == "5555551234"),
--   </pre>
--   
--   The <a>pending</a> function marks a behavior as pending an example.
--   The example doesn't count as failing.
--   
--   <pre>
--   it "handles non-US phone numbers"
--       (pending "need to look up how other cultures format phone numbers"),
--   </pre>
--   
--   An HUnit <tt>Test</tt> can act as a behavior's example. (must import
--   <tt>Test.Hspec.HUnit</tt>)
--   
--   <pre>
--   it "removes the \"ext\" prefix of the extension"
--       (TestCase $ let expected = "5555551234135"
--                       actual   = unformatPhoneNumber "(555) 555-1234 ext 135"
--                   in assertEqual "remove extension" expected actual),
--   </pre>
--   
--   An <tt>IO()</tt> action is treated like an HUnit <tt>TestCase</tt>.
--   (must import <tt>Test.Hspec.HUnit</tt>)
--   
--   <pre>
--   it "converts letters to numbers"
--       (do
--         let expected = "6862377"
--         let actual   = unformatPhoneNumber "NUMBERS"
--         assertEqual "letters to numbers" expected actual),
--   </pre>
--   
--   The <tt>property</tt> function allows a QuickCheck property to act as
--   an example. (must import <tt>Test.Hspec.QuickCheck</tt>)
--   
--   <pre>
--     it "can add and remove formatting without changing the number"
--         (property $ forAll phoneNumber $
--           \ n -&gt; unformatPhoneNumber (formatPhoneNumber n) == n)
--     ]]
--   
--   phoneNumber :: Gen String
--   phoneNumber = do
--     nums &lt;- elements [7,10,11,12,13,14,15]
--     vectorOf nums (elements "0123456789")
--   </pre>
module Test.Hspec
data Spec a

-- | The result of running an example.
data Result
type Specs = [UnevaluatedSpec]
describe :: String -> [Spec a] -> Spec a

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

-- | Declare an example as not successful or failing but pending some other
--   work. 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 "waiting for clarification from the designers")
--     ]
--   </pre>
pending :: String -> Result

-- | 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 <tt>hspec</tt> 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 :: [Spec a] -> [Spec a]