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

-- | HUnit support for the Tasty test framework.
--   
--   HUnit support for the Tasty test framework.
--   
--   Note that this package does not depend on HUnit but implements the
--   relevant subset of its API. The name is a legacy of the early versions
--   of tasty-hunit and of test-framework-hunit, which did depend on HUnit.
@package tasty-hunit
@version 0.10.2

-- | Unit testing support for tasty, inspired by the HUnit package.
--   
--   Here's an example (a single tasty test case consisting of three
--   assertions):
--   
--   
--   import Test.Tasty
--   import Test.Tasty.HUnit
--   
--   main = defaultMain $
--     testCase "Example test case" $ do
--       -- assertion no. 1 (passes)
--       2 + 2 @?= 4
--       -- assertion no. 2 (fails)
--       assertBool "the list is not empty" $ null [1]
--       -- assertion no. 3 (would have failed, but won't be executed because
--       -- the previous assertion has already failed)
--       "foo" @?= "bar"
--   
module Test.Tasty.HUnit

-- | Turn an Assertion into a tasty test case
testCase :: TestName -> Assertion -> TestTree

-- | Like testCase, except in case the test succeeds, the returned
--   string will be shown as the description. If the empty string is
--   returned, it will be ignored.
testCaseInfo :: TestName -> IO String -> TestTree

-- | Create a multi-step unit test.
--   
--   Example:
--   
--   
--   main = defaultMain $ testCaseSteps "Multi-step test" $ \step -> do
--     step "Preparing..."
--     -- do something
--   
--     step "Running part 1"
--     -- do something
--   
--     step "Running part 2"
--     -- do something
--     assertFailure "BAM!"
--   
--     step "Running part 3"
--     -- do something
--   
--   
--   The step calls are mere annotations. They let you see which
--   steps were performed successfully, and which step failed.
--   
--   You can think of step as putStrLn, except
--   putStrLn would mess up the output with the console reporter and
--   get lost with the others.
--   
--   For the example above, the output will be
--   
--   
--   Multi-step test: FAIL
--     Preparing...
--     Running part 1
--     Running part 2
--       BAM!
--   
--   1 out of 1 tests failed (0.00s)
--   
--   
--   Note that:
--   
--   
--   
- Tasty still treats this as a single test, even though it consists
--   of multiple steps.
--   
- The execution stops after the first failure. When we are looking
--   at a failed test, we know that all displayed steps but the last
--   one were successful, and the last one failed. The steps after
--   the failed one are not displayed, since they didn't run.
--   
testCaseSteps :: TestName -> ((String -> IO ()) -> Assertion) -> TestTree

-- | Unconditionally signals that a failure has occured. All other
--   assertions can be expressed with the form:
--   
--   
--   if conditionIsMet
--       then return ()
--       else assertFailure msg
--   
assertFailure :: HasCallStack => String -> IO a

-- | Asserts that the specified condition holds.
assertBool :: HasCallStack => String -> Bool -> Assertion

-- | Asserts that the specified actual value is equal to the expected
--   value. The output message will contain the prefix, the expected value,
--   and the actual value.
--   
--   If the prefix is the empty string (i.e., ""), then the prefix
--   is omitted and only the expected and actual values are output.
assertEqual :: (Eq a, Show a, HasCallStack) => String -> a -> a -> Assertion

-- | Asserts that the specified actual value is equal to the expected value
--   (with the expected value on the left-hand side).
(@=?) :: (Eq a, Show a, HasCallStack) => a -> a -> Assertion
infix 1 @=?

-- | Asserts that the specified actual value is equal to the expected value
--   (with the actual value on the left-hand side).
(@?=) :: (Eq a, Show a, HasCallStack) => a -> a -> Assertion
infix 1 @?=

-- | An infix and flipped version of assertBool. E.g. instead of
--   
--   
--   assertBool "Non-empty list" (null [1])
--   
--   
--   you can write
--   
--   
--   null [1] @? "Non-empty list"
--   
--   
--   @? is also overloaded to accept IO Bool
--   predicates, so instead of
--   
--   
--   do
--     e <- doesFileExist "test"
--     e @? "File does not exist"
--   
--   
--   you can write
--   
--   
--   doesFileExist "test" @? "File does not exist"
--   
(@?) :: (AssertionPredicable t, HasCallStack) => t -> String -> Assertion
infix 1 @?

-- | An ad-hoc class used to overload the @? operator.
--   
--   The only intended instances of this class are Bool and
--   IO Bool.
--   
--   You shouldn't need to interact with this class directly.
class AssertionPredicable t
assertionPredicate :: AssertionPredicable t => t -> IO Bool

-- | An assertion is simply an IO action. Assertion failure is
--   indicated by throwing an exception, typically HUnitFailure.
--   
--   Instead of throwing the exception directly, you should use functions
--   like assertFailure and assertBool.
--   
--   Test cases are composed of a sequence of one or more assertions.
type Assertion = IO ()

-- | Exception thrown by assertFailure etc.
data HUnitFailure
HUnitFailure :: Maybe SrcLoc -> String -> HUnitFailure

-- | Request a CallStack.
--   
--   NOTE: The implicit parameter ?callStack :: CallStack is an
--   implementation detail and should not be considered part of the
--   CallStack API, we may decide to change the implementation in
--   the future.
type HasCallStack = ?callStack :: CallStack

-- | Signals an assertion failure if a non-empty message (i.e., a message
--   other than "") is passed.

-- | Deprecated: Why not use assertBool instead?
assertString :: HasCallStack => String -> Assertion

-- | Allows the extension of the assertion mechanism.
--   
--   Since an Assertion can be a sequence of Assertions and
--   IO actions, there is a fair amount of flexibility of what can
--   be achieved. As a rule, the resulting Assertion should be the
--   body of a TestCase or part of a TestCase; it should
--   not be used to assert multiple, independent conditions.
--   
--   If more complex arrangements of assertions are needed, Test
--   and Testable should be used.

-- | Deprecated: This class or type seems dubious. If you have a good
--   use case for it, please create an issue for tasty. Otherwise, it may
--   be removed in a future version.
class Assertable t
assert :: Assertable t => t -> Assertion

-- | The result of an assertion that hasn't been evaluated yet.
--   
--   Most test cases follow the following steps:
--   
--   
--   
- Do some processing or an action.
--   
- Assert certain conditions.
--   
--   
--   However, this flow is not always suitable. AssertionPredicate
--   allows for additional steps to be inserted without the initial action
--   to be affected by side effects. Additionally, clean-up can be done
--   before the test case has a chance to end. A potential work flow is:
--   
--   
--   
- Write data to a file.
--   
- Read data from a file, evaluate conditions.
--   
- Clean up the file.
--   
- Assert that the side effects of the read operation meet certain
--   conditions.
--   
- Assert that the conditions evaluated in step 2 are met.
--   

-- | Deprecated: This class or type seems dubious. If you have a good
--   use case for it, please create an issue for tasty. Otherwise, it may
--   be removed in a future version.
type AssertionPredicate = IO Bool
instance Test.Tasty.Core.IsTest Test.Tasty.HUnit.TestCase
