Sunday, July 18, 2010

Boost Test. Setup and usage

Below is a translation of russian post, published by me early.

Recently in my blog I did a brief overview of the tools unit testing and noted the presence of of short notes for fast start with a library UnitTest++. Today I want to offer the option of such manual to Boost Test, which you will not find in the official documentation for this tool. Description focuses on the use under Windows with Visual Studio 2005/2008.

To work with the examples you need to download from the site www.boost.org boost libraries package (currently version 1.39). Unzip the downloaded archive and we can begin.

Building Boost.Test

You can use Boost.Test as a library and as an includable header file. Next I will describe the use of this library in binary form, statically linked to the test project.

In the root directory of the downloaded Boost distribution find out bootstrap.bat and run it. As a result Boost build utility bjam.exe will be created in the same directory.

Now run from the command line bjam.exe as shown below:
bjam --build-dir=..\boosttest\build_dir toolset=msvc --libdir=..\boosttest\lib --includedir=..\boosttest\include --with-test variant=debug link=static threading=multi runtime-link=shared install

In the same folder where you unzipped Boost archive the folder boosttest will be created with the following subfolders:
  • build_dir, which stores intermediate and result build files of the Boost.Test
  • include, with the headers of all utilities of the Boost library to use in your project
  • lib, which stores libraries to link with
Creating a test project
Next I will describe the creation of a test project with unit tests. Using this description you can use similar tests in your project.

We will add unit tests directly in the main project. You can also place unit tests into separate project, but in this case, you may have trouble with linking. For the variant with a separate project for the tests you need to export the tested functions and classes, and this may complicate the work of a tightly coupled classes, maybe just those who are sorely needed refactoring.

So, let's create an empty project:

New Project > Visual C++ > General > Empty Project

First, write a simple program for multiplying two integers anddisplays their product.
Adding to the project file main.cpp with the following content:
//! main.cpp

#include <iostream>
#include "functions.h"

using namespace std;

void main()
{
cout << "Main Program" << endl;
cout << "5 * 4 = " << multiply(5, 4) << endl;
}
Also add a file with the implementation of the function of multiplication:
//! functions.cpp
#include "functions.h"

int multiply(const int x, const int y)
{
return x * y;
}
And the header file delaring the function of multiplication:
//! functions.h
int multiply(const int x, const int y);

Now add the files with the code test. First, add the file maintest.cpp, which declared constant BOOST_TEST_MAIN to Boost Test automatically generated main function for testing. Here, write the first test, which will always be wrong. I do it just to show how to use the library to test the implementation of which is in multiple files.
//! maintest.cpp

#define BOOST_TEST_MAIN

#include <boost/test/unit_test.hpp>

BOOST_AUTO_TEST_CASE(SimpleTestInMainTestingModule)
{
BOOST_CHECK(1 == 2);
}

Now add another file functionsTest.cpp, which will contain a test for the function of the multiply from functions.cpp:
//! functionsTest.cpp

#include "functions.h"
#include <boost/test/unit_test.hpp>

BOOST_AUTO_TEST_CASE(Multiply)
{
BOOST_CHECK(multiply(4, 5) == 20);
}
Adding a test configuration

Now we need to solve the problem of main functions conflict, which one is described in main.cpp and another one that will be generated by Boost. To do this, add a new configuration of the project for unit tests, where main.cpp module will be excluded from the assembly, and in the Debug and Release-configurations should be excluded from the assembly mainTest.cpp.

To add a new configuration of the project in the Build menu choose Configuration Manager .... In the resulting dialog box, select the Active solution configuration, click New. Enter the name of the new configuration UnitTests and save the changes.

Make the active configuration 'UnitTests'. In the shortcut menu, select 'Properties' of the file main.cpp and on the 'General' tab for the properties 'Excluded from build' set to Yes. Take an active configuration 'Debug' and for both files 'maintest.cpp' and 'functionsTest.cpp' also set the 'Excluded from build' option to 'Yes'. Similarly to Debug, configure the Release configuration.

Now you need to configure a test configuration of the project. Again, make active configuration UnitTests and project properties for this configuration, do the following:
In the project settings C++ > General > Additional Include Directories enter the path to the Boost Test header files

Linker > General > Additional Library Directories enter path to the folder with libboost_unit_test_framework-vc90-mt-gd-1_39.lib

Linker > System > SubSystem choose from the list option Console (/SUBSYSTEM:CONSOLE)

Build Events > Post-Build Event > Command Line
"$(TargetDir)\$(TargetName).exe" --result_code=no --report_level=short

Build Events > Post-Build Event > Description
==== Run unit tests ====

The output can be different. Description of parameters to control output, is shown in official documentation in the section Runtime Parameters Reference.

Build and run the project in Debug or Release configurations. There will be a message:

Main Program
5 * 4 = 20

Then build the project in the configuration UnitTests. In the Output window of Visual Studio IDE in additional to compilation information will be something like this:

==== Run unit tests ====
Running 2 test cases...
./maintest.cpp(13): error in "SimpleTestInMainTestingModule": check 1 == 2 failed
Test suite "Master Test Suite" failed with:
1 assertion out of 2 passed
1 assertion out of 2 failed
1 test case out of 2 passed
1 test case out of 2 failed

If you execute the file SingleProject.exe built in UnitTests configuratin you will see the same output in console window.
If you see this message, it means the project is configured correctly. You can also download all the project sources.

I hope this information wiil be useful. Corrections and additions are welcome!

3 comments:

Brian said...

Great Stuff (found this link via a StackOverflow answer)

- B

Anonymous said...

Great tutorial, thanks! (found on StackOverflow also :D )

Anonymous said...

Very practical and friendly tutorial for first time user. Pleasant to read. Having stuff often omitted by basic documents and other tutorials, which often assuming some basic knowledge already.