Boost.Test > Components > The Test Tools
Boost Test logo

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.

Implementation

The Test Tools are implemented in three modules: two header files and one source file.

boost/test/test_tools.hpp:

contains definition for the convenience macros, some template based Test Tools implementation functions and class ostream_test_stream.

Boost/test/floating_point_comparison.hpp:

contains implementation for the floating point comparison algorithms, used by BOOST_CHECK_CLOSE tool. They also could be used directly.

libs/test/test_tools.cpp:

contains definition for the most Test Tools implementation functions and class ostream_test_stream implementation.

Since this component is not intended to be used standalone, there are no special compilation instruction for it.

Examples and Tests

test_exec_example
test_exec_fail2
test_exec_fail3
test_tools_test
test_fp_comparisons