CppUnit project page FAQ
Money, a step by step example

of contents

The example explored in this article can be found in examples/Money/.

Setting up your project (VC++)

Compiling and installing CppUnit libaries

In the following document, $CPPUNIT is the directory where you unpacked CppUnit: $CPPUNIT/: include/ lib/ src/ cppunit/

First, you need to compile CppUnit libraries:

Once it is done, you need to tell VC++ where are the includes and libraries to use them in other projects. Open the 'Tools/Options...' dialog, and in the 'Directories' tab, select 'include files' in the combo. Add a new entry that points to $CPPUNIT/include/. Change to 'libraries files' in the combo and add a new entry for $CPPUNIT/lib/. Repeat the process with 'source files' and add $CPPUNIT/src/cppunit/.

Getting started

Creates a new console application ('a simple application' template will do). Let's link CppUnit library to our project. In the project settings:

We're done !

Setting up your project (Unix)

We'll use autoconf and automake to make it simple to create our build environment. Create a directory somewhere to hold the code we're going to build. Create configure.in and Makefile.am in that directory to get started.

configure.in 

dnl Process this file with autoconf to produce a configure script.
AC_INIT(Makefile.am)
AM_INIT_AUTOMAKE(money,0.1)
AM_PATH_CPPUNIT(1.9.6)
AC_PROG_CXX
AC_PROG_CC
AC_PROG_INSTALL
AC_OUTPUT(Makefile)

Makefile.am 

# Rules for the test code (use `make check` to execute)
TESTS = MoneyApp
check_PROGRAMS = $(TESTS)
MoneyApp_SOURCES = Money.h MoneyTest.h MoneyTest.cpp MoneyApp.cpp
MoneyApp_CXXFLAGS = $(CPPUNIT_CFLAGS)
MoneyApp_LDFLAGS = $(CPPUNIT_LIBS) -ldl

Running our tests

We have a main that doesn't do anything. Let's start by adding the mechanics to run our tests (remember, test before you code ;-) ). For this example, we will use a TextTestRunner with the CompilerOutputter for post-build testing:

MoneyApp.cpp

#include "stdafx.h"
#include <cppunit/CompilerOutputter.h>
#include <cppunit/extensions/TestFactoryRegistry.h>
#include <cppunit/ui/text/TestRunner.h>
int main(int argc, char* argv[])
{
// Get the top level suite from the registry
CppUnit::Test *suite = CppUnit::TestFactoryRegistry::getRegistry().makeTest();
// Adds the test to the list of test to run
CppUnit::TextUi::TestRunner runner;
runner.addTest( suite );
// Change the default outputter to a compiler error format outputter
runner.setOutputter( new CppUnit::CompilerOutputter( &runner.result(),
std::cerr ) );
// Run the tests.
bool wasSucessful = runner.run();
// Return error code 1 if the one of test failed.
return wasSucessful ? 0 : 1;
}

VC++: Compile and run (Ctrl+F5).

Unix: First build. Since we don't have all the file yet, let's create them and build our application for the first time: 

touch Money.h MoneyTest.h MoneyTest.cpp
aclocal -I /usr/local/share/aclocal
autoconf
automake -a
touch NEWS README AUTHORS ChangeLog # To make automake happy
./configure
make check

Our application will report that everything is fine and no test were run. So let's add some tests...

Setting up automated post-build testing (VC++)

What does post-build testing means? It means that each time you compile, the test are automatically run when the build finish. This is very useful, if you compile often you can know that you just 'broke' something, or that everything is still working fine.

Let's adds that to our project, In the project settings, in the 'post-build step' tab:

$(TargetPath) expands into the name of your application: Debug\MoneyApp.exe in debug configuration and Release\MoneyApp.exe in release configuration.

What we are doing is say to VC++ to run our application for each build. Notices the last line of main(), it returns a different error code, depending on weither or not a test failed. If the code returned by an application is not 0 in post-build step, it tell VC++ that the build step failed.

Compile. Notice that the application's output is now in the build window. How convenient!

(Unix: tips to integrate make check into various IDE?)

Adding the TestFixture

For this example, we are going to write a simple money class. Money has an amount and a currency. Let's begin by creating a fixture where we can put our tests, and add single test to test Money constructor:

MoneyTest.h:

#ifndef MONEYTEST_H
#define MONEYTEST_H
#include <cppunit/extensions/HelperMacros.h>
class MoneyTest : public CppUnit::TestFixture
{
CPPUNIT_TEST_SUITE( MoneyTest );
CPPUNIT_TEST( testConstructor );
CPPUNIT_TEST_SUITE_END();
public:
void setUp();
void tearDown();
void testConstructor();
};
#endif // MONEYTEST_H

MoneyTest.cpp

#include "stdafx.h"
#include "MoneyTest.h"
// Registers the fixture into the 'registry'
CPPUNIT_TEST_SUITE_REGISTRATION( MoneyTest );
void
MoneyTest::setUp()
{
}
void
MoneyTest::tearDown()
{
}
void
MoneyTest::testConstructor()
{
CPPUNIT_FAIL( "not implemented" );
}

Compile. As expected, it reports that a test failed. Press the F4 key (Go to next Error). VC++ jump right to our failed assertion CPPUNIT_FAIL. We can not ask better in term of integration! 

Compiling...
MoneyTest.cpp
Linking...
Unit testing...
.F
G:\prg\vc\Lib\cppunit\examples\money\MoneyTest.cpp(26):Assertion
Test name: MoneyTest.testConstructor
not implemented
Failures !!!
Run: 1   Failure total: 1   Failures: 1   Errors: 0
Error executing d:\winnt\system32\cmd.exe.

