Home > The Unit Test Framework > Testing tools > Reference
PrevNext

The UTF testing tools reference

BOOST_WARN(predicate)
BOOST_CHECK(predicate)
BOOST_REQUIRE(predicate)

These tools are used to validate the predicate value. The only parameter for these tools is a boolean predicate value that gets validated. It could be any expression that could be evaluated and converted to boolean value. The expression gets evaluated only once, so it's safe to pass complex expression for validation.

Example38.BOOST_<level> usage

#define BOOST_TEST_MODULE example
#include <boost/test/included/unit_test.hpp>

//____________________________________________________________________________//

BOOST_AUTO_TEST_CASE( test )
{
    int i=2;
    BOOST_WARN( sizeof(int) == sizeof(short) );
    BOOST_CHECK( i == 1 );
    BOOST_REQUIRE( i > 5 );
    BOOST_CHECK( i == 6 ); // will never reach this check
}

//____________________________________________________________________________//
Source code | Show output
> example --log_level=warning
Running 1 test case...
test.cpp(9): warning in "test": condition sizeof(int) == sizeof(short) is not satisfied
test.cpp(10): error in "test": check i == 1 failed
test.cpp(11): fatal error in "test": critical check i > 5 failed

*** 2 failures detected in test suite "example"

See also: BOOST_<level>_MESSAGE
BOOST_WARN_BITWISE_EQUAL(left, right)
BOOST_CHECK_BITWISE_EQUAL(left, right)
BOOST_REQUIRE_BITWISE_EQUAL(left, right)

These tools are used to perform bitwise comparison of two values. The check shows all positions where left and right value's bits mismatch.

The first parameter is the left compared value. The second parameter is the right compared value. Parameters are not required to be of the same type, but warning is issued if their type's size does not coincide.

Example39.BOOST_<level>_BITWISE_EQUAL usage

#define BOOST_TEST_MODULE example
#include <boost/test/included/unit_test.hpp>

//____________________________________________________________________________//

BOOST_AUTO_TEST_CASE( test )
{
    BOOST_CHECK_BITWISE_EQUAL( (char)0x26, 0x04 );
}

//____________________________________________________________________________//
Source code | Show output
> example
Running 1 test case...                                                          
test.cpp(8): error in "test": check (char)0x26 =.= 0x04 failed.                 
Mismatch in a position 1                                                        
Mismatch in a position 5                                                        
Operands bit sizes mismatch: 8 != 32                                            
                                                                                
*** 1 failure detected in test suite "example" 

See also: BOOST_<level>_EQUAL
BOOST_WARN_CLOSE(left, right, tolerance)
BOOST_CHECK_CLOSE(left, right, tolerance)
BOOST_REQUIRE_CLOSE(left, right, tolerance)

These tools are used to check on closeness using strong relationship defined by the predicate check_is_close( left, right, tolerance ). To check for the weak relationship use BOOST_<level>_PREDICATE family of tools with explicit check_is_close invocation.

The first parameter is the left compared value. The second parameter is the right compared value. Last third parameter defines the tolerance for the comparison in percentage units.

[Note] Note

It is required for left and right parameters to be of the same floating point type. You will need to explicitly resolve any type mismatch to select which type to use for comparison.

[Note] Note

Note that to use these tools you need to include additional header floating_point_comparison.hpp.

Example40.BOOST_<level>_CLOSE usage with very small values

#define BOOST_TEST_MODULE example
#include <boost/test/included/unit_test.hpp>
#include <boost/test/floating_point_comparison.hpp>

//____________________________________________________________________________//

BOOST_AUTO_TEST_CASE( test )
{
    double v1 = 1.23456e-10;
    double v2 = 1.23457e-10;

    BOOST_CHECK_CLOSE( v1, v2, 0.0001 );
    // Absolute value of difference between these two values is 1e-15. They seems 
    // to be very close. But we want to checks that these values differ no more then 0.0001%
    // of their value. And this test will fail at tolerance supplied.
}

