Boost Test Library: Test Tools
Home
Introduction
Benefits
Specification
BOOST_CHECKPOINT
BOOST_WARN
BOOST_CHECK
BOOST_CHECK_EQUAL
BOOST_CHECK_CLOSE
BOOST_REQUIRE
BOOST_MESSAGE
BOOST_WARN_MESSAGE
BOOST_CHECK_MESSAGE
BOOST_REQUIRE_MESSAGE
BOOST_CHECK_PREDICATE
BOOST_REQUIRE_PREDICATE
BOOST_ERROR
BOOST_FAIL
BOOST_CHECK_THROW
BOOST_CHECK_EQUAL_COLLECTIONS
BOOST_IS_DEFINED
output_test_stream
Depricated Boost Test v1 test tools
Example and Test Programs
Design
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.
To use the Test Tools you need to link with either the Program
Execution Monitor or the Unit Test Framework.
Using of Test Tools simplify writing of test program and
provide a uniform error reporting mechanism.
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.cpp
int 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
test.cpp(2) : last checkpoint: Going to throw an exception
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.cpp
int 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
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.cpp
int 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
The same as BOOST_CHECK( left == right ). The tools allows
to see mismatched values.
Example: test.cpp
int 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]
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.cpp
int test_main( int, char* [] ) {
double v1 = 1.23456e-10;
double v2 = 1.23457e-10;
BOOST_CHECK_CLOSE( v1, v2, 1e-6 );
return 0;
}
Output:
test.cpp(4) : error in test_main: test v1 (==) v2 failed [1.23456e-10
!= 1.23457e-10 (1e-06)]
Example: test.cpp
int test_main( int, char* [] ) {
double v1 = 4.1;
v1 = v1 * v1;
BOOST_CHECK_CLOSE( v1, 16.81, 1+2 );
return 0;
}
Output:
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.cpp
int test_main( int, char* [] ) {
int i = 3;
BOOST_REQUIRE( i > 5 );
BOOST_CHECK( i == 6 );
return 0;
}
Output:
test.cpp(3) : fatal error in test_main: test i>5 failed
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.cpp
struct 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
i=2
still testing...
struct A.
BOOST_WARN_MESSAGE( predicate, message )
BOOST_CHECK_MESSAGE( predicate, message )
BOOST_REQUIRE_MESSAGE( predicate, message )
This group of tools works the same way as their non _MESSAGE
form. The only difference is test instead of generating of an error/confirm message
these macros use the supplied one.
Example: test.cpp
int test.cpp( int, char* [] ) {
double res = sin( 45 );
BOOST_CHECK_MESSAGE( res > 3, "Why not?!?!" );
return 0;
}
Output:
test.cpp(3) : error in test_main: Why not?!?!
BOOST_CHECK_PREDICATE( prediate, number_of_arguments,
arguments_list )
This tool is used to validate the supplied predicate.
If predicate produces true value, the tool produces a conformation message
in other case it produces an error message in a form "error in ...: test <predicate>(
arguments_list ) fail for (arguments values)". Right now only unary and binary
predicates are supported.
Example: test.cpp
bool is_even( int i ) {
return i%2 == 0;
}
int test.cpp( int, char* [] ) {
int i = 17;
BOOST_CHECK_PREDICATE( &is_even, 1, (i) );
return 0;
}
Output:
test.cpp(3) : error in test_main: test &is_even(i) failed
for 17
Example: test.cpp
int test.cpp( int, char* [] ) {
int i = 17;
BOOST_CHECK_PREDICATE( std::not_equal_to<int>(), 2, (i,17) );
return 0;
}
Output:
test.cpp(3) : error in test_main: test std::not_equal_to<int>()(i,
17) failed for (17, 17)
BOOST_REQUIRE_PREDICATE( prediate, number_of_arguments,
arguments_list )
This tool is used to validate the supplied predicate.
If predicate produces true value, the tool produces a conformation message
in other case it produces an error message in a form "error in ...: test <predicate>(
arguments_list ) fail for (arguments values)" and abort current test case
processing. Right now only unary and binary predicates are supported.
Example: test.cpp
int test.cpp( int, char* [] ) {
double fp1 = 1.23456e-10;
double fp2 = 1.23457e-10;
double epsilon = 8.1e-6;
BOOST_CHECK_PREDICATE( close_at_tolerance<double>( epsilon, false ),
2, ( fp1, fp2 ) );
return 0;
}
Output:
BOOST_ERROR is the same as BOOST_CHECK_MESSAGE( false,
message ). This tool is used for an unconditional error message logging. BOOST_FAIL
is the same as BOOST_REQUIRE_MESSAGE( false, message ). This tool is used for an
unconditional error message logging and the current test case aborting.
Example: test.cpp
int test_main( int, char* [] ) {
BOOST_ERROR( "Nothing to test" );
BOOST_FAIL( "Test is not ready yet" );
return 0;
}
Output:
test.cpp(3) : error in test_main: Nothing to test
test.cpp(4) : fatal error in test_main: Test is not ready yet
This tool is used to perform an error detection check.
The tool executes the supplied statement and check that it throw the supplied exception.
Example: test.cpp
class my_exception{};
int test_main( int, char* [] ) {
int i = 0;
BOOST_CHECK_THROW( i++, my_exception );
return 0;
}
Output:
test.cpp(4) : error in test_main: exception my_exception expected
BOOST_CHECK_EQUAL_COLLECTIONS( left_begin,
left_end, right_begin )
This tool is used to perform an element comparison of
two collections
Example: test.cpp
int test_main( int, char* [] ) {
int col1 [] = { 1, 2, 3, 4, 5, 6, 7 };
int col2 [] = { 1, 2, 4, 4, 5, 7, 7 };
BOOST_CHECK_EQUAL_COLLECTIONS( col1, col1+7, col2);
return 0;
}
Output:
test.cpp(4) : error in test_main: test {col1, col1+7} == {col2,...}
failed [3 != 4]
test.cpp(4) : error in test_main: test {col1, col1+7} == {col2,...} failed [6 !=
7]
This tool is used to check whether or not the supplied
symbol is defined.
Example: test.cpp
int test_main( int, char* [] ) {
BOOST_CHECK( BOOST_IS_DEFINED(SYMBOL1) );
BOOST_CHECK( BOOST_IS_DEFINED(SYMBOL2(arg)) );
return 0;
}
Output:
test.cpp(2) : error in test_main: test BOOST_IS_DEFINED(SYMBOL1)
failed
test.cpp(3) : error in test_main: test BOOST_IS_DEFINED(SYMBOL2(arg)) failed
Here is the list of depricated test tools used in Boost Test
version 1 and their new analogs:
| 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.
|