moneyappd.exe - 1 error(s), 0 warning(s)

Well, we have everything set up, let's start doing some real testing.

Our first tests

Let's write our first real test. A test is usually decomposed in three parts:

Well, we finally have a good start of what our Money class will look like. Let's start implementing...

Money.h

#ifndef MONEY_H
#define MONEY_H
#include <string>
class Money
{
public:
Money( double amount, std::string currency )
: m_amount( amount )
, m_currency( currency )
{
}
double getAmount() const
{
return m_amount;
}
std::string getCurrency() const
{
return m_currency;
}
private:
double m_amount;
std::string m_currency;
};
#endif

Include Money.h in MoneyTest.cpp and compile.

Hum, an assertion failed! Press F4, and we jump to the assertion that checks the currency of the constructed money object. The report indicates that string is not equal to expected value. There is only two ways for this to happen: the member was badly initialized or we returned the wrong value. After a quick check, we find out it is the former. Let's fix that:

Money.h

Money( double amount, std::string currency )
: m_amount( amount )
, m_currency( currency )
{
}

Compile. Our test finally pass! Let's add some functionnality to our Money class.

Adding more tests

Testing for equality

We want to check if to Money object are equal. Let's start by adding a new test to the suite, then add our method:

MoneyTest.h

CPPUNIT_TEST_SUITE( MoneyTest );
CPPUNIT_TEST( testConstructor );
CPPUNIT_TEST( testEqual );
CPPUNIT_TEST_SUITE_END();
public:
...
void testEqual();

MoneyTest.cpp

void
MoneyTest::testEqual()
{
// Set up
const Money money123FF( 123, "FF" );
const Money money123USD( 123, "USD" );
const Money money12FF( 12, "FF" );
const Money money12USD( 12, "USD" );
// Process & Check
CPPUNIT_ASSERT( money123FF == money123FF ); // ==
CPPUNIT_ASSERT( money12FF != money123FF ); // != amount
CPPUNIT_ASSERT( money123USD != money123FF ); // != currency
CPPUNIT_ASSERT( money12USD != money123FF ); // != currency and != amount
}

Let's implements operator == and operator != in Money.h:

Money.h

class Money
{
public:
...
bool operator ==( const Money &other ) const
{
return m_amount == other.m_amount &&
m_currency == other.m_currency;
}
bool operator !=( const Money &other ) const
{
return (*this == other);
}
};

Compile, run... Ooops... Press F4, it seems we're having trouble with operator !=. Let's fix that:

bool operator !=( const Money &other ) const
{
return !(*this == other);
}

Compile, run. Finally got it working!

Adding moneys

Let's add our test 'testAdd' to MoneyTest. You know the routine...

MoneyTest.cpp

void
MoneyTest::testAdd()
{
// Set up
const Money money12FF( 12, "FF" );
const Money expectedMoney( 135, "FF" );
// Process
Money money( 123, "FF" );
money += money12FF;
// Check
CPPUNIT_ASSERT( expectedMoney == money ); // add works
CPPUNIT_ASSERT( &money == &(money += money12FF) ); // add returns ref. on 'this'.
}

While writing that test case, you ask yourself, what is the result of adding money of currencies. Obviously this is an error and it should be reported, say let throw an exception, say IncompatibleMoneyError, when the currencies are not equal. We will write another test case for this later. For now let get our testAdd() case working:

Money.h

class Money
{
public:
...
Money &operator +=( const Money &other )
{
m_amount += other.m_amount;
return *this;
}
};

Compile, run. Miracle, everything is fine! Just to be sure the test is indeed working, in the above code, change m_amount += to -=. Build and check that it fails (always be suspicious of test that work the first time: you may have forgotten to add it to the suite for example)! Change the code back so that all the tests are working.

Let's the incompatible money test case before we forget about it... That test case expect an IncompatibleMoneyError exception to be thrown. CppUnit can test that for us, you need to specify that the test case expect an exception when you add it to the suite:

MoneyTest.h

class MoneyTest : public CppUnit::TestFixture
{
CPPUNIT_TEST_SUITE( MoneyTest );
CPPUNIT_TEST( testConstructor );
CPPUNIT_TEST( testEqual );
CPPUNIT_TEST( testAdd );
CPPUNIT_TEST_EXCEPTION( testAddThrow, IncompatibleMoneyError );
CPPUNIT_TEST_SUITE_END();
public:
...
void testAddThrow();
};

By convention, you end the name of such tests with 'Throw', that way, you know that the test expect an exception to be thrown. Let's write our test case:

MoneyTest.cpp

void
MoneyTest::testAddThrow()
{
// Set up
const Money money123FF( 123, "FF" );
// Process
Money money( 123, "USD" );
money += money123FF; // should throw an exception
}

Compile... Ooops, forgot to declare the exception class. Let's do that:

Money.h

#include <string>
#include <stdexcept>
class IncompatibleMoneyError : public std::runtime_error
{
public:
IncompatibleMoneyError() : runtime_error( "Incompatible moneys" )
{
}
};

Compile. As expected testAddThrow() fail... Let's fix that:

Money.h

Money &operator +=( const Money &other )
{
if ( m_currency != other.m_currency )
throw IncompatibleMoneyError();
m_amount += other.m_amount;
return *this;
}

Compile. Our test finaly passes!

TODO:

Credits

This article was written by Baptiste Lepilleur. Unix configuration & set up by Phil Verghese. Inspired from many others (JUnit, Phil's cookbook...), and all the newbies around that keep asking me for the 'Hello world' example ;-)

Send comments to:
CppUnit Developers