//____________________________________________________________________________//
Source code | Show output
> example
Running 1 test case...
test.cpp(12): error in "test": difference between v1{1.23456e-010} and v2{1.23457e-010} exceeds 0.0001%

*** 1 failure detected in test suite "example"

Example41.BOOST_<level>_CLOSE usage with very big values

#define BOOST_TEST_MODULE example
#include <boost/test/included/unit_test.hpp>
#include <boost/test/floating_point_comparison.hpp>

//____________________________________________________________________________//

BOOST_AUTO_TEST_CASE( test )
{
    double v1 = 1.23456e28;
    double v2 = 1.23457e28;

    BOOST_REQUIRE_CLOSE( v1, v2, 0.001 );
    // Absolute value of difference between these two values is 1e+23.
    // But we are interested only that it does not exeed 0.001% of a values compared
    // And this test will pass.
}

//____________________________________________________________________________//
Source code | Show output
> example
Running 1 test case...

*** No errors detected

See also: BOOST_<level>_CLOSE_FRACTION, BOOST_<level>_SMALL, BOOST_<level>_EQUAL, Floating point comparison algorithms
BOOST_WARN_CLOSE_FRACTION(left, right, tolerance)
BOOST_CHECK_CLOSE_FRACTION(left, right, tolerance)
BOOST_REQUIRE_CLOSE_FRACTION(left, right, tolerance)

These tools are used to check on closeness using strong relationship defined by the predicate check_is_close( left, right, tolerance ). To check for the weak relationship use BOOST_<level>_PREDICATE family of tools with explicit check_is_close invocation.

The first parameter is the left compared value. The second parameter is the right compared value. Last third parameter defines the tolerance for the comparison in percentage units.

[Note] Note

It is required for left and right parameters to be of the same floating point type. You will need to explicitly resolve any type mismatch to select which type to use for comparison.

[Note] Note

Note that to use these tools you need to include additional header floating_point_comparison.hpp.

Example42.BOOST_<level>_CLOSE_FRACTION usage

#define BOOST_TEST_MODULE example
#include <boost/test/included/unit_test.hpp>
#include <boost/test/floating_point_comparison.hpp>

//____________________________________________________________________________//

BOOST_AUTO_TEST_CASE( test )
{
    double v1 = 1.111e-10;
    double v2 = 1.112e-10;

    BOOST_CHECK_CLOSE_FRACTION( v1, v2, 0.0008999 );
}

//____________________________________________________________________________//
Source code | Show output
> example
Running 1 test case...
test.cpp(12): error in "test": difference between v1{1.111e-010} and v2{1.112e-010} exceeds 0.0008999

*** 1 failure detected in test suite "example"

See also: BOOST_<level>_CLOSE, BOOST_<level>_SMALL, BOOST_<level>_EQUAL, Floating point comparison algorithms
BOOST_WARN_EQUAL(left, right)
BOOST_CHECK_EQUAL(left, right)
BOOST_REQUIRE_EQUAL(left, right)

Check performed by these tools is the same as the one performed by BOOST_<level>( left == right ). The difference is that the mismatched values are reported as well.

[Note] Note

It is bad idea to use these tools to compare floating point values. Use BOOST_<level>_CLOSE or BOOST_<level>_CLOSE_FRACTION tools instead.

Example43.BOOST_<level>_EQUAL usage

#define BOOST_TEST_MODULE example
#include <boost/test/included/unit_test.hpp>

//____________________________________________________________________________//

BOOST_AUTO_TEST_CASE( test )
{
    int i = 2;
    int j = 1;
    BOOST_REQUIRE_EQUAL( i, j );
}

//____________________________________________________________________________//
Source code | Show output
> example
Running 1 test case...
test.cpp(10): fatal error in "test": critical check i == j failed [2 != 1]

*** 1 failure detected in test suite "example"

See also: BOOST_<level>, BOOST_<level>_CLOSE, BOOST_<level>_NE
BOOST_WARN_EQUAL_COLLECTION(left_begin, left_end, right_begin, right_end)
BOOST_CHECK_EQUAL_COLLECTION(left_begin, left_end, right_begin, right_end)
BOOST_REQUIRE_EQUAL_COLLECTION(left_begin, left_end, right_begin, right_end)

