CppUnit 2 Documentation

0.1

WARNING

This is a *very early* documenation release and is very incomplete (including this page).

Features

support aborting and non-aborting assertions
rich collection of assertions
rich assertion diagnostic
customizable conversion to string for complex assertion (equal, not equal...)
customizable equality comparison
customizable convertion to std::string for string assertion
support to ignore a specific assertion failures
...

A test case is exposed by instantiating a subclass of CppUT::AbstractTestCase. Each time a test case is executed, the runTest() method is called. This method calls the virtual methods setUp(), run() and tearDown(). The run() and tearDown() methods are only called if the setUp() method was successful (no assertion failure, no exception thrown). Only the run() method is required to be overridden. It is possible to make assertions in any of those methods. If any exception is thrown by the setUp(), run() or tearDown() methods, or if any of those methods makes an assertion that fails, the test case get a 'failed' status; otherwise it get a 'sucessful' status. The skipped status is never set automatically (see Skipping a test for detail).

There is mainly two ways to create test case:

Subclassing CppUT::AbstractTestCase and overridding at least run().
Instantiating CppUT::TestCase, which subclass CppUT::AbstractTestCase, and passing the function to execute in the constructor.

A test case is usually created using CppUT::makeTestCase() that instantiate CppUT::TestCase.

Notes that test case instantiation is usually only done when you need to create your own convenience test case macro or you are populating a TestSuite with parametrized TestCase. The framework provides severable way to create and register test case, see Creating TestCase: light Fixture, Creating TestCase: TestFixture, Creating TestCase: test functions.

Making assertions

When writing unit test, you check that the tested code behave as expected using assertions. In CppUnit 2 each assertion is provides in two forms:

as an aborting assertion
as a non-aborting assertion (a.k.a. checking assertion)

The difference between aborting and non-aborting assertions is that if an aborting assertion fails then the test is aborted, while if a non-aborting assertion failed, then the assertion is logged and the test continue. In CppUnit 1 only aborting assertion were provided.

When an aborting assertion failed, it throws the exception CppUT::AbortingAssertionException to abort the test. You must ensure that your test let this exception pass through (notes that it subclasses std::runtime_error).

All assertions are macros (to capture source location). By convention, the following naming prefix are used do distinguish aborting and non-aborting assertion:

CPPUT_ASSERT : aborting assertion
CPPUT_CHECK : non-arborting assertion

In the table below, all supported assertions without the above prefix will be listed.

Suffix Parameters Asserts that...

expression, [message] expression is true

_EXPR expression expression is true

_FALSE expression, [message] expression is false

_EXPR_FALSE expression expression is false

_EQUAL expected_value, actual_value, [message] expected_value == actual_value

_NOT_EQUAL expected_value, actual_value, [message] expected_value != actual_value

_DOUBLE_EQUAL expected_value, actual_value, tolerance, [message] fabs(expected_value - actual_value) <= tolerance

_THROW expression, ExpectedExceptionType expression throws an exception of type ExpectedExceptionType

_NO_THROW expression expression does not throw any exceptions

_ASSERTION_FAIL_MESSAGE assertion, message assertion fails

_ASSERTION_FAIL assertion assertion fails

_ASSERTION_PASS_MESSAGE assertion, message assertion passes

_ASSERTION_PASS assertion assertion passes

STR_START pattern, actual_string actual_string starts with pattern

STR_END pattern, actual_string actual_string ends with pattern

STR_END pattern, actual_string actual_string ends with pattern

STR_CONTAIN pattern, actual_string actual_string contains pattern

STR_EQUAL pattern, actual_string actual_string contains pattern

_SEQUENCE_EQUAL expected_ordered_sequence, actual_ordered_sequence expected_ordered_sequence and actual_ordered_sequence contains the same value in the same order.

_SET_EQUAL expected_unordered, actual_unordered_sequence expected_ordered_sequence and actual_ordered_sequence contains the same value regardless of the order.

_STL_SEQUENCE_EQUAL expected_ordered_sequence, actual_ordered_sequence expected_ordered_sequence and actual_ordered_sequence contains the same value in the same order.

_STL_SET_EQUAL expected_unordered, actual_unordered_sequence expected_ordered_sequence and actual_ordered_sequence contains the same value regardless of the order.

See module Assertions for the list of assertion macros.

[[notes: add double brace warning about macro parameter]]

Ignoring specific assertion failures

During a test, it is also possible to ignore an assertion failure. This is useful for example when doing some large refactoring that takes days and cause some test to break temporarily. With this feature, it is possible to indicate that some assertions are expected to fail and the test should not be considered to have failed. The assertion failure is still logged.

Use CPPUT_IGNORE_FAILURE() to ignore an assertion failure. See ignore_failure_demo for an example.

Loggin events

Often the same set of assertions is used in a loop over some input data. If a failure occurs, it is not possible to know on which iteration the failure occurred (unless the iteration was specified in the optional message parameter of the assertion).

CppUT::log() can be used to log a context. The list of log events and assertion failures is seen as a single test event sequence. See log_demo for an example.

Skipping a test

It is possible to force a test to be skipped using CPPUT_SKIP_TEST. The test status will be set to CppUT::TestStatus::skipped unless a failure occurred before.

Notes that a SkipTestException exception (a subclass of std::runtime_error) is thrown to abort the test.

Creating TestCase: TestFixture

A TestFixture is a class that implements multiple test cases sharing the same setUp/tearDown steps. Test cases are implements as "void test()" member function and each test case has its own instance of the test fixture.

A TestFixture support the following features:

TestFixture may be a template class
polymorphism: you can subclass a TestFixture and adds more test or override setUp/teardown virtual member functions.
TestExtendedData can be specified for each test
TestFixture test cases are grouped within a TestSuite
macro usage is limited to a declaration of the test member function and is clearly separated from code.

Creating TestCase: light Fixture

A Light test fixture is similar to a TestFixture but does not support the following features:

templated test class
can not subclass a light test fixture and share common test cases
macro usage is intrusive and hides member function declaration.

On the positive side, it is easier on the wrist.

Creating TestCase: test functions

A test case can be implemented as a plain C function "void test()".

Creating TestCase: using table fixture in test cases

Sometimes when writing test cases, you need to repeat the same test with different input values. Table fixture are a way to do this.

See also:: CPPUT_TEST_TABLE(), CPPUT_REGISTER_TEST_FUNCTION_TABLE_IN(), CPPUT_TEST_FUNCTION_TABLE_IN().

Creating TestCase: input fixture

Input fixture are intended to run functional test cases with externalized input data.

They usually rely on a reflection mecanism for interaction between the input data and testing.

Currently, only column based fixture is implemented. Data takes the form of a table. The header row indicates the role of each column. For each row, the same sequence of operation will be done:

if column name match an attribute name, then set the attribute value to the cell value
if column name match a method name, then invoke the method and pass the cell value
if column name ends with '?' then, if the column name match an attribute then get its value, otherwise invoke the matching method name and retrieve its return value. Finally, compares the retrieved value for equality with the cell value.

See also:: ColumnInputTest

Project links

License

The CppTL library is in public domain.

The CppUT and OpenTest library are under the LGPL with run-time exception.

Author:: Baptiste Lepilleur <blep@users.sourceforge.net>