Boost logo

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

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. reference to the top 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 )

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

reference to the top

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.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 reference to the top

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.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 reference to the top

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] reference to the top

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.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: reference to the top

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.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 reference to the top

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.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.

reference to the top

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?!?! reference to the top

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) reference to the top

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;

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

    return 0;
}
reference to the top

Output:

BOOST_ERROR( message )
BOOST_FAIL( message )

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

reference to the top

BOOST_CHECK_THROW( statement, exception )

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

reference to the top

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] reference to the top

BOOST_IS_DEFINED( symbol )

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 reference to the top

Depricated Boost Test v1 test tools

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.

Examples and Test Programs

test_exec_example
test_exec_fail2
test_exec_fail3
test_tools_test
test_fp_comparisons

Design

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