White paper for unit testing using boost

Purpose
Purpose of this document to describe how to do the unit testing using boost library. This library is
open source and is available for cross platform operating systems like Windows, UNIX etc. Primarily
this framework is used to do the regression testing for applications written in C++ language. Boost
has set of tools which are majorly macros and expressions. These tools are
BOOST_WARN, BOOST_CHECK, and BOOST_REQUIRE.
Inside the boost code there is a directory called test where all the test related files are there say
unit_test.hpp. Below is the screenshot to configure the boost library in Visual Studio.
Simple test for a function of the class

Let say I have to test my custom string class TestString. Below is the code for that class and save the
filename as str.h.
#ifndef _TESTSTRING
#define _TESTSTRING
class TestString {
char* buffer;
int length;
public:
void setbuffer(char* s) { buffer = s; length = strlen(s); }
char& operator[ ] (const int index) { return buffer[index]; }
int size( ) { return length; }
};
#endif
In order to test the above methods using boost library following will be used (test.cpp).
#define BOOST_TEST_MODULE StringTest
#include <boost/test/included/unit_test.hpp>
#include "./str.h"
BOOST_AUTO_TEST_SUITE (StringTest) // name of the test suite is StringTest
BOOST_AUTO_TEST_CASE (test1)
{
TestString s;
BOOST_CHECK(s.size() == 0);
}
{
Teststring s;
s.setbuffer("hello world");
BOOST_REQUIRE_EQUAL ('h', s[0]); // basic test
}
BOOST_AUTO_TEST_SUITE_END( )
This is basic test suit to test the string class, BOOST_REQUIRE_EQUAL is the macro used to check the
elements at 0 index. Compile above code either g++ compiler or using visual studio you will get the
following result.
Running 2 test cases...
test.cpp(10): error in "test1": check s.size() == 0 failed
*** 1 failure detected in test suite "StringTest"
Let see one more scenario using boost tool like BOOST_CHECK and BOOST_REQUIRE. The main
difference is that first one continues to execution even if the assertion has failed, while in the
latter case, it is deemed a critical error and testing stops.
#define BOOST_TEST_MODULE enumtest
BOOST_AUTO_TEST_SUITE (enum-test)
{
typedef enum {red = 8, blue, green = 1, yellow, black } color;
color c = green;
BOOST_WARN(sizeof(green) > sizeof(char));
BOOST_CHECK(c == 2);
BOOST_REQUIRE(yellow > red);
BOOST_CHECK(black != 4);
}

This is the simple test for boost tool using the enum datatype rather than the class. Following is the
test result for the above code.
Running 1 test case...
e2.cpp(11): error in "test1": check c == 2 failed
e2.cpp(12): fatal error in "test1": critical check yellow > red failed
*** 2 failures detected in test suite "enumtest"
Lets I am going to cover the pattern matching. Whats the code is doing is that it creates the run.log
file and then write the return value of the function and called the match_pattern for the same
object.
#define BOOST_TEST_MODULE example
#include <boost/test/output_test_stream.hpp>
using boost::test_tools::output_test_stream;
BOOST_AUTO_TEST_SUITE ( test )
BOOST_AUTO_TEST_CASE( test )
{
output_test_stream output( "run.log", true );
output << predefined_user_func( );
BOOST_CHECK( output.match_pattern() );
}
BOOST_CHECK_CLOSE_FRACTION macro
This section is going to describe the functionality of the BOOST_CHECK_CLOSE_FRACTION in
the code.
The syntax for this method is as follows:
BOOST_CHECK_CLOSE_FRACTION (left-value, right-value, tolerance-limit);
#define BOOST_TEST_MODULE floatingTest
#include <boost/test/floating_point_comparison.hpp>
#include <cmath>
{
float f1 = 567.01012;
float result = sqrt(f1); // this could be my_sqrt; faster implementation
// for some specific DSP like hardware
BOOST_CHECK_CLOSE_FRACTION (f1, result * result, 0.0001);
}
Following is the result it will display.
sq.cpp(18): error in "test": difference between f1{567.010132} and
result * result{567.010193} exceeds 1e-07

