Boost Test Library: Test Tools

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

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. To use the Test Tools you need to link with either the Program Execution Monitor or the Unit Test Framework.

Benefits

Using of Test Tools simplify writing of test program and provide a uniform error reporting mechanism.

Specification

BOOST_CHECKPOINT( message ) - to be 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

BOOST_WARN( predicate ) - to be used to perform a weak validation of the 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

BOOST_CHECK( predicate ) - to be 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

BOOST_CHECK_EQUAL( left, right ) - 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]

BOOST_CHECK_CLOSE( left, right, tolerance_src ) - to be 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 detail/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 ); // 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.cpp

int 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 ) - to be 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 ); // will never reach this check

    return 0;
}

Output:

test.cpp(3) : fatal error in test_main: test i>5 failed

BOOST_MESSAGE( message ) - to be 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 ) - to be 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 ) - to be 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;

    // check weak closeness 
    BOOST_CHECK_PREDICATE( close_at_tolerance<double>( epsilon, false ),
                           2, ( fp1, fp2 ) ); // should pass

    return 0;
}

Output:

BOOST_ERROR( message ) - the same as BOOST_CHECK_MESSAGE( false, message ); to be used for an unconditional error message
BOOST_FAIL( message )      - the same as BOOST_REQUIRE_MESSAGE( false, message ); to be used for an unconditional error message 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

BOOST_CHECK_THROW( statement, exception ) - to be 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 ) - to be 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]

BOOST_IS_DEFINED( symbol ) - to be 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

Depricated Boost.Test v1 test tools

Here is the list of depricated test tools used in Boost.Test version 1 and their new analogs:

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.

Examples and Test Programs

test_exec_example.cpp
test_exec_fail2.cpp
test_exec_fail3.cpp
test_tools_test.cpp

Design

The Boost Test Library Design document describes the relationship between Boost Test Library components.

©

Revised 15 Aug 2002