-- 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.
@package tasty-hunit
@version 0.9.2


-- | Unit testing support for tasty, inspired by the HUnit package
module Test.Tasty.HUnit

-- | Create a <tt>Test</tt> for a HUnit <a>Assertion</a>
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

-- | When an assertion is evaluated, it will output a message if and only
--   if the assertion fails.
--   
--   Test cases are composed of a sequence of one or more assertions.
type Assertion = IO ()

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

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

-- | Signals an assertion failure if a non-empty message (i.e., a message
--   other than <tt>""</tt>) is passed.
assertString :: String -> 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) => String -> a -> a -> 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.
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>
type AssertionPredicate = IO Bool

-- | Used to signify that a data type can be converted to an assertion
--   predicate.
class AssertionPredicable t
assertionPredicate :: AssertionPredicable t => t -> AssertionPredicate

-- | Asserts that the condition obtained from the specified
--   <a>AssertionPredicable</a> holds.
(@?) :: (AssertionPredicable t) => t -> String -> Assertion
infix 1 @?

-- | 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) => 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) => a -> a -> Assertion
infix 1 @?=

-- | Exception thrown by <a>assertFailure</a> etc.
data HUnitFailure
HUnitFailure :: String -> HUnitFailure
instance Test.Tasty.Core.IsTest Test.Tasty.HUnit.TestCase