*** 1 failure detected in test suite "floatingTest"
Common (and vicious) problem that keeps repeating itself in production software is the
comparison of variables of type double and float. A nice feature
of BOOST_CHECK_CLOSE_FRACTION is that it does not let you make such comparisons.
Custom predicate support as in C++ template
Boost test tools validate Boolean conditions. User can augment the test tools to support
more complicated checks—say, to determine whether the contents of two lists are the same
or whether a certain condition is valid on all elements of a vector. You can also extend
the BOOST_CHECK macro to perform custom predicate support. Custom check function needs
to return the typeboost::test_tools::predicate_result
std::list<int>
user_defined_func( )
{
std::list<int> lst;
lst.push_pack(1);
lst.push_pack(2);
lst.push_pack(3);
lst.push_pack(4);
return lst;
}
boost::test_tools::predicate_result validate_list(std::list<int>& L1)
{
std::list<int>::iterator it1 = L1.begin( );
for (; it1 != L1.end( ); ++it1)
{
if (*it1 <= 1) return false;
}
return true;
}
{
std::list<int>& list1 = user_defined_func( );
BOOST_CHECK( validate_list(list1) );
}
The predicate_result object has an implicit constructor that accepts a Boolean value.
Another way by which developer could test complex predicates with Boost:
the BOOST_CHECK_PREDICATE macro. The good part about using this macro is that it
does not use the predicate_result. The user needs to pass the function name and the
argument(s) to the BOOST_CHECK_PREDICATE macro.
bool validate_list(std::list<int>& L1)
{
std::list<int>::iterator it1 = L1.begin( );
for (; it1 != L1.end( ); ++it1)

{
if (*it1 <= 1) return false;
}
return true;
}
{
std::list<int>& list1 = user_defined_func( );
BOOST_CHECK_PREDICATE( validate_list, list1 );
}
Include multiple test suites in a file
It is possible to include multiple test suites into a single file. Each test suite must have a pair
of BOOST_AUTO_TEST_SUITE... BOOST_AUTO_TEST_SUITE_END macros defined
inside the file. Below shows two different test suites defined inside the same file. When
running the regressions, run the executable with the predefined –log_level=test_suite option.
#define BOOST_TEST_MODULE Regression
typedef struct {
int c;
char d;
double e;
bool f;
} Node;
typedef union {
int c;
char d;
double e;
bool f;
} Node2;
BOOST_AUTO_TEST_SUITE(Structure)
BOOST_AUTO_TEST_CASE(Test1)
{
Node n;
BOOST_CHECK(sizeof(n) < 12);
}
BOOST_AUTO_TEST_SUITE_END()
BOOST_AUTO_TEST_SUITE(Union)
BOOST_AUTO_TEST_CASE(Test1)
{
Node2 n;
BOOST_CHECK(sizeof(n) == sizeof(double));
}
Following is the output for above program.
Running 2 test cases...
Entering test suite "Regression"
Entering test suite "Structure"
Entering test case "Test1"
m2.cpp(23): error in "Test1": check sizeof(n) < 12 failed
Leaving test case "Test1"
Leaving test suite "Structure"

Entering test suite "Union"
Entering test case "Test1"
Leaving test case "Test1"
Leaving test suite "Union"
Leaving test suite "Regression"
*** 1 failure detected in test suite "Regression"
Organization of the test suit
Within the test framework itself, there typically will be multiple suites, each checking certain
product features. For example, regression framework of a word processor should have
suites that check for font support, different file formats, and so on. Each individual test suite
will have multiple unit tests.
#define BOOST_TEST_MODULE MasterTestSuite
using boost::unit_test;
test_suite*
init_unit_test_suite( int argc, char* argv[] )
{
test_suite* ts1 = BOOST_TEST_SUITE( "test_suite1" );
ts1->add( BOOST_TEST_CASE( &test_case1 ) );
test_suite* ts2 = BOOST_TEST_SUITE( "test_suite2" );
framework::master_test_suite().add( ts1 );
framework::master_test_suite().add( ts2 );
return 0;
}
Each test suite (in above) is created by using the macro BOOST_TEST_SUITE. The macro
expects a string that is the name of the test suite. All the test suites are eventually added to
the master test suite using the add method. Likewise, user create each test using the
macro BOOST_TEST_CASE and add each test to the test suite, again using the add method.
You can also add unit tests to the master test suite, although it is not a recommended
practice. The master_test_suite method is defined as part of
the boost::unit_test::framework namespace.
master_test_suite_t&
master_test_suite()
{
if( !s_frk_impl().m_master_test_suite )
s_frk_impl().m_master_test_suite = new master_test_suite_t;
return *s_frk_impl().m_master_test_suite;
}
boost Fixtures
A test fixture is meant to set up an environment before a test is executed and clean up when
the test is complete. This is additional feature in boost which is normally not present in C
based framework like “CMocka”. Below is a simple example.
#include <iostream>

