Safe Haskell	Safe-Inferred
Language	Haskell2010

Test.HUnit.Base

Contents

Declaring tests
Making assertions
Extending the assertion functionality
Test execution

Description

Basic definitions for the HUnit library.

This module contains what you need to create assertions and test cases and combine them into test suites.

This module also provides infrastructure for implementing test controllers (which are used to execute tests). See Test.HUnit.Text for a great example of how to implement a test controller.

Synopsis

data Test
- = TestCase Assertion
- | TestList [Test]
- | TestLabel String Test
(~=?) :: (HasCallStack, Eq a, Show a) => a -> a -> Test
(~?=) :: (HasCallStack, Eq a, Show a) => a -> a -> Test
(~:) :: (HasCallStack, Testable t) => String -> t -> Test
(~?) :: (HasCallStack, AssertionPredicable t) => t -> String -> Test
assertFailure :: HasCallStack => String -> IO a
assertBool :: HasCallStack => String -> Bool -> Assertion
assertEqual :: (HasCallStack, Eq a, Show a) => String -> a -> a -> Assertion
assertString :: HasCallStack => String -> Assertion
type Assertion = IO ()
(@=?) :: (HasCallStack, Eq a, Show a) => a -> a -> Assertion
(@?=) :: (HasCallStack, Eq a, Show a) => a -> a -> Assertion
(@?) :: (HasCallStack, AssertionPredicable t) => t -> String -> Assertion
class Assertable t where
- assert :: HasCallStack => t -> Assertion
class ListAssertable t where
- listAssert :: HasCallStack => [t] -> Assertion
type AssertionPredicate = IO Bool
class AssertionPredicable t where
- assertionPredicate :: t -> AssertionPredicate
class Testable t where
- test :: HasCallStack => t -> Test
data State = State {
- path :: Path
- counts :: Counts
}
data Counts = Counts {
- cases, tried, errors, failures :: Int
}
type Path = [Node]
data Node
- = ListItem Int
- | Label String
testCasePaths :: Test -> [Path]
testCaseCount :: Test -> Int
type ReportStart us = State -> us -> IO us
type ReportProblem us = Maybe SrcLoc -> String -> State -> us -> IO us
performTest :: ReportStart us -> ReportProblem us -> ReportProblem us -> us -> Test -> IO (Counts, us)

Declaring tests

data Test #

The basic structure used to create an annotated tree of test cases.

Constructors

TestCase Assertion	A single, independent test case composed.
TestList [Test]	A set of `Test`s sharing the same level in the hierarchy.
TestLabel String Test	A name or description for a subtree of the `Test`s.

Instances

Instances details

Show Test #
Instance details Defined in Test.HUnit.Base Methods showsPrec :: Int -> Test -> ShowS show :: Test -> String showList :: [Test] -> ShowS
Testable Test #
Instance details Defined in Test.HUnit.Base Methods test :: Test -> Test #

(~=?) infix 1 #

Arguments

:: (HasCallStack, Eq a, Show a)
=> a	The expected value
-> a	The actual value
-> Test

Shorthand for a test case that asserts equality (with the expected value on the left-hand side, and the actual value on the right-hand side).

(~?=) infix 1 #

Arguments

:: (HasCallStack, Eq a, Show a)
=> a	The actual value
-> a	The expected value
-> Test

Shorthand for a test case that asserts equality (with the actual value on the left-hand side, and the expected value on the right-hand side).

(~:) :: (HasCallStack, Testable t) => String -> t -> Test infixr 0 #

Creates a test from the specified Testable, with the specified label attached to it.

Since Test is Testable, this can be used as a shorthand way of attaching a TestLabel to one or more tests.

(~?) infix 1 #

Arguments

:: (HasCallStack, AssertionPredicable t)
=> t	A value of which the asserted condition is predicated
-> String	A message that is displayed on test failure
-> Test

Creates a test case resulting from asserting the condition obtained from the specified AssertionPredicable.

Making assertions

assertFailure #

Arguments

:: HasCallStack
=> String	A message that is displayed with the assertion failure
-> IO a

Unconditionally signals that a failure has occured. All other assertions can be expressed with the form:

   if conditionIsMet
       then IO ()
       else assertFailure msg

assertBool #

Arguments

:: HasCallStack
=> String	The message that is displayed if the assertion fails
-> Bool	The condition
-> Assertion

Asserts that the specified condition holds.

assertEqual #

Arguments

:: (HasCallStack, Eq a, Show a)
=> String	The message prefix
-> a	The expected value
-> a	The actual value
-> 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.

assertString #

Arguments

:: HasCallStack
=> String	The message that is displayed with the assertion failure
-> Assertion

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

type Assertion = IO () #

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.

(@=?) infix 1 #

Arguments

:: (HasCallStack, Eq a, Show a)
=> a	The expected value
-> a	The actual value
-> Assertion

Asserts that the specified actual value is equal to the expected value (with the expected value on the left-hand side).

(@?=) infix 1 #

Arguments

:: (HasCallStack, Eq a, Show a)
=> a	The actual value
-> a	The expected value
-> Assertion

Asserts that the specified actual value is equal to the expected value (with the actual value on the left-hand side).

(@?) infix 1 #

Arguments

:: (HasCallStack, AssertionPredicable t)
=> t	A value of which the asserted condition is predicated
-> String	A message that is displayed if the assertion fails
-> Assertion

Asserts that the condition obtained from the specified AssertionPredicable holds.

Extending the assertion functionality

class Assertable t where #

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, Tests and Testable should be used.

