Boost Test Library: The Test Tools

Introduction
Reference
Implementation
Examples and tests

Introduction

Boost Test Library's Test Tools supply a toolbox to ease a creation and a maintenance of test programs and provide a uniform error reporting mechanism. The toolbox supplied in a form of macro and function declarations. While the functions can be called directly, the usual way to use Test Tools is via convenience macros. All macros arguments are calculated once, so it's safe to pass complex expressions in their place. All macros provide an error location: a file name and a line number. Boost Test Library's Test Tools are intended for test code rather than library or production code, where throwing exceptions, using assert(), boost::concept_check or BOOST_STATIC_ASSERT() may be more suitable ways to detect and report errors. To use the Test Tools you need to link with either the Test Execution Monitor or the Unit Test Framework. For list of all supplied Test Tools and usage examples see the reference.

Most of the tools supplied comes in three variations(levels): WARN, CHECK and REQUIRE ( for example BOOST_WARN_EQUAL, BOOST_CHECK_EQUAL, BOOST_REQUIRE_EQUAL). If an assertion designated by the tool passes, confirmation message could be printed in log output (note: to manage what messages appear in the test log stream set the proper log level). If an assertion designated by the tool failed, depending on the level following will happened (in some cases log message could be slightly different to reflect failed tool specifics):

Level	Output log content	Errors counter	Test execution
WARN	warning in <test case name>: condition <assertion description> is not satisfied	not affected	continues
CHECK	error in <test case name>: test <assertion description> failed	increased	continues
REQUIRE	fatal error in <test case name>: critical test <assertion description> failed	increased	aborts

Regularly you should use CHECK level tools to implement your assertions.You could use WARN level tools to validate aspects less important then correctness: performance, portability, usability etc. You should use REQUIRE level tools only if continuation of the test doesn't make sense if this assertions fails.

Among many tools in supplied toolbox, there are the BOOST_<level>_CLOSE tools that perform floating point comparison of values. See floating point comparison page for detailed description of used algorithms.

In addition to toolbox, the Test Tools also contains separate ostream_test_stream tool. This is class designed to significantly simplify correctness testing of the ostream based output procedures. For detailed description of it's interface and usage see the ostream_test_stream page.

Most of test tools direct values of their arguments to the output stream in some form of log statement. If arguments type does not support operator<<(...) interface you will get a compilation error. You could either implement above interface or prohibit Test tools from logging argument values for specified type. To do so use following statement on file level before first test case including statements failing to comply:

BOOST_TEST_DONT_PRINT_LOG_VALUE( ArgumentType ).

Even though supplied test tools cover wide range of possible checks and provide detailed report on cause of error in some cases you may want to implement and use custom predicate that perform complex check and produce intelligent report on failure. To satisfy this need test tools implements custom predicate support.

Boost Test Library: The Test Tools

Introduction

Implementation

boost/test/test_tools.hpp:

Boost/test/floating_point_comparison.hpp:

libs/test/test_tools.cpp:

Examples and Tests