class MyTest {
MyTest () : i( 0 ) { std::cout << "setup" << std::endl; }
~MyTest () { std::cout << "teardown" << std::endl; }
int i;
};
BOOST_AUTO_TEST_SUITE( test )
BOOST_FIXTURE_TEST_CASE( test_case1, MyTest )
{
BOOST_CHECK( i == 1 );
++i;
}
The below is the output of above program.
setup
fix.cpp(16): error in "test_case1": check i == 1 failed
teardown
*** 1 failure detected in test suite "example"
Instead of using the BOOST_AUTO_TEST_CASE macro, this code
uses BOOST_FIXTURE_TEST_CASE, which takes in an additional argument. The
constructor and destructor methods of this object do the necessary setup and cleanup.
This macro is defined in the unit_test_suite.hpp file and it is as follows:
#define BOOST_FIXTURE_TEST_CASE( test_name, MyTest )
struct test_name : public MyTest { void test_method(); };

static void BOOST_AUTO_TC_INVOKER( test_name )()
{

test_name t;

t.test_method();

}

struct BOOST_AUTO_TC_UNIQUE_ID( test_name ) {};

BOOST_AUTO_TU_REGISTRAR( test_name )(
boost::unit_test::make_test_case(
&BOOST_AUTO_TC_INVOKER( test_name ), #test_name ),
boost::unit_test::ut_detail::auto_tc_exp_fail<
BOOST_AUTO_TC_UNIQUE_ID( test_name )>::instance()->value() );

void test_name::test_method()

Internally, Boost is publicly deriving a class from the class MyTest (as above), then creating
an object out of that class. As per the rules of public inheritance in C++, all protected and
public variables of the class are directly accessible in the function that follows. Note that
in above in class MyTest, the variable i being modified is one that belongs to the internal
object t of type class (see above). It is quite okay to have a regression suite in which only
couple of tests need some sort of explicit initialization and therefore use the fixture feature.

#include <iostream>
class MyTest {
MyTest () : i( 0 ) { std::cout << "setup" << std::endl; }
~ MyTest () { std::cout << "teardown" << std::endl; }
int i;
};
BOOST_FIXTURE_TEST_CASE( test_case1, MyTest )
{
BOOST_CHECK( i == 1 );
++i;
}
BOOST_AUTO_TEST_CASE( test_case2 )
{
BOOST_REQUIRE( 2 > 1 );
}
{
int i = 1;
BOOST_CHECK_EQUAL( i, 1 );
++i;
}
Above code has fixtures that are defined and used on an individual test case. Boost also lets
the user define and use global fixtures with the macroBOOST_GLOBAL_FIXTURE (<Fixture
Name>). User can define any number of global fixtures, which allows splitting up of
initialization code.
#include <iostream>
struct MyTest {
MyTest () { std::cout << "setup" << std::endl; }
};
BOOST_GLOBAL_FIXTURE(MyTest );
{
BOOST_CHECK( true );
}
For multiple fixtures, the setup and tear-down occurs in the order you declare them. In below
code the constructor of MyTest is called before MyTest2; likewise for the destructor.
#include <iostream>
class MyTest {
MyTest () { std::cout << "setup" << std::endl; }
};
struct MyTest2 {
MyTest2() { std::cout << "setup 2" << std::endl; }
~ MyTest2() { std::cout << "teardown 2" << std::endl; }
};
BOOST_GLOBAL_FIXTURE(MyTest );
BOOST_GLOBAL_FIXTURE(MyTest2 );

{
BOOST_CHECK( true );
}
User cannot use global fixtures as objects in individual tests. Nor can you directly access
their public/protected non-static methods or variables inside a test.

White paper for unit testing using boost

More Related Content

What's hot

Similar to White paper for unit testing using boost

White paper for unit testing using boost