These tools are used to perform an element by element comparison of two collections. They print all mismatched positions, collection elements at these positions and check that the collections have the same size. The first two parameters designate begin and end of the first collection. The two parameters designate begin and end of the second collection.

Example44.BOOST_<level>_EQUAL_COLLECTION usage

#define BOOST_TEST_MODULE example
#include <boost/test/included/unit_test.hpp>

//____________________________________________________________________________//

BOOST_AUTO_TEST_CASE( test )
{
    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, col2+7 );
}

//____________________________________________________________________________//
Source code | Show output
> example
Running 1 test case...
test.cpp(11): error in "test": check { col1, col1+7 } == { col2, col2+7 } failed. 
Mismatch in a position 2: 3 != 4
Mismatch in a position 5: 6 != 7

*** 1 failure detected in test suite "example"

See also: BOOST_<level>_EQUAL
BOOST_WARN_EXCEPTION(expression, exception, predicate)
BOOST_CHECK_EXCEPTION(expression, exception, predicate)
BOOST_REQUIRE_EXCEPTION(expression, exception, predicate)

These tools are used to perform an exception detection and validation check. Tools execute the supplied expression and validate that it throws an exception of supplied class (or the one derived from it) that complies with the supplied predicate. If the expression throws any other unrelated exception, doesn't throw at all or predicate evaluates to false, check fails. In comparison with BOOST_<level>_THROW tools these allow performing more fine-grained checks. For example: make sure that an expected exception has specific error message.

Example45.BOOST_<level>_EXCEPTION usage

#define BOOST_TEST_MODULE example
#include <boost/test/included/unit_test.hpp>

//____________________________________________________________________________//

struct my_exception {
    explicit my_exception( int ec = 0 ) : m_error_code( ec ) {}

    int m_error_code;
};

bool is_critical( my_exception const& ex ) { return ex.m_error_code < 0; }

BOOST_AUTO_TEST_CASE( test )
{
    BOOST_CHECK_EXCEPTION( throw my_exception( 1 ), my_exception, is_critical );
}

//____________________________________________________________________________//
Source code | Show output
> example
Running 1 test case...
test.cpp(16): error in "test": incorrect exception my_exception is caught

*** 1 failure detected in test suite "example"

See also: BOOST_<level>_THROW
BOOST_WARN_GE(left, right)
BOOST_CHECK_GE(left, right)
BOOST_REQUIRE_GE(left, right)

Check performed by these tools is the same as the one performed by BOOST_<level>( left >= right ). The difference is that the argument values are reported as well.

Example46.BOOST_<level>_GE usage

#define BOOST_TEST_MODULE example
#include <boost/test/included/unit_test.hpp>

//____________________________________________________________________________//

BOOST_AUTO_TEST_CASE( test )
{
    int i = 1;
    int j = 4;
    BOOST_CHECK_GE( i, j );
}

//____________________________________________________________________________//
Source code | Show output
>example
Running 1 test case...
test.cpp(10): error in "test": check i >= j failed [1 < 4]

*** 1 failure detected in test suite "example"

See also: BOOST_<level>_LE, BOOST_<level>_LT, BOOST_<level>_GT
BOOST_WARN_GT(left, right)
BOOST_CHECK_GT(left, right)
BOOST_REQUIRE_GT(left, right)

Check performed by these tools is the same as the one performed by BOOST_<level>( left >= right ). The difference is that the argument values are reported as well.

Example47.BOOST_<level>_GT usage

#define BOOST_TEST_MODULE example
#include <boost/test/included/unit_test.hpp>

//____________________________________________________________________________//

BOOST_AUTO_TEST_CASE( test )
{
    int i = 2;
    int j = 14;
    BOOST_CHECK_GT( i, j );
}

//____________________________________________________________________________//
Source code | Show output
>example
Running 1 test case...
test.cpp(10): error in "test": check i > j failed [2 < 14]

