Safe Haskell	None
Language	Haskell2010

Test.HUnitPlus.Base

Contents

Test Definition
- Extended Test Creation
Assertions
- Extended Assertion Functionality
Low-level Test Functions

Description

Basic definitions for the HUnitPlus library.

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

The assertion and test definition operators are the same as those found in the HUnit library. However, an important note is that the behavior of assertions in HUnit-Plus differs from those in HUnit. HUnit-Plus assertions do not stop executing a test if they fail, and are designed so that multiple assertions can be made by a single test. HUnit-Plus contains several "abort" functions, which can be used to terminate a test immediately.

HUnit-Plus test execution handles exceptions. An uncaught exception will cause the test to report an error (along with any failures and/or errors that have occurred so far), and test execution and reporting will continue.

The data structures for describing tests are the same as those in the Distribution.TestSuite module used by cabal's testing facilities. This allows for easy interfacing with cabal's detailed testing scheme.

This gives rise to a grid possible use cases: creating a test using the HUnit-Plus facilities vs. executing an existing Distribution.TestSuite test which was not created by the facilities in this module, and executing a test with HUnit-Plus vs executing it with another test framework. The executeTest function is designed to cope with either possible origin of a test, and the Testable instances are designed to produce tests which work as expected in either possible execution environment.

Synopsis

Test Definition

data Test :: *

Constructors

Test TestInstance
Group
Fields groupName :: String concurrently :: Bool If true, then children of this group may be run in parallel. Note that this setting is not inherited by children. In particular, consider a group F with "concurrently = False" that has some children, including a group T with "concurrently = True". The children of group T may be run concurrently with each other, as long as none are run at the same time as any of the direct children of group F. groupTests :: [Test]
ExtraOptions [OptionDescr] Test

Instances

Testable Test

data TestInstance :: *

Constructors

TestInstance

Fields

run :: IO Progress: Perform the test.
name :: String: A name for the test, unique within a test suite.
tags :: [String]: Users can select groups of tests by their tags.
options :: [OptionDescr]: Descriptions of the options recognized by this test.
setOption :: String -> String -> Either String TestInstance: Try to set the named option to the given value. Returns an error message if the option is not supported or the value could not be correctly parsed; otherwise, a TestInstance with the option set to the given value is returned.

data TestSuite Source

Definition for a test suite. This is intended to be a top-level (ie. non-nestable) container for tests. Test suites have a name, a list of options with default values (which can be overridden either at runtime or statically using ExtraOptions), and a set of Tests to be run.

Individual tests are described using definitions found in cabal's Distribution.TestSuite module, to allow for straightforward integration with cabal testing facilities.

Constructors

TestSuite
Fields suiteName :: !String The name of the test suite. suiteConcurrently :: !Bool Whether or not to run the tests concurrently. suiteOptions :: [(String, String)] A list of all options used by this suite, and the default values for those options. suiteTests :: [Test] The tests in the suite.

Extended Test Creation

class Testable t where Source

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

Minimal complete definition

testNameTags

Methods

testNameTags :: String -> [String] -> t -> Test Source

Create a test with a given name and tag set from a Testable value

testName :: String -> t -> Test Source

Create a test with a given name and no tags from a Testable value

testTags :: [String] -> t -> Test Source

Create a test with a given name and no tags from a Testable value

test :: Testable t => t -> Test Source

Create a test with a synthetic name and no tags from a Testable value

Instances

Testable Test
Testable Test
Testable t => Testable [t]
Assertable t => Testable (IO t)

(~=?) infix 1 Source

Arguments

:: (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 Source

Arguments

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

(~:) :: Testable t => String -> t -> Test infixr 0 Source

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 Source

Arguments

:: Assertable 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.

Assertions

type Assertion = IO () Source

assertSuccess :: Assertion Source

Signal that an assertion succeeded. This will log that an assertion has been made.

assertFailure Source

Arguments

:: String	The failure message
-> Assertion

Unconditionally signal that a failure has occurred. This will not stop execution, but will record the failure, resulting in a failed test.

abortFailure :: String -> Assertion Source

Signal that a failure has occurred and stop the test immediately. Note that if an error has been logged already, the test will be reported as an error.

abortError :: String -> Assertion Source

Signal than an error has occurred and stop the test immediately.

assertBool Source

Arguments

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

Asserts that the specified condition holds.

assertString Source

Arguments

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

assertStringWithPrefix Source

Arguments

:: String	Prefix to attach to the string if not null
-> String	String to assert is null
-> Assertion

Signals an assertion failure if a non-empty message (i.e., a message other than "") is passed. Allows a prefix to be supplied for the assertion failure message.

assertEqual Source

Arguments

:: (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.

Extended Assertion Functionality

class Assertable t where Source

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 not assert multiple, independent conditions.

If more complex arrangements of assertions are needed, Tests and Testable should be used.

Minimal complete definition

assertWithMsg

Methods

assertWithMsg :: String -> t -> Assertion Source

Assertion with a failure message

assert :: t -> Assertion Source

Assertion with no failure message

Instances

Assertable Bool
Assertable ()
Assertable Progress
Assertable Result
ListAssertable t => Assertable [t]
Assertable t => Assertable (IO t)

(@=?) infix 1 Source

Arguments

:: (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 Source

Arguments

:: (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 Source

Arguments

:: Assertable t
=> t	A value of which the asserted condition is predicated
-> String	A message that is displayed if the assertion fails
-> Assertion

Shorthand for assertBool.

Low-level Test Functions

executeTest Source

Arguments

:: Reporter us	The reporter to use for reporting results.
-> State	The HUnit internal state.
-> us	The reporter state.
-> IO Progress	The test to run.
-> IO (Double, State, us)

Does the actual work of executing a test. This maintains the necessary bookkeeping recording assertions and failures, It also sets up exception handlers and times the test.

logAssert :: IO () Source

Record that one assertion has been checked.

logFailure :: String -> IO () Source

Record a failure, along with a message.

logError :: String -> IO () Source

Record an error, along with a message.

withPrefix :: String -> IO () -> IO () Source

Execute the given computation with a message prefix.

getErrors :: IO (Maybe String) Source

Get a combined failure message, if there is one.

getFailures :: IO (Maybe String) Source

Get a combined failure message, if there is one.