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


-- | Behavior Driven Development for Haskell
--   
--   Behavior Driven Development for Haskell
--   
--   Hspec is based on the Ruby library RSpec - so 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
--   then be run as tests and the output summarises what needs to be
--   implemented.
@package hspec
@version 0.3.0

module Test.Hspec.Internal

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

-- | Everything needed to specify and show a specific behavior.
data Spec
Spec :: String -> String -> Result -> Spec

-- | What is being tested, usually the name of a type.
name :: Spec -> String

-- | The specific behavior being tested.
requirement :: Spec -> String

-- | The status of this behavior.
result :: Spec -> 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>
describe :: String -> [IO (String, Result)] -> IO [Spec]

-- | Combine a list of descriptions.
descriptions :: [IO [Spec]] -> IO [Spec]

-- | Evaluate a Result. Any exceptions (undefined, etc.) are treated as
--   failures.
safely :: Result -> IO Result

-- | Anything that can be used as an example of a behavior.
class SpecVerifier a
it :: SpecVerifier a => String -> a -> IO (String, Result)

-- | 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.
documentSpecs :: [Spec] -> [String]

-- | Create a document of the given group of specs.
documentGroup :: [String] -> [Spec] -> ([String], [String])

-- | Create a document of the given spec.
documentSpec :: [String] -> Spec -> ([String], String)

-- | Create a summary of how long it took to run the examples.
timingSummary :: Double -> String
failedCount :: [Spec] -> Int

-- | Create a summary of how many specs exist and how many examples failed.
successSummary :: [Spec] -> String

-- | Create a document of the given specs. This does not track how much
--   time it took to check the examples. If you want a description of each
--   spec and don't need to know how long it tacks to check, use this.
pureHspec :: [Spec] -> [String]
pureHspecB :: [Spec] -> ([String], Bool)

-- | Create a document of the given specs and write it to stdout. This does
--   track how much time it took to check the examples. Use this if you
--   want a description of each spec and do need to know how long it tacks
--   to check the examples or want to write to stdout.
hspec :: IO [Spec] -> IO ()

-- | Same as <a>hspec</a> except it returns a bool indicating if all
--   examples ran without failures
hspecB :: IO [Spec] -> IO Bool

-- | Same as <a>hspec</a> except the program exits successfull if all
--   examples ran without failures or with an errorcode of 1 if any
--   examples failed.
hspecX :: IO [Spec] -> IO a
toExitCode :: Bool -> ExitCode

-- | Create a document of the given specs and write it to the given handle.
--   This does track how much time it took to check the examples. Use this
--   if you want a description of each spec and do need to know how long it
--   tacks to check the examples or want to write to a file or other
--   handle.
--   
--   <pre>
--   writeReport filename specs = withFile filename WriteMode (\ h -&gt; hHspec h specs)
--   </pre>
hHspec :: Handle -> IO [Spec] -> IO Bool

-- | Create a more readable display of a quantity of something.
quantify :: Num a => a -> String -> String
instance Eq Result
instance SpecVerifier Result
instance SpecVerifier Bool


-- | 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.
--   
--   <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 SpecVerifier Test
instance SpecVerifier (IO ())


-- | Importing this module allows you to use a QuickCheck property as an
--   example for a behavior. Use the <a>property</a> function to indicate a
--   QuickCkeck property.
--   
--   <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 a => a -> QuickCheckProperty a
instance Testable t => SpecVerifier (QuickCheckProperty t)


-- | 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 hiding (property)
--   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 <a>Test</a> 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 <a>TestCase</a>.
--   (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 <a>property</a> 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

-- | Everything needed to specify and show a specific behavior.
data Spec

-- | The result of running an example.
data 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>
describe :: String -> [IO (String, Result)] -> IO [Spec]

-- | Create a description and example of a behavior, a list of these is
--   used by <a>describe</a>. Once you know what you want to specify, use
--   this.
--   
--   <pre>
--   describe "closeEnough" [
--     it "is true if two numbers are almost the same"
--       (1.001 `closeEnough` 1.002),
--   
--     it "is false if two numbers are not almost the same"
--       (not $ 1.001 `closeEnough` 1.003)
--     ]
--   </pre>
it :: SpecVerifier a => String -> a -> IO (String, Result)

-- | Create a document of the given specs and write it to stdout. This does
--   track how much time it took to check the examples. Use this if you
--   want a description of each spec and do need to know how long it tacks
--   to check the examples or want to write to stdout.
hspec :: IO [Spec] -> IO ()

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

-- | Combine a list of descriptions.
descriptions :: [IO [Spec]] -> IO [Spec]

-- | Create a document of the given specs and write it to the given handle.
--   This does track how much time it took to check the examples. Use this
--   if you want a description of each spec and do need to know how long it
--   tacks to check the examples or want to write to a file or other
--   handle.
--   
--   <pre>
--   writeReport filename specs = withFile filename WriteMode (\ h -&gt; hHspec h specs)
--   </pre>
hHspec :: Handle -> IO [Spec] -> IO Bool

-- | Same as <a>hspec</a> except the program exits successfull if all
--   examples ran without failures or with an errorcode of 1 if any
--   examples failed.
hspecX :: IO [Spec] -> IO a

-- | Same as <a>hspec</a> except it returns a bool indicating if all
--   examples ran without failures
hspecB :: IO [Spec] -> IO Bool

-- | Create a document of the given specs. This does not track how much
--   time it took to check the examples. If you want a description of each
--   spec and don't need to know how long it tacks to check, use this.
pureHspec :: [Spec] -> [String]
pureHspecB :: [Spec] -> ([String], Bool)