*** 1 failure detected in test suite "example"

See also: BOOST_<level>_LE, BOOST_<level>_LT, BOOST_<level>_GE
BOOST_WARN_LE(left, right)
BOOST_CHECK_LE(left, right)
BOOST_REQUIRE_LE(left, right)

Check performed by these tools is the same as the one performed by BOOST_<level>( left <= right ). The difference is that the argument values are reported as well.

Example48.BOOST_<level>_LE usage

#define BOOST_TEST_MODULE example
#include <boost/test/included/unit_test.hpp>

//____________________________________________________________________________//

BOOST_AUTO_TEST_CASE( test )
{
    int i = 9;
    int j = 6;
    BOOST_CHECK_LE( i, j );
}

//____________________________________________________________________________//
Source code | Show output
>example
Running 1 test case...
test.cpp(10): error in "test": check i <= j failed [9 > 6]

*** 1 failure detected in test suite "example"

See also: BOOST_<level>_LT, BOOST_<level>_GE, BOOST_<level>_GT
BOOST_WARN_LT(left, right)
BOOST_CHECK_LT(left, right)
BOOST_REQUIRE_LT(left, right)

Check performed by these tools is the same as the one performed by BOOST_<level>( left < right ). The difference is that the argument values are reported as well.

Example49.BOOST_<level>_LT usage

#define BOOST_TEST_MODULE example
#include <boost/test/included/unit_test.hpp>

//____________________________________________________________________________//

BOOST_AUTO_TEST_CASE( test )
{
    int i = 7;
    int j = 7;
    BOOST_CHECK_LT( i, j );
}

//____________________________________________________________________________//
Source code | Show output
>example
Running 1 test case...
test.cpp(10): error in "test": check i < j failed [7 >= 7]

*** 1 failure detected in test suite "example"

See also: BOOST_<level>_LE, BOOST_<level>_GE, BOOST_<level>_GT
BOOST_WARN_MESSAGE(predicate, message)
BOOST_CHECK_MESSAGE(predicate, message)
BOOST_REQUIRE_MESSAGE(predicate, message)

These tools perform exactly the same check as BOOST_<level> tools. The only difference is that instead of generating an error/confirm message these use the supplied one.

The first parameter is the boolean expression. The second parameter is the message reported in case of check failure. The message argument can be constructed of components of any type supporting the std::ostream& operator<<(std::ostream&).

Example50.BOOST_<level>_MESSAGE usage

#define BOOST_TEST_MODULE example
#include <boost/test/included/unit_test.hpp>

//____________________________________________________________________________//

#include <cmath>

BOOST_AUTO_TEST_CASE( test )
{
    double res = std::sin( 45. );

    BOOST_WARN_MESSAGE( res > 1, "sin(45){" << res << "} is <= 1. Hmm.. Strange. " );
}

//____________________________________________________________________________//
Source code | Show output
> example --log_level=warning
Running 1 test case...
test.cpp(12): warning in "test": sin(45){0.850904} is <= 1. Hmm.. Strange. 

*** No errors detected

See also: BOOST_<level>
BOOST_WARN_NE(left, right)
BOOST_CHECK_NE(left, right)
BOOST_REQUIRE_NE(left, right)

Check performed by these tools is the same as the one performed by BOOST_<level>( left != right ). The difference is that the matched values are reported as well.

Example51.BOOST_<level>_NE usage

#define BOOST_TEST_MODULE example
#include <boost/test/included/unit_test.hpp>

//____________________________________________________________________________//

BOOST_AUTO_TEST_CASE( test )
{
    int i = 3;
    int j = 3;
    BOOST_CHECK_NE( i, j );
}

//____________________________________________________________________________//
Source code | Show output
>example
Running 1 test case...
test.cpp(10): error in "test": check i != j failed [3 == 3]

*** 1 failure detected in test suite "example"

See also: BOOST_<level>_EQUAL
BOOST_WARN_NO_THROW(expression)
BOOST_CHECK_NO_THROW(expression)
BOOST_REQUIRE_NO_THROW(expression)

