![]() Boost Test Library: Test Tools Home BOOST_CHECKPOINT Example and Test Programs Introduction Boost Test Library's Test Tools supply a toolbox to ease
a creation and a maintenance of test programs. The toolbox supplied in a form of
macros 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(), or BOOST_STATIC_ASSERT() may be more suitable
ways to detect and report errors. BenefitsUsing of Test Tools simplify writing of test program and provide a uniform error reporting mechanism. SpecificationBOOST_CHECKPOINT( message )This tool is used to mark a test flow with a check points. The checkpoint can help to locate a source of a runtime exception. Example: test.cppint test_main( int, char* [] ) { BOOST_CHECKPOINT( "Going to throw an exception" ); throw "some error"; return 0; } Output: Exception in test_main : C string:some_error ![]() BOOST_WARN( predicate )This tool is used to perform a weak validation of the predicate. If predicate is true, the tool produces a conformation message in other case it produces a warning message in a form "warning in ...: condition <predicate> is not satisfied" Example: test.cppint test_main( int, char* [] ) { BOOST_WARN( sizeof(int) == sizeof(short) ); return 0; } Output:test.cpp(2) : warning in test_main: condition sizeof(int)
== sizeof(short) is not satisfied BOOST_CHECK( predicate )This tool is used to validate the predicate value. If predicate is true, the tool produces a conformation message (note here and further: to manage what massages appear in the test output stream set the proper log level) in other case it produces an error message in a form "error in ...: test <predicate> fail" Example: test.cppint test_main( int, char* [] ) { int i=2; BOOST_CHECK( i == 1 ); return 0; } Output:test.cpp(3) : error in test_main: test i==1 failed BOOST_CHECK_EQUAL( left, right )The same as BOOST_CHECK( left == right ). The tools allows to see mismatched values. Example: test.cppint test_main( int, char* [] ) { int i = 2; int j = 1; BOOST_CHECK_EQUAL( i, j ); return 0; } Output: test.cpp(4) : error in test_main: test i == j failed [2 !=
1] BOOST_CHECK_CLOSE( left, right, tolerance_src )This tool is used to check for the strong relationship defined by the predicate close_at_tolerance ( tolerance_src ) between left and right. To check for the weak relationship use BOOST_CHECK_PREDICATE. Note that you need to include floating_point_comparison.hpp yourself to use this tool since it depend on this file that does not get included automatically to minimize code dependency. Example: test.cppint test_main( int, char* [] ) { double v1 = 1.23456e-10; double v2 = 1.23457e-10; BOOST_CHECK_CLOSE( v1, v2, 1e-6 ); // should fail at tolerance supplied return 0; } Output:test.cpp(4) : error in test_main: test v1 (==) v2 failed [1.23456e-10 != 1.23457e-10 (1e-06)] Example: test.cppint test_main( int, char* [] ) { double v1 = 4.1; v1 = v1 * v1; BOOST_CHECK_CLOSE( v1, 16.81, 1+2 ); // 1(arithmetic operation) + // 2(decimal to binary conversions) - // number of rounding errors; should pass return 0; } Output:
BOOST_REQUIRE( predicate )This tool is used to validate the predicate value. If predicate is true, the tool produces a conformation message in other case it produces an error message in a form " fatal error in ...: test <predicate> fail" and then abort the current test case processing. Example: test.cppint test_main( int, char* [] ) { int i = 3; BOOST_REQUIRE( i > 5 ); BOOST_CHECK( i == 6 ); // will never reach this check return 0; } Output:test.cpp(3) : fatal error in test_main: test i>5 failed
BOOST_MESSAGE( message )This tool is used to print the message in the test output stream. The message argument can be of any type and can be a result of concatenations using the operator <<. Example: test.cppstruct A { friend std::ostream& operator<<( std::ostream& str, A const& a ) { str << "struct A"; return str; } }; int test_main( int, char* [] ) { BOOST_MESSAGE( "Starting test" ); int i = 2; BOOST_MESSAGE( "i=" << i ); BOOST_MESSAGE( "still testing..." ); struct A a; BOOST_MESSAGE( a << '.' ); return 0; } Output:Starting test ![]() BOOST_WARN_MESSAGE( predicate, message )
|
Old tool | New analog tool |
BOOST_TEST( predicate ) | BOOST_CHECK( predicate ) |
BOOST_CRITICAL_TEST( predicate ) | BOOST_REQUIRE( predicate ) |
BOOST_CRITICAL_ERROR( message ) | BOOST_FAIL( message ) |
The main reasons for making these changes were conciseness and uniformity. Old deprecated names are still accepted but may be excluded in a future releases. Thanks for Ullrich Koethe, who originally proposed new names.
test_exec_example
test_exec_fail2
test_exec_fail3
test_tools_test
test_fp_comparisons
The Boost Test Library Design
document describes the relationship between Boost Test Library components.