Methods

assert :: HasCallStack => t -> Assertion #

Instances

Instances details

Assertable Bool #
Instance details Defined in Test.HUnit.Base Methods assert :: Bool -> Assertion #
Assertable () #
Instance details Defined in Test.HUnit.Base Methods assert :: () -> Assertion #
ListAssertable t => Assertable [t] #
Instance details Defined in Test.HUnit.Base Methods assert :: [t] -> Assertion #
Assertable t => Assertable (IO t) #
Instance details Defined in Test.HUnit.Base Methods assert :: IO t -> Assertion #

class ListAssertable t where #

A specialized form of Assertable to handle lists.

Methods

listAssert :: HasCallStack => [t] -> Assertion #

Instances

Instances details

ListAssertable Char #
Instance details Defined in Test.HUnit.Base Methods listAssert :: [Char] -> Assertion #

type AssertionPredicate = IO Bool #

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.

class AssertionPredicable t where #

Used to signify that a data type can be converted to an assertion predicate.

Methods

assertionPredicate :: t -> AssertionPredicate #

Instances

Instances details

AssertionPredicable Bool #
Instance details Defined in Test.HUnit.Base Methods assertionPredicate :: Bool -> AssertionPredicate #
AssertionPredicable t => AssertionPredicable (IO t) #
Instance details Defined in Test.HUnit.Base Methods assertionPredicate :: IO t -> AssertionPredicate #

class Testable t where #

Provides a way to convert data into a Test or set of Test.

Methods

test :: HasCallStack => t -> Test #

Instances

Instances details

Testable Test #
Instance details Defined in Test.HUnit.Base Methods test :: Test -> Test #
Testable t => Testable [t] #
Instance details Defined in Test.HUnit.Base Methods test :: [t] -> Test #
Assertable t => Testable (IO t) #
Instance details Defined in Test.HUnit.Base Methods test :: IO t -> Test #

Test execution

Note: the rest of the functionality in this module is intended for implementors of test controllers. If you just want to run your tests cases, simply use a test controller, such as the text-based controller in Test.HUnit.Text.

data State #

Keeps track of the remaining tests and the results of the performed tests. As each test is performed, the path is removed and the counts are updated as appropriate.

Constructors

State
Fields path :: Path counts :: Counts

Instances

Instances details

Eq State #
Instance details Defined in Test.HUnit.Base Methods (==) :: State -> State -> Bool (/=) :: State -> State -> Bool
Read State #
Instance details Defined in Test.HUnit.Base Methods readsPrec :: Int -> ReadS State readList :: ReadS [State] readPrec :: ReadPrec State readListPrec :: ReadPrec [State]
Show State #
Instance details Defined in Test.HUnit.Base Methods showsPrec :: Int -> State -> ShowS show :: State -> String showList :: [State] -> ShowS

data Counts #

A data structure that hold the results of tests that have been performed up until this point.

Constructors

Counts
Fields cases, tried, errors, failures :: Int

Instances

Instances details

Eq Counts #
Instance details Defined in Test.HUnit.Base Methods (==) :: Counts -> Counts -> Bool (/=) :: Counts -> Counts -> Bool
Read Counts #
Instance details Defined in Test.HUnit.Base Methods readsPrec :: Int -> ReadS Counts readList :: ReadS [Counts] readPrec :: ReadPrec Counts readListPrec :: ReadPrec [Counts]
Show Counts #
Instance details Defined in Test.HUnit.Base Methods showsPrec :: Int -> Counts -> ShowS show :: Counts -> String showList :: [Counts] -> ShowS

type Path = [Node] #

Uniquely describes the location of a test within a test hierarchy. Node order is from test case to root.

data Node #

Composed into Paths.

Constructors

ListItem Int
Label String

Instances

Instances details

Eq Node #
Instance details Defined in Test.HUnit.Base Methods (==) :: Node -> Node -> Bool (/=) :: Node -> Node -> Bool
Read Node #
Instance details Defined in Test.HUnit.Base Methods readsPrec :: Int -> ReadS Node readList :: ReadS [Node] readPrec :: ReadPrec Node readListPrec :: ReadPrec [Node]
Show Node #
Instance details Defined in Test.HUnit.Base Methods showsPrec :: Int -> Node -> ShowS show :: Node -> String showList :: [Node] -> ShowS

testCasePaths :: Test -> [Path] #

Determines the paths for all TestCases in a tree of Tests.

testCaseCount :: Test -> Int #

Counts the number of TestCases in a tree of Tests.

type ReportStart us = State -> us -> IO us #

Report generator for reporting the start of a test run.

type ReportProblem us = Maybe SrcLoc -> String -> State -> us -> IO us #

Report generator for reporting problems that have occurred during a test run. Problems may be errors or assertion failures.

performTest #

Arguments

:: ReportStart us	report generator for the test run start
-> ReportProblem us	report generator for errors during the test run
-> ReportProblem us	report generator for assertion failures during the test run
-> us
-> Test	the test to be executed
-> IO (Counts, us)

Performs a test run with the specified report generators.

This handles the actual running of the tests. Most developers will want to use HUnit.Text.runTestTT instead. A developer could use this function to execute tests via another IO system, such as a GUI, or to output the results in a different manner (e.g., upload XML-formatted results to a webservice).

Note that the counts in a start report do not include the test case being started, whereas the counts in a problem report do include the test case just finished. The principle is that the counts are sampled only between test case executions. As a result, the number of test case successes always equals the difference of test cases tried and the sum of test case errors and failures.