These tools are used to perform a "no throw" check. Tools execute the supplied expression and validate that it does not throw any exceptions. Error would be reported by the framework even if the statement appear directly in test case body and throw any exception. But these tools allow proceeding further with test case in case of failure.

If check is successful, tools may produce a confirmation message, in other case they produce an error message in a form "error in <test case name>exception was thrown by <expression>.

The only parameter is an expression to execute. You can use do-while(0) block if you want to execute more than one statement.

Example52.BOOST_<level>_NO_THROW usage

#define BOOST_TEST_MODULE example
#include <boost/test/included/unit_test.hpp>

//____________________________________________________________________________//

class my_exception{};

BOOST_AUTO_TEST_CASE( test )
{
    BOOST_CHECK_NO_THROW( throw my_exception() );
}

//____________________________________________________________________________//
Source code | Show output
> example
Running 1 test case...
test.cpp(10): error in "test": exception thrown by throw my_exception()

*** 1 failure detected in test suite "example"

See also: BOOST_<level>_THROW
BOOST_WARN_PREDICATE(predicate, arguments_list)
BOOST_CHECK_PREDICATE(predicate, arguments_list)
BOOST_REQUIRE_PREDICATE(predicate, arguments_list)

These are generic tools used to validate an arbitrary supplied predicate functor (there is a compile time limit on predicate arity defined by the configurable macro BOOST_TEST_MAX_PREDICATE_ARITY). To validate zero arity predicate use BOOST_<level> tools. In other cases prefer theses tools. The advantage of these tools is that they show arguments values in case of predicate failure.

The first parameter is the predicate itself. The second parameter is the list of predicate arguments each wrapped in round brackets (BOOST_PP sequence format).

Example53.BOOST_<level>_PREDICATE usage

Note difference in error log from

#define BOOST_TEST_MODULE example
#include <boost/test/included/unit_test.hpp>
using namespace boost::unit_test;

//____________________________________________________________________________//

bool moo( int arg1, int arg2, int mod ) { return ((arg1+arg2) % mod) == 0; }

BOOST_AUTO_TEST_CASE( test )
{
    int i = 17;
    int j = 15;
    unit_test_log.set_threshold_level( log_warnings );
    BOOST_WARN( moo( 12,i,j ) );
    BOOST_WARN_PREDICATE( moo, (12)(i)(j) );
}

//____________________________________________________________________________//
Source code | Show output
> example
Running 1 test case...
test.cpp(14): warning in "test": condition moo( 12,i,j ) is not satisfied
test.cpp(15): warning in "test": condition moo( 12, i, j ) is not satisfied for ( 12, 17, 15 )

*** No errors detected

See also: BOOST_<level>
BOOST_WARN_SMALL(value, tolerance)
BOOST_CHECK_SMALL(value, tolerance)
BOOST_REQUIRE_SMALL(value, tolerance)

These tools are used to check that supplied value is small enough. The "smallness" is defined by absolute value of the tolerance supplied as a second argument. Use these tools with caution. To compare to values on closeness it's preferable to use BOOST_<level>_CLOSE tools instead.

The first parameter is the value to check. The second parameter is the tolerance.

[Note] Note

Note that to use these tools you need to include additional header floating_point_comparison.hpp.

Example54.BOOST_<level>_SMALL usage

#define BOOST_TEST_MODULE example
#include <boost/test/included/unit_test.hpp>
#include <boost/test/floating_point_comparison.hpp>

//____________________________________________________________________________//

BOOST_AUTO_TEST_CASE( test )
{
    double v = -1.23456e-3;

    BOOST_CHECK_SMALL( v, 0.000001 );
}

//____________________________________________________________________________//
Source code | Show output
> example
Running 1 test case...
test.cpp(11): error in "test": absolute value of v{-0.00123456} exceeds 1e-006

*** 1 failure detected in test suite "example"

