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


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

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

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

-- | A description of the specific behavior being tested.
--   
--   A description of the specific behavior being tested.
requirement :: Spec -> String

-- | The status of the example of this behavior.
result :: Spec -> Result

-- | The level of nestedness.
--   
--   The level of nestedness.
depth :: Spec -> Int
UnevaluatedSpec :: String -> String -> AnyExample -> Int -> Spec

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

-- | A description of the specific behavior being tested.
--   
--   A description of the specific behavior being tested.
requirement :: Spec -> String

-- | An example of this behavior.
example :: Spec -> AnyExample

-- | The level of nestedness.
--   
--   The level of nestedness.
depth :: Spec -> Int
data Formatter
Formatter :: String -> (Handle -> Spec -> IO ()) -> (Handle -> Spec -> [String] -> IO ()) -> (Handle -> Spec -> [String] -> IO ()) -> (Handle -> Spec -> [String] -> IO ()) -> (Handle -> [String] -> IO ()) -> (Handle -> [Spec] -> Double -> IO ()) -> Bool -> Formatter
formatterName :: Formatter -> String
exampleGroupStarted :: Formatter -> Handle -> Spec -> IO ()
examplePassed :: Formatter -> Handle -> Spec -> [String] -> IO ()
exampleFailed :: Formatter -> Handle -> Spec -> [String] -> IO ()
examplePending :: Formatter -> Handle -> Spec -> [String] -> IO ()
errorsFormatter :: Formatter -> Handle -> [String] -> IO ()
footerFormatter :: Formatter -> Handle -> [Spec] -> Double -> IO ()
usesFormatting :: Formatter -> Bool
describe :: String -> [[Spec]] -> [Spec]

-- | Combine a list of descriptions.
descriptions :: [[Spec]] -> [Spec]
evaluateSpec :: Spec -> IO 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]
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 :: [Spec] -> Int
failure :: [Spec] -> Bool
success :: [Spec] -> 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


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


-- | 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
restoreFormat :: Handle -> IO ()
silent :: Bool -> Formatter
specdoc :: Bool -> Formatter
progress :: Bool -> Formatter
failed_examples :: Bool -> Formatter


-- | 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 [Spec]

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

-- | Create a document of the given specs and write it to the given handle.
--   THIS IS LIKELY TO CHANGE
hHspecWithFormat :: Formatter -> Handle -> Specs -> IO 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]
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 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" $ 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"
--       (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.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

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

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

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

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

-- | 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. (Note that descriptions can also be
--   combined with monadic sequencing.)
descriptions :: [Specs] -> Specs

-- | 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 [Spec]

-- | Converts a specs created with <a>describe</a> into a monadic
--   <a>describe</a>.
fromSpecList :: [Spec] -> Specs
runSpecM :: Specs -> [Spec]
instance Monad SpecM


-- | 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. 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 a => a -> QuickCheckProperty a

-- | Monadic DSL shortcut, use this instead of <tt>it</tt>
prop :: Testable t => String -> t -> Specs
instance Testable t => Example (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 <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

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

-- | The result of running an example.
data Result
type Specs = [Spec]
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]

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

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

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

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