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


-- | Unit testing support for tasty, inspired by the HUnit package.
--   
--   Here's an example (a single tasty test case consisting of three
--   assertions):
--   
--   <pre>
--   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"
--   </pre>
module Test.Tasty.HUnit

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

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

-- | Unconditionally signals that a failure has occured. All other
--   assertions can be expressed with the form:
--   
--   <pre>
--   if conditionIsMet
--       then return ()
--       else assertFailure msg
--   </pre>
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., <tt>""</tt>), 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 <a>assertBool</a>. E.g. instead of
--   
--   <pre>
--   assertBool "Non-empty list" (null [1])
--   </pre>
--   
--   you can write
--   
--   <pre>
--   null [1] @? "Non-empty list"
--   </pre>
--   
--   <a>@?</a> is also overloaded to accept <tt><a>IO</a> <a>Bool</a></tt>
--   predicates, so instead of
--   
--   <pre>
--   do
--     e &lt;- doesFileExist "test"
--     e @? "File does not exist"
--   </pre>
--   
--   you can write
--   
--   <pre>
--   doesFileExist "test" @? "File does not exist"
--   </pre>
(@?) :: (AssertionPredicable t, HasCallStack) => t -> String -> Assertion
infix 1 @?

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

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

-- | Exception thrown by <a>assertFailure</a> etc.
data HUnitFailure
HUnitFailure :: Maybe SrcLoc -> String -> HUnitFailure
type HasCallStack = ?callStack :: CallStack

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

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

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

-- | <i>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.</i>
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:
--   
--   <ol>
--   <li>Do some processing or an action.</li>
--   <li>Assert certain conditions.</li>
--   </ol>
--   
--   However, this flow is not always suitable. <tt>AssertionPredicate</tt>
--   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:
--   
--   <ol>
--   <li>Write data to a file.</li>
--   <li>Read data from a file, evaluate conditions.</li>
--   <li>Clean up the file.</li>
--   <li>Assert that the side effects of the read operation meet certain
--   conditions.</li>
--   <li>Assert that the conditions evaluated in step 2 are met.</li>
--   </ol>

-- | <i>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.</i>
type AssertionPredicate = IO Bool
instance Test.Tasty.Core.IsTest Test.Tasty.HUnit.TestCase