See also: BOOST_<level>_CLOSE, BOOST_<level>_CLOSE_FRACTION, Floating point comparison algorithms
BOOST_WARN_THROW(expression, exception)
BOOST_CHECK_THROW(expression, exception)
BOOST_REQUIRE_THROW(expression, exception)

These tools are used to perform an exception detection check. Tools execute the supplied expression and validate that it throws an exception of supplied class (or the one derived from it) or it's child. If the statement throws any other unrelated exception or doesn't throw at all, check fails.

If check is successful, the tool produces a confirmation message, in other case it produces an error message in a form "error in test case name: exception exception expected.

The first parameter is the expression to execute. Use do-while(0) block if you want to execute more than one statement. The second parameter is an expected exception.

Example55.BOOST_<level>_THROW usage

#define BOOST_TEST_MODULE example
#include <boost/test/included/unit_test.hpp>

//____________________________________________________________________________//

class my_exception{};

BOOST_AUTO_TEST_CASE( test )
{
    int i =  0;
    BOOST_CHECK_THROW( i++, my_exception );
}

//____________________________________________________________________________//
Source code | Show output
> example
Running 1 test case...
test.cpp(11): error in "test": exception my_exception is expected

*** 1 failure detected in test suite "example"

See also: BOOST_<level>NO_THROW
BOOST_ERROR(message)

BOOST_ERROR tool behave the same way as BOOST_CHECK_MESSAGE( false, message ). This tool is used for an unconditional error counter increasing and message logging.

The only tool's parameter is an error message to log.

Example56.BOOST_ERROR usage

#define BOOST_TEST_MODULE example
#include <boost/test/included/unit_test.hpp>

//____________________________________________________________________________//

BOOST_AUTO_TEST_CASE( test )
{
    BOOST_ERROR( "Nothing to test" );
}

//____________________________________________________________________________//
Source code | Show output
> example
Running 1 test case...
test.cpp(8): error in "test": Nothing to test

*** 1 failure detected in test suite "example"

See also: BOOST_<level>
BOOST_FAIL(message)

BOOST_FAIL behave the same way as BOOST_REQUIRE_MESSAGE( false, message ). This tool is used for an unconditional error counter increasing, message logging and the current test case aborting.

The only tool's parameter is an error message to log.

Example57.BOOST_FAIL usage

#define BOOST_TEST_MODULE example
#include <boost/test/included/unit_test.hpp>

//____________________________________________________________________________//

BOOST_AUTO_TEST_CASE( test )
{
    BOOST_FAIL( "Test is not ready yet" );
}

//____________________________________________________________________________//
Source code | Show output
> example
Running 1 test case...
test.cpp(8): fatal error in "test": Test is not ready yet

*** 1 failure detected in test suite "example"

See also: BOOST_<level>
BOOST_IS_DEFINED(symbol)

Unlike the rest of the tools in the toolbox this tool does not perform the logging itself. Its only purpose is to check at runtime whether or not the supplied preprocessor symbol is defined. Use it in combination with BOOST_<level> to perform and log validation. Macros of any arity could be checked. To check the macro definition with non-zero arity specify dummy arguments for it. See below for example.

The only tool's parameter is a preprocessor symbol that gets validated.

Example58.BOOST_IS_DEFINED usage

#define BOOST_TEST_MODULE example
#include <boost/test/included/unit_test.hpp>

//____________________________________________________________________________//

BOOST_AUTO_TEST_CASE( test )
{
    BOOST_CHECK( BOOST_IS_DEFINED(SYMBOL1) );
    BOOST_CHECK( BOOST_IS_DEFINED(SYMBOL2(arg)) );
}

//____________________________________________________________________________//
Source code | Show output
> example
Running 1 test case...
test.cpp(8): error in "test": check ::boost::test_tools::tt_detail::is_defined_impl( "SYMBOL1", "= SYMBOL1" ) failed
test.cpp(9): error in "test": check ::boost::test_tools::tt_detail::is_defined_impl( "SYMBOL2(arg)", "= SYMBOL2(arg)" ) failed

*** 2 failures detected in test suite "example"

See also: BOOST_<level>

PrevUpHomeNext