Code::Blocks - User contributions [en]

Nightly Cookbook

2014-01-05T11:50:07Z

Killerbot: /* wxWidgets */

[[Category:Developer Documentation]]
This page is under construction by 'killerbot'. Just be patient, some day it will be finished.

== Introduction ==
This article will describe the process used in creating the nightly builds, and can be used as a guideline if you want to build Code::Blocks yourself. It is described as a sequence of 'manual' actions. While it is possible to automate several of these tasks via script, that is beyond the scope of this article.
Current limitation : Windows unicode build.

== Shopping List ==
In order to perform our build tasks, we will need several tools. Let's create an ingredient list for our cooking experiments :
* a compiler
* an initial build system
* the Code::Blocks sources
* zip program
* svn (version control system)
* wxWidgets

While we are at it, maybe someday we want to debug our programs, so let's add a debugger to the list :

* debugger

== Shopping Time ==
=== Compiler ===
Let's start by shopping for the first item on our list, a compiler. Several compilers are available; some free, some expensive. Since the Code::Blocks developers build Code::Blocks using GCC, we might as well use that one. It is very standards compliant, though not the fastest one around. GCC on windows is available in several flavors. There are CygWin ports and MingW ports.

The easiest and cleanest port is MinGW. This is the compiler distributed with Code::Blocks when you download the official package (the one including the compiler). We can find MinGW at [http://www.mingw.org www.mingw.org]. [https://wiki.codeblocks.org/index.php?title=MinGW_installation#gcc_3.4.4_manual_install This post] in the wiki describes how to install MinGW. We will stick to version 3.4.5, which works nicely. (Much has changed since this was originally written; if possible, use version 4.4.0 or newer.)

First, a brief explanation of MinGW components:
* gcc-core : the core of the GCC suite
* gcc-g++ : the c++ compiler
* mingw Runtime : implementation of the run time libraries
* mingw utils : several utilities (implementation of smaller programs that GCC itself uses)
* win32Api : the APIs for creating Windows programs
* binutils : several utilities used in build environments
* make : the Gnu make program, so you can build from make files
* GDB : the Gnu debugger : for hunting those nasty bugs (version 6.3.2 or above !!!)

I would suggest extracting (and installing for the GDB) everything in the C:\MinGW directory. The remainder of this article will assume that this is where you have put it. If you already have an installation of Code::Blocks that came bundled with MinGW (for example RC2), I still advise you to install MinGW as described here. A compiler does not belong under the directory tree of an IDE; they are two separate things. Code::Blocks just brings it along in the official versions so that the average user does not need to bother with this process. But, since you are reading this, you are no longer an average user. :-)

You may need to add the 'bin' directory of your MinGW installation to your path (example : C:\MinGW\bin). An easy way to do this is with the following command at the command prompt:

set path=%PATH%;C:\MinGW\bin;C:\MinGW\mingw32\bin;

=== Initial Build System ===
We could try to build Code::Blocks by using makefiles, but there is an easier way: let's build Code::Blocks by using ........ Code::Blocks. All we need to do is get hold of a pre-built version Code::Blocks.

First, download a nightly build. You can make your selection from [/index.php?board=20.0 here]. The nightly builds are unicode versions, containing the core and contributed plug-ins.

Next, unpack the 7-zip file to any directory you like (e.g. C:\CodeBlocksTempNightly). If you don't have 7-zip, you can download it for free from [http://www.7-zip.org the 7-zip website].

Now, Code::Blocks needs one more dll to work correctly: the WxWidgets dll. You can also download it at the nightly builds forum. Just unzip it into the same directory that you unpacked the Code::Blocks nightly build. It also needs the mingwm10.dll, but don't worry - we already have it. It's in the bin directory of our MinGW installation. So, it's important to make sure the bin directory of your MinGW installation is in your path variable (see above).

Finally, start up this new nightly build of Code::Blocks. It should discover the MinGW compiler we just installed.

== Version Control System ==
In order to be able to retrieve the latest and greatest Code::Blocks sources, we need to install a Version Control System.

The Code::Blocks developers provide their sources through the SVN version control system. So, we need a client to access their svn repository of sources. A nice, easy client for Windows is TortoiseSVN, which is freely available from [http://tortoisesvn.tigris.org/ here]. Download and install it, keeping all suggested settings.

Now, go create a directory wherever you like, for example D:\projects\CodeBlocks. Right click on that directory and choose from the pop-up menu : svn-checkout. In the dialog that pops up, fill in the following information:

- Url of Repository : svn://svn.berlios.de/codeblocks/trunk
- leave all other settings as they are

Now be patient while TortoiseSVN retrieves the most recent source files from the Code::Blocks repository into our local directory. Yes; all those Code::Blocks sources are coming your way!

For more info on SVN settings, see [https://www.codeblocks.org/downloads/svn info on SVN settings]. If you don't like an Explorer integration or look for a cross-plattform client you might want to have a look at [http://rapidsvn.tigris.org/ RapidSVN] (which is btw. also written using wxWidgets).

All righty, time to continue our shopping session.

== wxWidgets ==
WxWidgets is a platform abstraction that provides an API to support many things such as GUI, sockets, files, registry functionality. By using this API, you can create a platform independent program.

Code::Blocks is a wxWidgets (here after: wx ) application, that means if you want to run Code::Blocks you needed the wx functionality. This can be provided in a couple of ways. It could be a .dll or a static library. Code::Blocks uses wx as a dll and this dll can also be downloaded from the nightly build section of the forum.

However, if we want to build a wx application, we need to include the headers of the wx sources. They tell the compiler about the functionality of wx. In addition to those header files, our application needs to link to the wx import libraries. Well, let's take it step by step.

Wx is provided as a zip file of it's sources, so we need to build that ourselves. We already shopped for the MinGW compiler, so we have all the tools we need at hand.

Download the [http://www.wxwidgets.org/downloads/ wx sources] (at time of writing : version 2.8.12) [http://prdownloads.sourceforge.net/wxwindows/wxMSW-2.8.12.zip in this .zip here].

Next, let's unzip the wx sources into C:\Projects so we will end up with a wx root directory like this: C:\Projects\wxWidgets-2.8.12. Note that we are going to refer to the wx root directory from now on as <wxDir>

Now, we are going to build the wxWidgets. This is how we do it:

First, make sure C:\MingGW\bin is in your path, during the build some programs will be called that reside in the the MinGW\bin directory. Also, Make has to be version 3.80 or above.

Now it is time to compile wxWidgets. Open the command prompt and change to the wxWidgets directory:
<tt>cd /D <wxDir>\build\msw</tt>
''Note: the ''<code>/D</code>'' flag after ''<code>cd</code>'' may be omitted from the command; it simply allows command prompt to change drives if necessary.''

We are now in the right place. We are first going to clean up the source:
<tt>mingw32-make -f makefile.gcc SHARED=1 MONOLITHIC=1 BUILD=release UNICODE=1 clean</tt>

Once everything is clean, we can compile wxWidgets:
<tt>mingw32-make -f makefile.gcc SHARED=1 MONOLITHIC=1 BUILD=release UNICODE=1</tt>

If you are using TDM-gcc 4.8.1, you will have to add the following option on the command line :
<tt>CXXFLAGS+=-fpermissive</tt>

This is going to take some time, so go get yourself a nice ice-cream, a beer, ...

Note: For making the debug build, follow these steps:
First clean any previous compilation with:
<tt>mingw32-make -f makefile.gcc SHARED=1 MONOLITHIC=1 BUILD=debug UNICODE=1 clean</tt>

And then compile with:
<tt>mingw32-make -f makefile.gcc SHARED=1 MONOLITHIC=1 BUILD=debug UNICODE=1</tt>

... If you are not on diet, get another ice-cream, a beer, ....

Did you enjoy your refreshment? Well have a little look in the directory (<wxDir>\lib\gcc_dll) now. The import libraries and the dll have shown up and there should also a mswu\wx subdirectory at that position containing setup.h.

Congratulations! You have just built wxWidgets!

Let's do some more preliminary tasks before we get to the real deal of compiling Code::Blocks.

== Zip ==
During the build of Code::Blocks, several resources are going to be zipped in zip files. Therefore, the build process should have access to a zip.exe. We have to download that zip.exe and put it somewhere in our path. A good place is: MingW\bin.

You can download zip.exe for free from [http://www.info-zip.org/Zip.html this site] and this is a [ftp://ftp.info-zip.org/pub/infozip/win32/zip232xn.zip direct link(32bit)] to the most recent version at the time of this writing.

Once downloaded, simply extract zip.exe to the appropriate location.

== Workspace ==
This brings us to the last preliminary task. The Code::Blocks code can be divided into 2 major parts: the core with internal plug-ins, and the contributed plug-ins. You always need to build the core/internal parts before building the contrib part.

To build the internal part, you can use the Code::Blocks project file which you can find at: <cbDir>\src\CodeBlocks.cbp. Our Code::Blocks master directory is from now one mentioned as <cbDir>, by the way. A workspace is something that groups several projects together. To build the contrib plug-ins, they can be found at <cbDir>\src\ContribPlugins.workspace.

But, let's create a workspace containing everything. Let's put that workspace in the master directory <cbDir>. Just use a regular text editor and create a file with the name "CbProjects.workspace" and give it the following content :

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_workspace_file>
<Workspace title="Workspace">
<Project filename="src\CodeBlocks.cbp" active="1" />
<Project filename="src\plugins\contrib\AutoVersioning\AutoVersioning.cbp" />
<Project filename="src\plugins\contrib\BrowseTracker\BrowseTracker.cbp" />
<Project filename="src\plugins\contrib\byogames\byogames.cbp" />
<Project filename="src\plugins\contrib\cb_koders\cb_koders.cbp" />
<Project filename="src\plugins\contrib\codesnippets\codesnippets.cbp" />
<Project filename="src\plugins\contrib\codestat\codestat.cbp" />
<Project filename="src\plugins\contrib\copystrings\copystrings.cbp" />
<Project filename="src\plugins\contrib\devpak_plugin\DevPakPlugin.cbp" />
<Project filename="src\plugins\contrib\dragscroll\dragscroll.cbp" />
<Project filename="src\plugins\contrib\envvars\envvars.cbp" />
<Project filename="src\plugins\contrib\headerfixup\headerfixup.cbp" />
<Project filename="src\plugins\contrib\help_plugin\help-plugin.cbp" />
<Project filename="src\plugins\contrib\keybinder\keybinder.cbp" />
<Project filename="src\plugins\contrib\profiler\cbprofiler.cbp" />
<Project filename="src\plugins\contrib\regex_testbed\RegExTestbed.cbp" />
<Project filename="src\plugins\contrib\source_exporter\Exporter.cbp" />
<Project filename="src\plugins\contrib\symtab\symtab.cbp" />
<Project filename="src\plugins\contrib\ThreadSearch\ThreadSearch.cbp" />
<Project filename="src\plugins\contrib\wxSmith\wxSmith.cbp" />
<Project filename="src\plugins\contrib\wxSmithContribItems\wxSmithContribItems.cbp" />
<Project filename="src\plugins\contrib\wxSmithAui\wxSmithAui.cbp" />
<Project filename="src\plugins\contrib\lib_finder\lib_finder.cbp" />
<Project filename="src\plugins\contrib\HexEditor\HexEditor-win.cbp" />
<Project filename="src\tools\cb_share_config\cb_share_config.cbp" />
<Project filename="src\plugins\contrib\IncrementalSearch\IncrementalSearch.cbp" />
<Project filename="src\plugins\contrib\MouseSap\MouseSap.cbp" />
</Workspace>
</CodeBlocks_workspace_file>

We will use this workspace to build all of Code::Blocks.

== Building Code::Blocks ==
Finally we have arrived at the final step; our final goal. Run the Code::Blocks executable from your nightly build download. Choose Open from the File menu and browse for our above created workspace, and open it up. Be a little patient while Code::Blocks is parsing everything, and Code::Blocks will ask us for 2 global variables, these global variables will tell the nightly Code::Blocks where it can find wxWidgets (remember : header files and import libraries) and where it can find .... Code::Blocks, this is needed for the contrib plug-ins, they need to know (as for any user created plug-in) where the sdk (Code::Blocks header files) are.
These are the values in our case :
- wx : <wxDir>
- Code::Blocks (cb) : <cbDir>\src

Now go to the Project Menu and choose (re)build workspace, and off you go. Watch how Code::Blocks is building Code::Blocks.

Once the build is complete, open up a console in <cbDir>\src and run the command "update.bat". This will transfer all built deliverables from <cbDir>\src\devel to <cbDir>\src\output. In addition, it will strip out all debugging symbols. This step is very important - never ever forget it.

Now you can copy the wx dll in both that output and the devel directory.

Then you can close Code::Blocks. That was the downloaded nightly remember?

Time to test it. In the output directory, start up the CodeBlocks.exe. If everything went well, you'll have your very own home-built Code::Blocks running.

Enjoy !!!

Nightly Cookbook

2014-01-05T11:49:32Z

Killerbot: /* wxWidgets */

[[Category:Developer Documentation]]
This page is under construction by 'killerbot'. Just be patient, some day it will be finished.

== Introduction ==
This article will describe the process used in creating the nightly builds, and can be used as a guideline if you want to build Code::Blocks yourself. It is described as a sequence of 'manual' actions. While it is possible to automate several of these tasks via script, that is beyond the scope of this article.
Current limitation : Windows unicode build.

== Shopping List ==
In order to perform our build tasks, we will need several tools. Let's create an ingredient list for our cooking experiments :
* a compiler
* an initial build system
* the Code::Blocks sources
* zip program
* svn (version control system)
* wxWidgets

While we are at it, maybe someday we want to debug our programs, so let's add a debugger to the list :

* debugger

== Shopping Time ==
=== Compiler ===
Let's start by shopping for the first item on our list, a compiler. Several compilers are available; some free, some expensive. Since the Code::Blocks developers build Code::Blocks using GCC, we might as well use that one. It is very standards compliant, though not the fastest one around. GCC on windows is available in several flavors. There are CygWin ports and MingW ports.

The easiest and cleanest port is MinGW. This is the compiler distributed with Code::Blocks when you download the official package (the one including the compiler). We can find MinGW at [http://www.mingw.org www.mingw.org]. [https://wiki.codeblocks.org/index.php?title=MinGW_installation#gcc_3.4.4_manual_install This post] in the wiki describes how to install MinGW. We will stick to version 3.4.5, which works nicely. (Much has changed since this was originally written; if possible, use version 4.4.0 or newer.)

First, a brief explanation of MinGW components:
* gcc-core : the core of the GCC suite
* gcc-g++ : the c++ compiler
* mingw Runtime : implementation of the run time libraries
* mingw utils : several utilities (implementation of smaller programs that GCC itself uses)
* win32Api : the APIs for creating Windows programs
* binutils : several utilities used in build environments
* make : the Gnu make program, so you can build from make files
* GDB : the Gnu debugger : for hunting those nasty bugs (version 6.3.2 or above !!!)

I would suggest extracting (and installing for the GDB) everything in the C:\MinGW directory. The remainder of this article will assume that this is where you have put it. If you already have an installation of Code::Blocks that came bundled with MinGW (for example RC2), I still advise you to install MinGW as described here. A compiler does not belong under the directory tree of an IDE; they are two separate things. Code::Blocks just brings it along in the official versions so that the average user does not need to bother with this process. But, since you are reading this, you are no longer an average user. :-)

You may need to add the 'bin' directory of your MinGW installation to your path (example : C:\MinGW\bin). An easy way to do this is with the following command at the command prompt:

set path=%PATH%;C:\MinGW\bin;C:\MinGW\mingw32\bin;

=== Initial Build System ===
We could try to build Code::Blocks by using makefiles, but there is an easier way: let's build Code::Blocks by using ........ Code::Blocks. All we need to do is get hold of a pre-built version Code::Blocks.

First, download a nightly build. You can make your selection from [/index.php?board=20.0 here]. The nightly builds are unicode versions, containing the core and contributed plug-ins.

Next, unpack the 7-zip file to any directory you like (e.g. C:\CodeBlocksTempNightly). If you don't have 7-zip, you can download it for free from [http://www.7-zip.org the 7-zip website].

Now, Code::Blocks needs one more dll to work correctly: the WxWidgets dll. You can also download it at the nightly builds forum. Just unzip it into the same directory that you unpacked the Code::Blocks nightly build. It also needs the mingwm10.dll, but don't worry - we already have it. It's in the bin directory of our MinGW installation. So, it's important to make sure the bin directory of your MinGW installation is in your path variable (see above).

Finally, start up this new nightly build of Code::Blocks. It should discover the MinGW compiler we just installed.

== Version Control System ==
In order to be able to retrieve the latest and greatest Code::Blocks sources, we need to install a Version Control System.

The Code::Blocks developers provide their sources through the SVN version control system. So, we need a client to access their svn repository of sources. A nice, easy client for Windows is TortoiseSVN, which is freely available from [http://tortoisesvn.tigris.org/ here]. Download and install it, keeping all suggested settings.

Now, go create a directory wherever you like, for example D:\projects\CodeBlocks. Right click on that directory and choose from the pop-up menu : svn-checkout. In the dialog that pops up, fill in the following information:

- Url of Repository : svn://svn.berlios.de/codeblocks/trunk
- leave all other settings as they are

Now be patient while TortoiseSVN retrieves the most recent source files from the Code::Blocks repository into our local directory. Yes; all those Code::Blocks sources are coming your way!

For more info on SVN settings, see [https://www.codeblocks.org/downloads/svn info on SVN settings]. If you don't like an Explorer integration or look for a cross-plattform client you might want to have a look at [http://rapidsvn.tigris.org/ RapidSVN] (which is btw. also written using wxWidgets).

All righty, time to continue our shopping session.

== wxWidgets ==
WxWidgets is a platform abstraction that provides an API to support many things such as GUI, sockets, files, registry functionality. By using this API, you can create a platform independent program.

Code::Blocks is a wxWidgets (here after: wx ) application, that means if you want to run Code::Blocks you needed the wx functionality. This can be provided in a couple of ways. It could be a .dll or a static library. Code::Blocks uses wx as a dll and this dll can also be downloaded from the nightly build section of the forum.

However, if we want to build a wx application, we need to include the headers of the wx sources. They tell the compiler about the functionality of wx. In addition to those header files, our application needs to link to the wx import libraries. Well, let's take it step by step.

Wx is provided as a zip file of it's sources, so we need to build that ourselves. We already shopped for the MinGW compiler, so we have all the tools we need at hand.

Download the [http://www.wxwidgets.org/downloads/ wx sources] (at time of writing : version 2.8.12) [http://prdownloads.sourceforge.net/wxwindows/wxMSW-2.8.12.zip in this .zip here].

Next, let's unzip the wx sources into C:\Projects so we will end up with a wx root directory like this: C:\Projects\wxWidgets-2.8.12. Note that we are going to refer to the wx root directory from now on as <wxDir>

Now, we are going to build the wxWidgets. This is how we do it:

First, make sure C:\MingGW\bin is in your path, during the build some programs will be called that reside in the the MinGW\bin directory. Also, Make has to be version 3.80 or above.

Now it is time to compile wxWidgets. Open the command prompt and change to the wxWidgets directory:
<tt>cd /D <wxDir>\build\msw</tt>
''Note: the ''<code>/D</code>'' flag after ''<code>cd</code>'' may be omitted from the command; it simply allows command prompt to change drives if necessary.''

We are now in the right place. We are first going to clean up the source:
<tt>mingw32-make -f makefile.gcc SHARED=1 MONOLITHIC=1 BUILD=release UNICODE=1 clean</tt>

Once everything is clean, we can compile wxWidgets:
<tt>mingw32-make -f makefile.gcc SHARED=1 MONOLITHIC=1 BUILD=release UNICODE=1</tt>

If you are using TDM-gcc 4.8.1, you will have to add hte following option on the command line : CXXFLAGS+=-fpermissive

This is going to take some time, so go get yourself a nice ice-cream, a beer, ...

Note: For making the debug build, follow these steps:
First clean any previous compilation with:
<tt>mingw32-make -f makefile.gcc SHARED=1 MONOLITHIC=1 BUILD=debug UNICODE=1 clean</tt>

And then compile with:
<tt>mingw32-make -f makefile.gcc SHARED=1 MONOLITHIC=1 BUILD=debug UNICODE=1</tt>

... If you are not on diet, get another ice-cream, a beer, ....

Did you enjoy your refreshment? Well have a little look in the directory (<wxDir>\lib\gcc_dll) now. The import libraries and the dll have shown up and there should also a mswu\wx subdirectory at that position containing setup.h.

Congratulations! You have just built wxWidgets!

Let's do some more preliminary tasks before we get to the real deal of compiling Code::Blocks.

== Zip ==
During the build of Code::Blocks, several resources are going to be zipped in zip files. Therefore, the build process should have access to a zip.exe. We have to download that zip.exe and put it somewhere in our path. A good place is: MingW\bin.

You can download zip.exe for free from [http://www.info-zip.org/Zip.html this site] and this is a [ftp://ftp.info-zip.org/pub/infozip/win32/zip232xn.zip direct link(32bit)] to the most recent version at the time of this writing.

Once downloaded, simply extract zip.exe to the appropriate location.

== Workspace ==
This brings us to the last preliminary task. The Code::Blocks code can be divided into 2 major parts: the core with internal plug-ins, and the contributed plug-ins. You always need to build the core/internal parts before building the contrib part.

To build the internal part, you can use the Code::Blocks project file which you can find at: <cbDir>\src\CodeBlocks.cbp. Our Code::Blocks master directory is from now one mentioned as <cbDir>, by the way. A workspace is something that groups several projects together. To build the contrib plug-ins, they can be found at <cbDir>\src\ContribPlugins.workspace.

But, let's create a workspace containing everything. Let's put that workspace in the master directory <cbDir>. Just use a regular text editor and create a file with the name "CbProjects.workspace" and give it the following content :

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_workspace_file>
<Workspace title="Workspace">
<Project filename="src\CodeBlocks.cbp" active="1" />
<Project filename="src\plugins\contrib\AutoVersioning\AutoVersioning.cbp" />
<Project filename="src\plugins\contrib\BrowseTracker\BrowseTracker.cbp" />
<Project filename="src\plugins\contrib\byogames\byogames.cbp" />
<Project filename="src\plugins\contrib\cb_koders\cb_koders.cbp" />
<Project filename="src\plugins\contrib\codesnippets\codesnippets.cbp" />
<Project filename="src\plugins\contrib\codestat\codestat.cbp" />
<Project filename="src\plugins\contrib\copystrings\copystrings.cbp" />
<Project filename="src\plugins\contrib\devpak_plugin\DevPakPlugin.cbp" />
<Project filename="src\plugins\contrib\dragscroll\dragscroll.cbp" />
<Project filename="src\plugins\contrib\envvars\envvars.cbp" />
<Project filename="src\plugins\contrib\headerfixup\headerfixup.cbp" />
<Project filename="src\plugins\contrib\help_plugin\help-plugin.cbp" />
<Project filename="src\plugins\contrib\keybinder\keybinder.cbp" />
<Project filename="src\plugins\contrib\profiler\cbprofiler.cbp" />
<Project filename="src\plugins\contrib\regex_testbed\RegExTestbed.cbp" />
<Project filename="src\plugins\contrib\source_exporter\Exporter.cbp" />
<Project filename="src\plugins\contrib\symtab\symtab.cbp" />
<Project filename="src\plugins\contrib\ThreadSearch\ThreadSearch.cbp" />
<Project filename="src\plugins\contrib\wxSmith\wxSmith.cbp" />
<Project filename="src\plugins\contrib\wxSmithContribItems\wxSmithContribItems.cbp" />
<Project filename="src\plugins\contrib\wxSmithAui\wxSmithAui.cbp" />
<Project filename="src\plugins\contrib\lib_finder\lib_finder.cbp" />
<Project filename="src\plugins\contrib\HexEditor\HexEditor-win.cbp" />
<Project filename="src\tools\cb_share_config\cb_share_config.cbp" />
<Project filename="src\plugins\contrib\IncrementalSearch\IncrementalSearch.cbp" />
<Project filename="src\plugins\contrib\MouseSap\MouseSap.cbp" />
</Workspace>
</CodeBlocks_workspace_file>

We will use this workspace to build all of Code::Blocks.

== Building Code::Blocks ==
Finally we have arrived at the final step; our final goal. Run the Code::Blocks executable from your nightly build download. Choose Open from the File menu and browse for our above created workspace, and open it up. Be a little patient while Code::Blocks is parsing everything, and Code::Blocks will ask us for 2 global variables, these global variables will tell the nightly Code::Blocks where it can find wxWidgets (remember : header files and import libraries) and where it can find .... Code::Blocks, this is needed for the contrib plug-ins, they need to know (as for any user created plug-in) where the sdk (Code::Blocks header files) are.
These are the values in our case :
- wx : <wxDir>
- Code::Blocks (cb) : <cbDir>\src

Now go to the Project Menu and choose (re)build workspace, and off you go. Watch how Code::Blocks is building Code::Blocks.

Once the build is complete, open up a console in <cbDir>\src and run the command "update.bat". This will transfer all built deliverables from <cbDir>\src\devel to <cbDir>\src\output. In addition, it will strip out all debugging symbols. This step is very important - never ever forget it.

Now you can copy the wx dll in both that output and the devel directory.

Then you can close Code::Blocks. That was the downloaded nightly remember?

Time to test it. In the output directory, start up the CodeBlocks.exe. If everything went well, you'll have your very own home-built Code::Blocks running.

Enjoy !!!

UnitTesting

2010-07-22T09:06:19Z

Killerbot: /* LeapYear-Step2 */

This document is under development by killerbot. Starting from 7 September 2009.

== Introduction ==
This document will describe how unit testing can be combined with the Code::Blocks IDE. It will give a hands-on example on a unit testing framework and how it can be used with Code::Blocks.

== What is Unit Testing ==
Simply put Unit Testing is the discipline and best practice of writing and running little test programs that test little units of code.
Such a unit can be :
* a class
* a free function
* an interface
* ...
There are several unit test frameworks available to help you write, deploy, manage your unit tests. The most famous family is the xUnit framework, and some of it's descendants.

== Why Unit Testing ==
Well we write code that implements some functionality. We need a way to check and prove that the implementation is correct. Therefor we need tests. We need tests on the application level, at the integration level of different components, classes, interfaces. But we also need tests for the smallest building blocks, the units.
We also want these tests to run very quickly. That way we can run the tests often, manually or automated.
These tests will also be our safeguards during refactoring of the code, extending the code or whatever maintenance tasks we carry out on the code.
These tests will also make us think of how our class, method, ... will be used. Since the test can be seen as a user of our code. Thanks to this, thinking about the tests before implementing the functionality can help us in the design : emergent design.
It will help us to avoid creating big classes, complex functions. We will only write the methods that are really needed, and no methods that we think might (n)ever be useful in the future. We are no good future tellers ! Those 'might be needed' methods and their tests are just a waste of time. Extending, refactoring will be done when it is actually needed, and at that time we have our unit tests to ensure we don't break any existing code.

Other times to add new unit tests are typically when a bug is discovered. Write a unit test to reproduce the bug, fix the code, and from now on the new unit test will watch your back so the bug won't reappear.

Unit test are also a good place of documentation. The little tests show how the class or method is used.
The code documents itself.

So the benefits are :
* better design
* prove of your code
* safe guard during code maintenance (refactoring, extensions)
* documentation
* ...

== Unit Test frameworks ==
When writing unit tests, one will create a lot of similar code. Since unit tests are nothing more then little programs, several tasks will be repeated, setting up the test environment, create your class, call a method, verify it's result, write out an error message when the test fails, preferably specifying what the wrong outcome was, and what the expected result is.
All these repetitive chores are taken care of by the frame work so the developer can focus on the real code of the test.
This document will use a small but very effective framework for the C++ language. It is called UnitTest++. It's homepage is at : [http://unittest-cpp.sourceforge.net/ UnitTest++].
You can download it directly at this [http://sourceforge.net/projects/unittest-cpp/files/UnitTest%2B%2B/1.4/unittest-cpp-1.4.zip/download link]. At the time of writing the latest version is 1.4.

== Setup our environment ==
Let's create a directory on our PC in which we will cary out our experiments. I will refer to this directory from now on as <TestPit>. For my laptop on which I am writing this article, that will be /home/lieven/Projects/UnitTestArticle. Note that everything we will do, works on linux and on windows!
Download the "unittest-cpp-1.4.zip" file from the link specified above. Extract it in the <TestPit> directory. All the files will end up in the <TestPit>/UnitTest++ directory.

== Build UnitTest++ ==
After the extracted the zip archive we have a directory structure like this :
<pre>
<TestPit>/UnitTest++
|
+docs
|
+src
</pre>
The files in the UnitTest++ directory are of little use for us, since they bring project files for some bizarre Microsoft IDE ;-) .
We will create our own Code::Blocks project to build the UnitTest++ framework.

Why do we need to build something ? Well as said, the framework will do a lot of chores for us, those chores are implemented by code, that code is the framework. We will build to framework into a static library, and for every unit test (or set of unit tests) we create a little (console/shell) program with the test code we wrote, which will link with the static library to obtain a unit test executable, driven by the framework.

We will put our Code::Blocks project file in a nice structured directory tree, therefor let's create a 'Project' subdirectory in the <TestPit>/UnitTest++ directory.

In there create a new file with the name "UnitTest++.cbp".
Give that file the following content :

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="UnitTest++" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option platforms="Windows;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option platforms="Windows;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
<Target title="Debug(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<VirtualTargets>
<Add alias="All" targets="Debug;Release;Debug(linux);Release(linux);" />
</VirtualTargets>
<Unit filename="../src/AssertException.cpp" />
<Unit filename="../src/AssertException.h" />
<Unit filename="../src/CheckMacros.h" />
<Unit filename="../src/Checks.cpp" />
<Unit filename="../src/Checks.h" />
<Unit filename="../src/Config.h" />
<Unit filename="../src/CurrentTest.cpp" />
<Unit filename="../src/CurrentTest.h" />
<Unit filename="../src/DeferredTestReporter.cpp" />
<Unit filename="../src/DeferredTestReporter.h" />
<Unit filename="../src/DeferredTestResult.cpp" />
<Unit filename="../src/DeferredTestResult.h" />
<Unit filename="../src/ExecuteTest.h" />
<Unit filename="../src/MemoryOutStream.cpp" />
<Unit filename="../src/MemoryOutStream.h" />
<Unit filename="../src/Posix/SignalTranslator.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/SignalTranslator.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/ReportAssert.cpp" />
<Unit filename="../src/ReportAssert.h" />
<Unit filename="../src/Test.cpp" />
<Unit filename="../src/Test.h" />
<Unit filename="../src/TestDetails.cpp" />
<Unit filename="../src/TestDetails.h" />
<Unit filename="../src/TestList.cpp" />
<Unit filename="../src/TestList.h" />
<Unit filename="../src/TestMacros.h" />
<Unit filename="../src/TestReporter.cpp" />
<Unit filename="../src/TestReporter.h" />
<Unit filename="../src/TestReporterStdout.cpp" />
<Unit filename="../src/TestReporterStdout.h" />
<Unit filename="../src/TestResults.cpp" />
<Unit filename="../src/TestResults.h" />
<Unit filename="../src/TestRunner.cpp" />
<Unit filename="../src/TestRunner.h" />
<Unit filename="../src/TestSuite.h" />
<Unit filename="../src/TimeConstraint.cpp" />
<Unit filename="../src/TimeConstraint.h" />
<Unit filename="../src/TimeHelpers.h" />
<Unit filename="../src/UnitTest++.h" />
<Unit filename="../src/Win32/TimeHelpers.cpp">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/Win32/TimeHelpers.h">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/XmlTestReporter.cpp" />
<Unit filename="../src/XmlTestReporter.h" />
<Extensions>
<envvars />
<code_completion />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

Some things to note about the content of the project file, the power of Code::Blocks.
* there are 4 targets : Debug/Release for Windows and Debug/Release for linux [yes : 1 project file that allows building on linux and on windows]
* some files are only part of the linux targets, some only for the windows targets

But before we build, let's modify some source files (not really needed, but I prefer to have warning free compilations). These are the changes I carried out :
* ReportAssert.cpp : #include "ReportAssert.h"
* win32/TimeHelpers.cpp : first the m_threadHandle and then the m_startTime in the initializerlist

Next open up this project file in Code::Blocks and build the debug and release target. From now one we will only use the Release target, we go for speed ;-)

The result of the build process will show up in subdirectories of the new 'Deliv' subdirectory of <testPit>/UnitTest++ : '''<testPit>/UnitTest++/Deliv/Release/libUnitTest++.a'''

Alright, we have build the unit test framework in a platform independent way, no silly makefiles, no obscure M$ IDE, good old super Code::Blocks. It is time to write some code so we have something to unit test.

In the first example we will create a simple free function that checks if a given year is a leap year or not.

The business logic is as follows : a year is a leap year when it can be divided by 4, unless it can be divided by 100. But in case it can be divided by 400, then again it is a leap year.

In the next section we will first setup a Code::Blocks project containing both the 'functionality files, and the unit test files. Typically one will package several functionality files into a static library and create a unit test project that tests all the class/functionalities in that library package, also called a component. That is we have a component (whose deliverable is the static library, and we have a unit test project that tests the entire component).

== Our first test project environment ==
Let's create a new directory in our <TestPit> : <TestPit>/LeapYear.
For the simplicity we will put the project file and the source file all together in this directory. Normally we would work in a more structured way, but in a demo article we have some artistic freedom ;-)
Next you can create with the Code::Block's wizard a new console project in the LeapYear directory. Or you can create the following 5 files and give the the contents as specified below. Note that this demo works on linux and on windows, everything is still completely platform independent. Long Live Code::Blocks.

The project file : LeapYear.cbp (the one below already contains the 4 source files, in case you use the wizard you have to add the LeapYear.h/cpp and LeapYearTest.cpp files to the project)

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="LeapYear" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option output="Deliv/Debug/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Debug/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option output="Deliv/Release/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Release/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-O2" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<Compiler>
<Add option="-Wall" />
<Add option="-fexceptions" />
</Compiler>
<Unit filename="LeapYear.cpp" />
<Unit filename="LeapYear.h" />
<Unit filename="LeapYearTest.cpp" />
<Unit filename="main.cpp" />
<Extensions>
<envvars />
<code_completion />
<lib_finder disable_auto="1" />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

The main source file : main.cpp
int main()
{
return 0;
}

The header exporting our powerful function : LeapYear.h

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

#endif // LEAPYEAR_H_INCLUDED

And the implementation of the leap year logic : LeapYear.cpp

#include "LeapYear.h"

And finishing with the source file for the tests : LeapYearTest.cpp (currently) empty

We can already build the project, we have a nice little program that does .... nothing.

Time to move to the next section, a little word about Test Driven Development.

== Test Driven Development ==
This is a practice where new code is only added to make a failing test pass. And one only adds the code needed to make that test pass. Once that is done, a new test is added that will check the next functionality to add.
On this really simple example we will more or less practice some TDD.

So get ready, it's time for LeapYear-Step1.

== LeapYear-Step1 ==
We will turn our main.cpp into the guy in charge to carry out the tests, all we need to do is change the contents of main.cpp into this :

<source lang="cpp">
#include "UnitTest++.h"

int main()
{
return UnitTest::RunAllTests();
}

</source>
And add '''../UnitTest++/src''' to the compiler search directories on the project level of our LeapYear project.
And add '''../UnitTest++/Deliv/Release/libUnitTest++.a''' to the link libraries of the project

Why : well we need to link with the framework and we need to include the UnitTest++ header so we can use it's functionalities.

The line '''UnitTest::RunAllTests()''' will make sure all test encountered in our sources will be carried out.
We don't have any tests yet, nor any functionality, but go ahead build the project and run it.
This is the output :

Success: 0 tests passed
Test time: 0.00 seconds.

Great : success, but no tests yet. Well it's a start.
Time to move forward, and write our first test.

== LeapYear-Step2 ==
Test, test, but there's nothing to test. Yes, absolutely. Let's think of a test, a test that will help us in the design. Now that's a good idea. Suppose I would be the user of the uplifting problem solving leap year checking library/component ... hmmm modesty first : leap year checking '''function'''.
How would I like that function to look.
<source lang="cpp">
bool IsLeapYear(int Year);
</source>
Yes that seems acceptable.
So let's write a test that will call that method.
We do that by adding the following code to LeapYearTest.cpp

<source lang="cpp">
#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

}

</source>
Things to note :
* we include the unit test header
* it is good to put the tests in a nameless namespace (will be explained later on)
* we use the TEST macro, the argument is the name of the test : OurFirstTest
* we use CHECK_EQUAL to check if the expected result (the first argument) matches the computed result (the second argument)

Time to build. Woooooops errors. The test fails completely, it does not even build. Time to add the code needed.
In order to compile the test file, we need to include the LeapYear.h header and have that header export our function.
Our LeapYear header will look like this now (don't forget the include in the test file of our LeapYear.h header, it is not shown here) :

<source lang="cpp">
#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

bool IsLeapYear(int Year);

#endif // LEAPYEAR_H_INCLUDED

</source>

At least now it compiles, but it doesn't link yet. Duh ! That's because we don't have an implementation yet.
Time to provide the bare minimum of code to make the test pass.
So we change the LeapYear.cpp into :

<source lang="cpp">
#include "LeapYear.h"

bool IsLeapYear(int /*Year*/)
{
return true;
}

</source>
Build it, run it. Yes, we have one working test.
Great. Let's move on.

== LeapYear-Step3 ==
Does anyone have the feeling we are cheating? Well the user does not know how we wrote our code on the inside. So just to be sure the user (we) adds the following test, ending up in :

<source lang="cpp">
#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

TEST(OurSecondTest)
{
const bool Result = IsLeapYear(1973);
CHECK_EQUAL(false, Result);
}

}

</source>
Building is already no issue any more, we can run it. Oh boy, a test is failing.
The framework tell us something like this :
<filename>:<Line>: error: Failure in OurSecondTest: Expected 0 but was 1
FAILURE: 1 out of 2 tests failed (1 failures)
Test time: 0.00 seconds.

So we are informed of the line where the failing test occurs, next to that it tells us what it was expecting and what the actual outcome was. And it presents a resume of the total number of tests, and how many that failed. For you scripting hackers note that FAILURE != SUCCESS.

It seems we should do some more effort and implement some real logic.

== LeapYear-Step4 ==
Let's keep it taking one step at a time. Let's start by implementing the 'divisible by 4' logic. That will already solve our tests.
So our LeapYear.cpp will now look like this :

<source lang="cpp">
#include "LeapYear.h"

namespace
{

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year);
}

</source>
Build, run. All tests pass. Life is great.

But those changing requirements, always the change of the requirements. Years that can be divided by 100 should not be considered as a leap year.

Time for our next step.

== LeapYear-Step5 ==
We add a new test for checking for example the year 1900.

<source lang="cpp">
TEST(DivisableBy100)
{
const bool Result = IsLeapYear(1900);
CHECK_EQUAL(false, Result);
}
</source>

Build and run the tests. It will fail. So time to add the minimum code needed to make this test pass.
This will change our LeapYear.cpp into :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year) && !IsDivisableBy100(Year);
}

</source>

Build and run the tests, yes : success. All 3 tests pass.

It seems life might be great again ...

Wrong, someone just added the following test :

<source lang="cpp">
TEST(DivisableBy400)
{
const bool Result = IsLeapYear(2000);
CHECK_EQUAL(true, Result);
}
</source>

And we once again have a failing test.

Time for the next step.

== LeapYear-Step6 ==
We should add logic to deal with years that can be divided by 400, since those are leap years.
We change our LeapYear.cpp into this :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy400(int Year)
{
return (Year%400) == 0;
}

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
const bool LeapYear = IsDivisableBy400(Year) ||
(IsDivisableBy4(Year) && !IsDivisableBy100(Year));
return LeapYear;
}

</source>

And once again everything works OK.
And it seems all the logical rules have been implemented.
This one is ready for shipping, and till the end of time we have our tests that can be run whenever we want (more on this later, we'd prefer this to be done automatically) to ensure we never break anything.

== Increase the user experience ==
There are a few areas where we can increase the user experience.
When a unit test fails the framework tell use on which line in the the code his happens.
That's excellent.
BUT we see this information in a console/shell windows. So we need to find that window, read the issues, remember them and then go find our test source files and navigate manually to the offending line. This works but is very cumbersome.
We want this to be a no-brainer, and have these steps being carried out for us.

Well, didn't we say life is great, Code::Blocks and UnitTest++ to the rescue. The error/warning output of the framework is in the gcc format. That means Code::Blocks can parse it.
One restriction Code::Blocks can parse it during the 'build process'. But currently the build process stops after the unit test executable is built, and only then we run the test executable (manually).
Solution have Code::Blocks run the test executable as a post-build step. Pre-build and post-build steps are part of the build process !
Important consequence : if you want to debug something, the debugger will only kick off after Code::Blocks was able to carry out a successful build (including the pre/post builds steps). Therefor it is not wise to have the unit test executable being carried out as a post-build step of the 'Debug' target. But as a post-build step of the Release target, our goal is met.

Adjust the target settings for the 'Release' target [Build Options -> select Release target -> Pre/Post-build steps -> Post-build steps text field] and add the following '''$exe_output'''. you can tick the 'Always execute' if you want.

Now build your Release target, and look at what shows up in the 'Build Log' tab in Code::Blocks.
This is my output :
<pre>

-------------- Build: Release in LeapYear ---------------

[ 25.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/LeapYear.cpp -o Deliv/Release/LeapYear.o
[ 50.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/LeapYearTest.cpp -o Deliv/Release/LeapYearTest.o
[ 75.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/main.cpp -o Deliv/Release/main.o
[100.0%] g++ -o Deliv/Release/LeapYear Deliv/Release/LeapYear.o Deliv/Release/LeapYearTest.o Deliv/Release/main.o -s ../UnitTest++/Deliv/Release/libUnitTest++.a
Output size is 23.28 KB
[100.0%] Running target post-build steps
Deliv/Release/LeapYear
Success: 4 tests passed.
Test time: 0.00 seconds.
Process terminated with status 0 (0 minutes, 2 seconds)
0 errors, 0 warnings
Build log saved as:
file:///home/lieven/Projects/UnitTestArticle/LeapYear/LeapYear_build_log.html
</pre>

We see that the unit test has been carried out, automatically.

Let's demonstrate that upon a failed test, Code::Blocks will jump to the offending line.
Change the latest test, the one checking on the year 2000 : change 2000 to 2001.
And build : Code::Blocks will jump to the offending line, and shows an entry in the "Build messages" tab (error: Failure in DivisableBy400: Expected 1 but was 0), just like for a regular compiler warning/error.
In the "Build" tab, we now find something like (red colored since it is an error) :
<pre>

-------------- Build: Release in LeapYear ---------------

[ 50.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/LeapYearTest.cpp -o Deliv/Release/LeapYearTest.o
[100.0%] g++ -o Deliv/Release/LeapYear Deliv/Release/LeapYear.o Deliv/Release/LeapYearTest.o Deliv/Release/main.o -s ../UnitTest++/Deliv/Release/libUnitTest++.a
Output size is 23.28 KB
[100.0%] Running target post-build steps
Deliv/Release/LeapYear
/home/lieven/Projects/UnitTestArticle/LeapYear/LeapYearTest.cpp:28: error: Failure in DivisableBy400: Expected 1 but was 0
FAILURE: 1 out of 4 tests failed (1 failures).
Test time: 0.00 seconds.
Process terminated with status 1 (0 minutes, 1 seconds)
1 errors, 0 warnings
Build log saved as:
file:///home/lieven/Projects/UnitTestArticle/LeapYear/LeapYear_build_log.html
</pre>

Voila, we have increased the user experience.
Time to readjust the final test, 2001 becomes 2000 again ;-)

== Further automation ==
You can create a script that calls Code::Blocks on the command line and passes it our LeapYear.cbp project file, and it will build both targets (Debug/Release) and run the test, since it is a post-build step for the 'Release' target.
Bye bye funky makefiles, welcome Code::Blocks as your build system.

== More to come ==
More examples will be added, showcasing 'fixtures' (setup/teardown), some more CHECK macros of UnitTest++. In case you have some tips/ideas, drop me a PM in the forum.
On the planning is a full conversion of the Money example, but all with gcc and Code::Blocks instead of the crazy Microsoft IDE.

UnitTesting

2010-07-22T09:03:45Z

Killerbot: /* Why Unit Testing */

This document is under development by killerbot. Starting from 7 September 2009.

== Introduction ==
This document will describe how unit testing can be combined with the Code::Blocks IDE. It will give a hands-on example on a unit testing framework and how it can be used with Code::Blocks.

== What is Unit Testing ==
Simply put Unit Testing is the discipline and best practice of writing and running little test programs that test little units of code.
Such a unit can be :
* a class
* a free function
* an interface
* ...
There are several unit test frameworks available to help you write, deploy, manage your unit tests. The most famous family is the xUnit framework, and some of it's descendants.

== Why Unit Testing ==
Well we write code that implements some functionality. We need a way to check and prove that the implementation is correct. Therefor we need tests. We need tests on the application level, at the integration level of different components, classes, interfaces. But we also need tests for the smallest building blocks, the units.
We also want these tests to run very quickly. That way we can run the tests often, manually or automated.
These tests will also be our safeguards during refactoring of the code, extending the code or whatever maintenance tasks we carry out on the code.
These tests will also make us think of how our class, method, ... will be used. Since the test can be seen as a user of our code. Thanks to this, thinking about the tests before implementing the functionality can help us in the design : emergent design.
It will help us to avoid creating big classes, complex functions. We will only write the methods that are really needed, and no methods that we think might (n)ever be useful in the future. We are no good future tellers ! Those 'might be needed' methods and their tests are just a waste of time. Extending, refactoring will be done when it is actually needed, and at that time we have our unit tests to ensure we don't break any existing code.

Other times to add new unit tests are typically when a bug is discovered. Write a unit test to reproduce the bug, fix the code, and from now on the new unit test will watch your back so the bug won't reappear.

Unit test are also a good place of documentation. The little tests show how the class or method is used.
The code documents itself.

So the benefits are :
* better design
* prove of your code
* safe guard during code maintenance (refactoring, extensions)
* documentation
* ...

== Unit Test frameworks ==
When writing unit tests, one will create a lot of similar code. Since unit tests are nothing more then little programs, several tasks will be repeated, setting up the test environment, create your class, call a method, verify it's result, write out an error message when the test fails, preferably specifying what the wrong outcome was, and what the expected result is.
All these repetitive chores are taken care of by the frame work so the developer can focus on the real code of the test.
This document will use a small but very effective framework for the C++ language. It is called UnitTest++. It's homepage is at : [http://unittest-cpp.sourceforge.net/ UnitTest++].
You can download it directly at this [http://sourceforge.net/projects/unittest-cpp/files/UnitTest%2B%2B/1.4/unittest-cpp-1.4.zip/download link]. At the time of writing the latest version is 1.4.

== Setup our environment ==
Let's create a directory on our PC in which we will cary out our experiments. I will refer to this directory from now on as <TestPit>. For my laptop on which I am writing this article, that will be /home/lieven/Projects/UnitTestArticle. Note that everything we will do, works on linux and on windows!
Download the "unittest-cpp-1.4.zip" file from the link specified above. Extract it in the <TestPit> directory. All the files will end up in the <TestPit>/UnitTest++ directory.

== Build UnitTest++ ==
After the extracted the zip archive we have a directory structure like this :
<pre>
<TestPit>/UnitTest++
|
+docs
|
+src
</pre>
The files in the UnitTest++ directory are of little use for us, since they bring project files for some bizarre Microsoft IDE ;-) .
We will create our own Code::Blocks project to build the UnitTest++ framework.

Why do we need to build something ? Well as said, the framework will do a lot of chores for us, those chores are implemented by code, that code is the framework. We will build to framework into a static library, and for every unit test (or set of unit tests) we create a little (console/shell) program with the test code we wrote, which will link with the static library to obtain a unit test executable, driven by the framework.

We will put our Code::Blocks project file in a nice structured directory tree, therefor let's create a 'Project' subdirectory in the <TestPit>/UnitTest++ directory.

In there create a new file with the name "UnitTest++.cbp".
Give that file the following content :

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="UnitTest++" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option platforms="Windows;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option platforms="Windows;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
<Target title="Debug(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<VirtualTargets>
<Add alias="All" targets="Debug;Release;Debug(linux);Release(linux);" />
</VirtualTargets>
<Unit filename="../src/AssertException.cpp" />
<Unit filename="../src/AssertException.h" />
<Unit filename="../src/CheckMacros.h" />
<Unit filename="../src/Checks.cpp" />
<Unit filename="../src/Checks.h" />
<Unit filename="../src/Config.h" />
<Unit filename="../src/CurrentTest.cpp" />
<Unit filename="../src/CurrentTest.h" />
<Unit filename="../src/DeferredTestReporter.cpp" />
<Unit filename="../src/DeferredTestReporter.h" />
<Unit filename="../src/DeferredTestResult.cpp" />
<Unit filename="../src/DeferredTestResult.h" />
<Unit filename="../src/ExecuteTest.h" />
<Unit filename="../src/MemoryOutStream.cpp" />
<Unit filename="../src/MemoryOutStream.h" />
<Unit filename="../src/Posix/SignalTranslator.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/SignalTranslator.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/ReportAssert.cpp" />
<Unit filename="../src/ReportAssert.h" />
<Unit filename="../src/Test.cpp" />
<Unit filename="../src/Test.h" />
<Unit filename="../src/TestDetails.cpp" />
<Unit filename="../src/TestDetails.h" />
<Unit filename="../src/TestList.cpp" />
<Unit filename="../src/TestList.h" />
<Unit filename="../src/TestMacros.h" />
<Unit filename="../src/TestReporter.cpp" />
<Unit filename="../src/TestReporter.h" />
<Unit filename="../src/TestReporterStdout.cpp" />
<Unit filename="../src/TestReporterStdout.h" />
<Unit filename="../src/TestResults.cpp" />
<Unit filename="../src/TestResults.h" />
<Unit filename="../src/TestRunner.cpp" />
<Unit filename="../src/TestRunner.h" />
<Unit filename="../src/TestSuite.h" />
<Unit filename="../src/TimeConstraint.cpp" />
<Unit filename="../src/TimeConstraint.h" />
<Unit filename="../src/TimeHelpers.h" />
<Unit filename="../src/UnitTest++.h" />
<Unit filename="../src/Win32/TimeHelpers.cpp">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/Win32/TimeHelpers.h">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/XmlTestReporter.cpp" />
<Unit filename="../src/XmlTestReporter.h" />
<Extensions>
<envvars />
<code_completion />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

Some things to note about the content of the project file, the power of Code::Blocks.
* there are 4 targets : Debug/Release for Windows and Debug/Release for linux [yes : 1 project file that allows building on linux and on windows]
* some files are only part of the linux targets, some only for the windows targets

But before we build, let's modify some source files (not really needed, but I prefer to have warning free compilations). These are the changes I carried out :
* ReportAssert.cpp : #include "ReportAssert.h"
* win32/TimeHelpers.cpp : first the m_threadHandle and then the m_startTime in the initializerlist

Next open up this project file in Code::Blocks and build the debug and release target. From now one we will only use the Release target, we go for speed ;-)

The result of the build process will show up in subdirectories of the new 'Deliv' subdirectory of <testPit>/UnitTest++ : '''<testPit>/UnitTest++/Deliv/Release/libUnitTest++.a'''

Alright, we have build the unit test framework in a platform independent way, no silly makefiles, no obscure M$ IDE, good old super Code::Blocks. It is time to write some code so we have something to unit test.

In the first example we will create a simple free function that checks if a given year is a leap year or not.

The business logic is as follows : a year is a leap year when it can be divided by 4, unless it can be divided by 100. But in case it can be divided by 400, then again it is a leap year.

In the next section we will first setup a Code::Blocks project containing both the 'functionality files, and the unit test files. Typically one will package several functionality files into a static library and create a unit test project that tests all the class/functionalities in that library package, also called a component. That is we have a component (whose deliverable is the static library, and we have a unit test project that tests the entire component).

== Our first test project environment ==
Let's create a new directory in our <TestPit> : <TestPit>/LeapYear.
For the simplicity we will put the project file and the source file all together in this directory. Normally we would work in a more structured way, but in a demo article we have some artistic freedom ;-)
Next you can create with the Code::Block's wizard a new console project in the LeapYear directory. Or you can create the following 5 files and give the the contents as specified below. Note that this demo works on linux and on windows, everything is still completely platform independent. Long Live Code::Blocks.

The project file : LeapYear.cbp (the one below already contains the 4 source files, in case you use the wizard you have to add the LeapYear.h/cpp and LeapYearTest.cpp files to the project)

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="LeapYear" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option output="Deliv/Debug/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Debug/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option output="Deliv/Release/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Release/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-O2" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<Compiler>
<Add option="-Wall" />
<Add option="-fexceptions" />
</Compiler>
<Unit filename="LeapYear.cpp" />
<Unit filename="LeapYear.h" />
<Unit filename="LeapYearTest.cpp" />
<Unit filename="main.cpp" />
<Extensions>
<envvars />
<code_completion />
<lib_finder disable_auto="1" />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

The main source file : main.cpp
int main()
{
return 0;
}

The header exporting our powerful function : LeapYear.h

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

#endif // LEAPYEAR_H_INCLUDED

And the implementation of the leap year logic : LeapYear.cpp

#include "LeapYear.h"

And finishing with the source file for the tests : LeapYearTest.cpp (currently) empty

We can already build the project, we have a nice little program that does .... nothing.

Time to move to the next section, a little word about Test Driven Development.

== Test Driven Development ==
This is a practice where new code is only added to make a failing test pass. And one only adds the code needed to make that test pass. Once that is done, a new test is added that will check the next functionality to add.
On this really simple example we will more or less practice some TDD.

So get ready, it's time for LeapYear-Step1.

== LeapYear-Step1 ==
We will turn our main.cpp into the guy in charge to carry out the tests, all we need to do is change the contents of main.cpp into this :

<source lang="cpp">
#include "UnitTest++.h"

int main()
{
return UnitTest::RunAllTests();
}

</source>
And add '''../UnitTest++/src''' to the compiler search directories on the project level of our LeapYear project.
And add '''../UnitTest++/Deliv/Release/libUnitTest++.a''' to the link libraries of the project

Why : well we need to link with the framework and we need to include the UnitTest++ header so we can use it's functionalities.

The line '''UnitTest::RunAllTests()''' will make sure all test encountered in our sources will be carried out.
We don't have any tests yet, nor any functionality, but go ahead build the project and run it.
This is the output :

Success: 0 tests passed
Test time: 0.00 seconds.

Great : success, but no tests yet. Well it's a start.
Time to move forward, and write our first test.

== LeapYear-Step2 ==
Test, test, but there's nothing to test. Yes, absolutely. Let's think of a test, a test that will help us in the design. Now that's a good idea. Suppose I would be the user of the uplifting problem solving leap year checking library/component ... hmmm modesty first : leap year checking '''function'''.
How would I like that function to look.
<source lang="cpp">
bool IsLeapYear(int Year);
</source>
Yes that seems acceptable.
So let's write a test that will call that method.
We do that by adding the following code to LeapYearTest.cpp

<source lang="cpp">
#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

}

</source>
Things to note :
* we include the unit test header
* it is good to put the tests in a nameless namespace (will be explained later on)
* we use the TEST macro, the argument is the name of the test : OurFirstTest
* we use CHECK_EQUAL to check if the expected result (the first argument) matches the computed result (the second argument)

Time to build. Woooooops errors. The test fails completely, it does not even build. Time to add the code needed.
In order to compile the test file, we need to include the LeapYear.h header and have that header export our function.
Our LeapYear header will look like this now (don't forget the include in the test file of our LeapYear.h header, it is not shown here) :

<source lang="cpp">
#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

bool IsLeapYear(int Year);

#endif // LEAPYEAR_H_INCLUDED

</source>

At least now it compiles, but it doesn't link yet. Duh, that because we don't have an implementation yet.
Time to provide the bare minimum of code to make the test pass.
So we change the LeapYear.cpp into :

<source lang="cpp">
#include "LeapYear.h"

bool IsLeapYear(int /*Year*/)
{
return true;
}

</source>
Build it, run it. Yes, we have one working test.
Great. Let's move on.

== LeapYear-Step3 ==
Does anyone have the feeling we are cheating? Well the user does not know how we wrote our code on the inside. So just to be sure the user (we) adds the following test, ending up in :

<source lang="cpp">
#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

TEST(OurSecondTest)
{
const bool Result = IsLeapYear(1973);
CHECK_EQUAL(false, Result);
}

}

</source>
Building is already no issue any more, we can run it. Oh boy, a test is failing.
The framework tell us something like this :
<filename>:<Line>: error: Failure in OurSecondTest: Expected 0 but was 1
FAILURE: 1 out of 2 tests failed (1 failures)
Test time: 0.00 seconds.

So we are informed of the line where the failing test occurs, next to that it tells us what it was expecting and what the actual outcome was. And it presents a resume of the total number of tests, and how many that failed. For you scripting hackers note that FAILURE != SUCCESS.

It seems we should do some more effort and implement some real logic.

== LeapYear-Step4 ==
Let's keep it taking one step at a time. Let's start by implementing the 'divisible by 4' logic. That will already solve our tests.
So our LeapYear.cpp will now look like this :

<source lang="cpp">
#include "LeapYear.h"

namespace
{

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year);
}

</source>
Build, run. All tests pass. Life is great.

But those changing requirements, always the change of the requirements. Years that can be divided by 100 should not be considered as a leap year.

Time for our next step.

== LeapYear-Step5 ==
We add a new test for checking for example the year 1900.

<source lang="cpp">
TEST(DivisableBy100)
{
const bool Result = IsLeapYear(1900);
CHECK_EQUAL(false, Result);
}
</source>

Build and run the tests. It will fail. So time to add the minimum code needed to make this test pass.
This will change our LeapYear.cpp into :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year) && !IsDivisableBy100(Year);
}

</source>

Build and run the tests, yes : success. All 3 tests pass.

It seems life might be great again ...

Wrong, someone just added the following test :

<source lang="cpp">
TEST(DivisableBy400)
{
const bool Result = IsLeapYear(2000);
CHECK_EQUAL(true, Result);
}
</source>

And we once again have a failing test.

Time for the next step.

== LeapYear-Step6 ==
We should add logic to deal with years that can be divided by 400, since those are leap years.
We change our LeapYear.cpp into this :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy400(int Year)
{
return (Year%400) == 0;
}

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
const bool LeapYear = IsDivisableBy400(Year) ||
(IsDivisableBy4(Year) && !IsDivisableBy100(Year));
return LeapYear;
}

</source>

And once again everything works OK.
And it seems all the logical rules have been implemented.
This one is ready for shipping, and till the end of time we have our tests that can be run whenever we want (more on this later, we'd prefer this to be done automatically) to ensure we never break anything.

== Increase the user experience ==
There are a few areas where we can increase the user experience.
When a unit test fails the framework tell use on which line in the the code his happens.
That's excellent.
BUT we see this information in a console/shell windows. So we need to find that window, read the issues, remember them and then go find our test source files and navigate manually to the offending line. This works but is very cumbersome.
We want this to be a no-brainer, and have these steps being carried out for us.

Well, didn't we say life is great, Code::Blocks and UnitTest++ to the rescue. The error/warning output of the framework is in the gcc format. That means Code::Blocks can parse it.
One restriction Code::Blocks can parse it during the 'build process'. But currently the build process stops after the unit test executable is built, and only then we run the test executable (manually).
Solution have Code::Blocks run the test executable as a post-build step. Pre-build and post-build steps are part of the build process !
Important consequence : if you want to debug something, the debugger will only kick off after Code::Blocks was able to carry out a successful build (including the pre/post builds steps). Therefor it is not wise to have the unit test executable being carried out as a post-build step of the 'Debug' target. But as a post-build step of the Release target, our goal is met.

Adjust the target settings for the 'Release' target [Build Options -> select Release target -> Pre/Post-build steps -> Post-build steps text field] and add the following '''$exe_output'''. you can tick the 'Always execute' if you want.

Now build your Release target, and look at what shows up in the 'Build Log' tab in Code::Blocks.
This is my output :
<pre>

-------------- Build: Release in LeapYear ---------------

[ 25.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/LeapYear.cpp -o Deliv/Release/LeapYear.o
[ 50.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/LeapYearTest.cpp -o Deliv/Release/LeapYearTest.o
[ 75.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/main.cpp -o Deliv/Release/main.o
[100.0%] g++ -o Deliv/Release/LeapYear Deliv/Release/LeapYear.o Deliv/Release/LeapYearTest.o Deliv/Release/main.o -s ../UnitTest++/Deliv/Release/libUnitTest++.a
Output size is 23.28 KB
[100.0%] Running target post-build steps
Deliv/Release/LeapYear
Success: 4 tests passed.
Test time: 0.00 seconds.
Process terminated with status 0 (0 minutes, 2 seconds)
0 errors, 0 warnings
Build log saved as:
file:///home/lieven/Projects/UnitTestArticle/LeapYear/LeapYear_build_log.html
</pre>

We see that the unit test has been carried out, automatically.

Let's demonstrate that upon a failed test, Code::Blocks will jump to the offending line.
Change the latest test, the one checking on the year 2000 : change 2000 to 2001.
And build : Code::Blocks will jump to the offending line, and shows an entry in the "Build messages" tab (error: Failure in DivisableBy400: Expected 1 but was 0), just like for a regular compiler warning/error.
In the "Build" tab, we now find something like (red colored since it is an error) :
<pre>

-------------- Build: Release in LeapYear ---------------

[ 50.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/LeapYearTest.cpp -o Deliv/Release/LeapYearTest.o
[100.0%] g++ -o Deliv/Release/LeapYear Deliv/Release/LeapYear.o Deliv/Release/LeapYearTest.o Deliv/Release/main.o -s ../UnitTest++/Deliv/Release/libUnitTest++.a
Output size is 23.28 KB
[100.0%] Running target post-build steps
Deliv/Release/LeapYear
/home/lieven/Projects/UnitTestArticle/LeapYear/LeapYearTest.cpp:28: error: Failure in DivisableBy400: Expected 1 but was 0
FAILURE: 1 out of 4 tests failed (1 failures).
Test time: 0.00 seconds.
Process terminated with status 1 (0 minutes, 1 seconds)
1 errors, 0 warnings
Build log saved as:
file:///home/lieven/Projects/UnitTestArticle/LeapYear/LeapYear_build_log.html
</pre>

Voila, we have increased the user experience.
Time to readjust the final test, 2001 becomes 2000 again ;-)

== Further automation ==
You can create a script that calls Code::Blocks on the command line and passes it our LeapYear.cbp project file, and it will build both targets (Debug/Release) and run the test, since it is a post-build step for the 'Release' target.
Bye bye funky makefiles, welcome Code::Blocks as your build system.

== More to come ==
More examples will be added, showcasing 'fixtures' (setup/teardown), some more CHECK macros of UnitTest++. In case you have some tips/ideas, drop me a PM in the forum.
On the planning is a full conversion of the Money example, but all with gcc and Code::Blocks instead of the crazy Microsoft IDE.

UnitTesting

2010-07-22T09:02:55Z

Killerbot: /* LeapYear-Step3 */

This document is under development by killerbot. Starting from 7 September 2009.

== Introduction ==
This document will describe how unit testing can be combined with the Code::Blocks IDE. It will give a hands-on example on a unit testing framework and how it can be used with Code::Blocks.

== What is Unit Testing ==
Simply put Unit Testing is the discipline and best practice of writing and running little test programs that test little units of code.
Such a unit can be :
* a class
* a free function
* an interface
* ...
There are several unit test frameworks available to help you write, deploy, manage your unit tests. The most famous family is the xUnit framework, and some of it's descendants.

== Why Unit Testing ==
Well we write code that implements some functionality. We need a way to check and prove that the implementation is correct. Therefor we need tests. We need tests on the application level, at the integration level of different components, classes, interfaces. But we also need tests for the smallest building blocks, the units.
We also wans these tests to run very quickly. That way we can run the tests often, manually or automated.
These tests will also be our safeguards during refactoring of the code, extending the code or whatever maintenance tasks we carry out on the code.
These tests will also make us think of how our class, method, ... will be used. Since the test can be seen as a user of our code. Thanks to this, thinking about the tests before implementing the functionality can help us in the design : emergent design.
It will help us to avoid creating big classes, complex functions. We will only write the methods that are really needed, and no methods that we think might (n)ever be useful in the future. We are no good future tellers ! Those 'might be needed' methods and their tests are just a waste of time. Extending, refactoring will be done when it is actually needed, and at that time we have our unit tests to ensure we don't break any existing code.

Other times to add new unit tests are typically when a bug is discovered. Write a unit test to reproduce the bug, fix the code, and from now on the new unit test will watch your back so the bug won't reappear.

Unit test are also a good place of documentation. The little tests show how the class or method is used.
The code documents itself.

So the benefits are :
* better design
* prove of your code
* safe guard during code maintenance (refactoring, extensions)
* documentation
* ...

== Unit Test frameworks ==
When writing unit tests, one will create a lot of similar code. Since unit tests are nothing more then little programs, several tasks will be repeated, setting up the test environment, create your class, call a method, verify it's result, write out an error message when the test fails, preferably specifying what the wrong outcome was, and what the expected result is.
All these repetitive chores are taken care of by the frame work so the developer can focus on the real code of the test.
This document will use a small but very effective framework for the C++ language. It is called UnitTest++. It's homepage is at : [http://unittest-cpp.sourceforge.net/ UnitTest++].
You can download it directly at this [http://sourceforge.net/projects/unittest-cpp/files/UnitTest%2B%2B/1.4/unittest-cpp-1.4.zip/download link]. At the time of writing the latest version is 1.4.

== Setup our environment ==
Let's create a directory on our PC in which we will cary out our experiments. I will refer to this directory from now on as <TestPit>. For my laptop on which I am writing this article, that will be /home/lieven/Projects/UnitTestArticle. Note that everything we will do, works on linux and on windows!
Download the "unittest-cpp-1.4.zip" file from the link specified above. Extract it in the <TestPit> directory. All the files will end up in the <TestPit>/UnitTest++ directory.

== Build UnitTest++ ==
After the extracted the zip archive we have a directory structure like this :
<pre>
<TestPit>/UnitTest++
|
+docs
|
+src
</pre>
The files in the UnitTest++ directory are of little use for us, since they bring project files for some bizarre Microsoft IDE ;-) .
We will create our own Code::Blocks project to build the UnitTest++ framework.

Why do we need to build something ? Well as said, the framework will do a lot of chores for us, those chores are implemented by code, that code is the framework. We will build to framework into a static library, and for every unit test (or set of unit tests) we create a little (console/shell) program with the test code we wrote, which will link with the static library to obtain a unit test executable, driven by the framework.

We will put our Code::Blocks project file in a nice structured directory tree, therefor let's create a 'Project' subdirectory in the <TestPit>/UnitTest++ directory.

In there create a new file with the name "UnitTest++.cbp".
Give that file the following content :

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="UnitTest++" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option platforms="Windows;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option platforms="Windows;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
<Target title="Debug(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<VirtualTargets>
<Add alias="All" targets="Debug;Release;Debug(linux);Release(linux);" />
</VirtualTargets>
<Unit filename="../src/AssertException.cpp" />
<Unit filename="../src/AssertException.h" />
<Unit filename="../src/CheckMacros.h" />
<Unit filename="../src/Checks.cpp" />
<Unit filename="../src/Checks.h" />
<Unit filename="../src/Config.h" />
<Unit filename="../src/CurrentTest.cpp" />
<Unit filename="../src/CurrentTest.h" />
<Unit filename="../src/DeferredTestReporter.cpp" />
<Unit filename="../src/DeferredTestReporter.h" />
<Unit filename="../src/DeferredTestResult.cpp" />
<Unit filename="../src/DeferredTestResult.h" />
<Unit filename="../src/ExecuteTest.h" />
<Unit filename="../src/MemoryOutStream.cpp" />
<Unit filename="../src/MemoryOutStream.h" />
<Unit filename="../src/Posix/SignalTranslator.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/SignalTranslator.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/ReportAssert.cpp" />
<Unit filename="../src/ReportAssert.h" />
<Unit filename="../src/Test.cpp" />
<Unit filename="../src/Test.h" />
<Unit filename="../src/TestDetails.cpp" />
<Unit filename="../src/TestDetails.h" />
<Unit filename="../src/TestList.cpp" />
<Unit filename="../src/TestList.h" />
<Unit filename="../src/TestMacros.h" />
<Unit filename="../src/TestReporter.cpp" />
<Unit filename="../src/TestReporter.h" />
<Unit filename="../src/TestReporterStdout.cpp" />
<Unit filename="../src/TestReporterStdout.h" />
<Unit filename="../src/TestResults.cpp" />
<Unit filename="../src/TestResults.h" />
<Unit filename="../src/TestRunner.cpp" />
<Unit filename="../src/TestRunner.h" />
<Unit filename="../src/TestSuite.h" />
<Unit filename="../src/TimeConstraint.cpp" />
<Unit filename="../src/TimeConstraint.h" />
<Unit filename="../src/TimeHelpers.h" />
<Unit filename="../src/UnitTest++.h" />
<Unit filename="../src/Win32/TimeHelpers.cpp">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/Win32/TimeHelpers.h">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/XmlTestReporter.cpp" />
<Unit filename="../src/XmlTestReporter.h" />
<Extensions>
<envvars />
<code_completion />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

Some things to note about the content of the project file, the power of Code::Blocks.
* there are 4 targets : Debug/Release for Windows and Debug/Release for linux [yes : 1 project file that allows building on linux and on windows]
* some files are only part of the linux targets, some only for the windows targets

But before we build, let's modify some source files (not really needed, but I prefer to have warning free compilations). These are the changes I carried out :
* ReportAssert.cpp : #include "ReportAssert.h"
* win32/TimeHelpers.cpp : first the m_threadHandle and then the m_startTime in the initializerlist

Next open up this project file in Code::Blocks and build the debug and release target. From now one we will only use the Release target, we go for speed ;-)

The result of the build process will show up in subdirectories of the new 'Deliv' subdirectory of <testPit>/UnitTest++ : '''<testPit>/UnitTest++/Deliv/Release/libUnitTest++.a'''

Alright, we have build the unit test framework in a platform independent way, no silly makefiles, no obscure M$ IDE, good old super Code::Blocks. It is time to write some code so we have something to unit test.

In the first example we will create a simple free function that checks if a given year is a leap year or not.

The business logic is as follows : a year is a leap year when it can be divided by 4, unless it can be divided by 100. But in case it can be divided by 400, then again it is a leap year.

In the next section we will first setup a Code::Blocks project containing both the 'functionality files, and the unit test files. Typically one will package several functionality files into a static library and create a unit test project that tests all the class/functionalities in that library package, also called a component. That is we have a component (whose deliverable is the static library, and we have a unit test project that tests the entire component).

== Our first test project environment ==
Let's create a new directory in our <TestPit> : <TestPit>/LeapYear.
For the simplicity we will put the project file and the source file all together in this directory. Normally we would work in a more structured way, but in a demo article we have some artistic freedom ;-)
Next you can create with the Code::Block's wizard a new console project in the LeapYear directory. Or you can create the following 5 files and give the the contents as specified below. Note that this demo works on linux and on windows, everything is still completely platform independent. Long Live Code::Blocks.

The project file : LeapYear.cbp (the one below already contains the 4 source files, in case you use the wizard you have to add the LeapYear.h/cpp and LeapYearTest.cpp files to the project)

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="LeapYear" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option output="Deliv/Debug/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Debug/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option output="Deliv/Release/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Release/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-O2" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<Compiler>
<Add option="-Wall" />
<Add option="-fexceptions" />
</Compiler>
<Unit filename="LeapYear.cpp" />
<Unit filename="LeapYear.h" />
<Unit filename="LeapYearTest.cpp" />
<Unit filename="main.cpp" />
<Extensions>
<envvars />
<code_completion />
<lib_finder disable_auto="1" />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

The main source file : main.cpp
int main()
{
return 0;
}

The header exporting our powerful function : LeapYear.h

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

#endif // LEAPYEAR_H_INCLUDED

And the implementation of the leap year logic : LeapYear.cpp

#include "LeapYear.h"

And finishing with the source file for the tests : LeapYearTest.cpp (currently) empty

We can already build the project, we have a nice little program that does .... nothing.

Time to move to the next section, a little word about Test Driven Development.

== Test Driven Development ==
This is a practice where new code is only added to make a failing test pass. And one only adds the code needed to make that test pass. Once that is done, a new test is added that will check the next functionality to add.
On this really simple example we will more or less practice some TDD.

So get ready, it's time for LeapYear-Step1.

== LeapYear-Step1 ==
We will turn our main.cpp into the guy in charge to carry out the tests, all we need to do is change the contents of main.cpp into this :

<source lang="cpp">
#include "UnitTest++.h"

int main()
{
return UnitTest::RunAllTests();
}

</source>
And add '''../UnitTest++/src''' to the compiler search directories on the project level of our LeapYear project.
And add '''../UnitTest++/Deliv/Release/libUnitTest++.a''' to the link libraries of the project

Why : well we need to link with the framework and we need to include the UnitTest++ header so we can use it's functionalities.

The line '''UnitTest::RunAllTests()''' will make sure all test encountered in our sources will be carried out.
We don't have any tests yet, nor any functionality, but go ahead build the project and run it.
This is the output :

Success: 0 tests passed
Test time: 0.00 seconds.

Great : success, but no tests yet. Well it's a start.
Time to move forward, and write our first test.

== LeapYear-Step2 ==
Test, test, but there's nothing to test. Yes, absolutely. Let's think of a test, a test that will help us in the design. Now that's a good idea. Suppose I would be the user of the uplifting problem solving leap year checking library/component ... hmmm modesty first : leap year checking '''function'''.
How would I like that function to look.
<source lang="cpp">
bool IsLeapYear(int Year);
</source>
Yes that seems acceptable.
So let's write a test that will call that method.
We do that by adding the following code to LeapYearTest.cpp

<source lang="cpp">
#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

}

</source>
Things to note :
* we include the unit test header
* it is good to put the tests in a nameless namespace (will be explained later on)
* we use the TEST macro, the argument is the name of the test : OurFirstTest
* we use CHECK_EQUAL to check if the expected result (the first argument) matches the computed result (the second argument)

Time to build. Woooooops errors. The test fails completely, it does not even build. Time to add the code needed.
In order to compile the test file, we need to include the LeapYear.h header and have that header export our function.
Our LeapYear header will look like this now (don't forget the include in the test file of our LeapYear.h header, it is not shown here) :

<source lang="cpp">
#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

bool IsLeapYear(int Year);

#endif // LEAPYEAR_H_INCLUDED

</source>

At least now it compiles, but it doesn't link yet. Duh, that because we don't have an implementation yet.
Time to provide the bare minimum of code to make the test pass.
So we change the LeapYear.cpp into :

<source lang="cpp">
#include "LeapYear.h"

bool IsLeapYear(int /*Year*/)
{
return true;
}

</source>
Build it, run it. Yes, we have one working test.
Great. Let's move on.

== LeapYear-Step3 ==
Does anyone have the feeling we are cheating? Well the user does not know how we wrote our code on the inside. So just to be sure the user (we) adds the following test, ending up in :

<source lang="cpp">
#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

TEST(OurSecondTest)
{
const bool Result = IsLeapYear(1973);
CHECK_EQUAL(false, Result);
}

}

</source>
Building is already no issue any more, we can run it. Oh boy, a test is failing.
The framework tell us something like this :
<filename>:<Line>: error: Failure in OurSecondTest: Expected 0 but was 1
FAILURE: 1 out of 2 tests failed (1 failures)
Test time: 0.00 seconds.

So we are informed of the line where the failing test occurs, next to that it tells us what it was expecting and what the actual outcome was. And it presents a resume of the total number of tests, and how many that failed. For you scripting hackers note that FAILURE != SUCCESS.

It seems we should do some more effort and implement some real logic.

== LeapYear-Step4 ==
Let's keep it taking one step at a time. Let's start by implementing the 'divisible by 4' logic. That will already solve our tests.
So our LeapYear.cpp will now look like this :

<source lang="cpp">
#include "LeapYear.h"

namespace
{

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year);
}

</source>
Build, run. All tests pass. Life is great.

But those changing requirements, always the change of the requirements. Years that can be divided by 100 should not be considered as a leap year.

Time for our next step.

== LeapYear-Step5 ==
We add a new test for checking for example the year 1900.

<source lang="cpp">
TEST(DivisableBy100)
{
const bool Result = IsLeapYear(1900);
CHECK_EQUAL(false, Result);
}
</source>

Build and run the tests. It will fail. So time to add the minimum code needed to make this test pass.
This will change our LeapYear.cpp into :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year) && !IsDivisableBy100(Year);
}

</source>

Build and run the tests, yes : success. All 3 tests pass.

It seems life might be great again ...

Wrong, someone just added the following test :

<source lang="cpp">
TEST(DivisableBy400)
{
const bool Result = IsLeapYear(2000);
CHECK_EQUAL(true, Result);
}
</source>

And we once again have a failing test.

Time for the next step.

== LeapYear-Step6 ==
We should add logic to deal with years that can be divided by 400, since those are leap years.
We change our LeapYear.cpp into this :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy400(int Year)
{
return (Year%400) == 0;
}

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
const bool LeapYear = IsDivisableBy400(Year) ||
(IsDivisableBy4(Year) && !IsDivisableBy100(Year));
return LeapYear;
}

</source>

And once again everything works OK.
And it seems all the logical rules have been implemented.
This one is ready for shipping, and till the end of time we have our tests that can be run whenever we want (more on this later, we'd prefer this to be done automatically) to ensure we never break anything.

== Increase the user experience ==
There are a few areas where we can increase the user experience.
When a unit test fails the framework tell use on which line in the the code his happens.
That's excellent.
BUT we see this information in a console/shell windows. So we need to find that window, read the issues, remember them and then go find our test source files and navigate manually to the offending line. This works but is very cumbersome.
We want this to be a no-brainer, and have these steps being carried out for us.

Well, didn't we say life is great, Code::Blocks and UnitTest++ to the rescue. The error/warning output of the framework is in the gcc format. That means Code::Blocks can parse it.
One restriction Code::Blocks can parse it during the 'build process'. But currently the build process stops after the unit test executable is built, and only then we run the test executable (manually).
Solution have Code::Blocks run the test executable as a post-build step. Pre-build and post-build steps are part of the build process !
Important consequence : if you want to debug something, the debugger will only kick off after Code::Blocks was able to carry out a successful build (including the pre/post builds steps). Therefor it is not wise to have the unit test executable being carried out as a post-build step of the 'Debug' target. But as a post-build step of the Release target, our goal is met.

Adjust the target settings for the 'Release' target [Build Options -> select Release target -> Pre/Post-build steps -> Post-build steps text field] and add the following '''$exe_output'''. you can tick the 'Always execute' if you want.

Now build your Release target, and look at what shows up in the 'Build Log' tab in Code::Blocks.
This is my output :
<pre>

-------------- Build: Release in LeapYear ---------------

[ 25.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/LeapYear.cpp -o Deliv/Release/LeapYear.o
[ 50.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/LeapYearTest.cpp -o Deliv/Release/LeapYearTest.o
[ 75.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/main.cpp -o Deliv/Release/main.o
[100.0%] g++ -o Deliv/Release/LeapYear Deliv/Release/LeapYear.o Deliv/Release/LeapYearTest.o Deliv/Release/main.o -s ../UnitTest++/Deliv/Release/libUnitTest++.a
Output size is 23.28 KB
[100.0%] Running target post-build steps
Deliv/Release/LeapYear
Success: 4 tests passed.
Test time: 0.00 seconds.
Process terminated with status 0 (0 minutes, 2 seconds)
0 errors, 0 warnings
Build log saved as:
file:///home/lieven/Projects/UnitTestArticle/LeapYear/LeapYear_build_log.html
</pre>

We see that the unit test has been carried out, automatically.

Let's demonstrate that upon a failed test, Code::Blocks will jump to the offending line.
Change the latest test, the one checking on the year 2000 : change 2000 to 2001.
And build : Code::Blocks will jump to the offending line, and shows an entry in the "Build messages" tab (error: Failure in DivisableBy400: Expected 1 but was 0), just like for a regular compiler warning/error.
In the "Build" tab, we now find something like (red colored since it is an error) :
<pre>

-------------- Build: Release in LeapYear ---------------

[ 50.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/LeapYearTest.cpp -o Deliv/Release/LeapYearTest.o
[100.0%] g++ -o Deliv/Release/LeapYear Deliv/Release/LeapYear.o Deliv/Release/LeapYearTest.o Deliv/Release/main.o -s ../UnitTest++/Deliv/Release/libUnitTest++.a
Output size is 23.28 KB
[100.0%] Running target post-build steps
Deliv/Release/LeapYear
/home/lieven/Projects/UnitTestArticle/LeapYear/LeapYearTest.cpp:28: error: Failure in DivisableBy400: Expected 1 but was 0
FAILURE: 1 out of 4 tests failed (1 failures).
Test time: 0.00 seconds.
Process terminated with status 1 (0 minutes, 1 seconds)
1 errors, 0 warnings
Build log saved as:
file:///home/lieven/Projects/UnitTestArticle/LeapYear/LeapYear_build_log.html
</pre>

Voila, we have increased the user experience.
Time to readjust the final test, 2001 becomes 2000 again ;-)

== Further automation ==
You can create a script that calls Code::Blocks on the command line and passes it our LeapYear.cbp project file, and it will build both targets (Debug/Release) and run the test, since it is a post-build step for the 'Release' target.
Bye bye funky makefiles, welcome Code::Blocks as your build system.

== More to come ==
More examples will be added, showcasing 'fixtures' (setup/teardown), some more CHECK macros of UnitTest++. In case you have some tips/ideas, drop me a PM in the forum.
On the planning is a full conversion of the Money example, but all with gcc and Code::Blocks instead of the crazy Microsoft IDE.

UnitTesting

2010-07-22T09:02:08Z

Killerbot: /* Increase the user experience */

This document is under development by killerbot. Starting from 7 September 2009.

== Introduction ==
This document will describe how unit testing can be combined with the Code::Blocks IDE. It will give a hands-on example on a unit testing framework and how it can be used with Code::Blocks.

== What is Unit Testing ==
Simply put Unit Testing is the discipline and best practice of writing and running little test programs that test little units of code.
Such a unit can be :
* a class
* a free function
* an interface
* ...
There are several unit test frameworks available to help you write, deploy, manage your unit tests. The most famous family is the xUnit framework, and some of it's descendants.

== Why Unit Testing ==
Well we write code that implements some functionality. We need a way to check and prove that the implementation is correct. Therefor we need tests. We need tests on the application level, at the integration level of different components, classes, interfaces. But we also need tests for the smallest building blocks, the units.
We also wans these tests to run very quickly. That way we can run the tests often, manually or automated.
These tests will also be our safeguards during refactoring of the code, extending the code or whatever maintenance tasks we carry out on the code.
These tests will also make us think of how our class, method, ... will be used. Since the test can be seen as a user of our code. Thanks to this, thinking about the tests before implementing the functionality can help us in the design : emergent design.
It will help us to avoid creating big classes, complex functions. We will only write the methods that are really needed, and no methods that we think might (n)ever be useful in the future. We are no good future tellers ! Those 'might be needed' methods and their tests are just a waste of time. Extending, refactoring will be done when it is actually needed, and at that time we have our unit tests to ensure we don't break any existing code.

Other times to add new unit tests are typically when a bug is discovered. Write a unit test to reproduce the bug, fix the code, and from now on the new unit test will watch your back so the bug won't reappear.

Unit test are also a good place of documentation. The little tests show how the class or method is used.
The code documents itself.

So the benefits are :
* better design
* prove of your code
* safe guard during code maintenance (refactoring, extensions)
* documentation
* ...

== Unit Test frameworks ==
When writing unit tests, one will create a lot of similar code. Since unit tests are nothing more then little programs, several tasks will be repeated, setting up the test environment, create your class, call a method, verify it's result, write out an error message when the test fails, preferably specifying what the wrong outcome was, and what the expected result is.
All these repetitive chores are taken care of by the frame work so the developer can focus on the real code of the test.
This document will use a small but very effective framework for the C++ language. It is called UnitTest++. It's homepage is at : [http://unittest-cpp.sourceforge.net/ UnitTest++].
You can download it directly at this [http://sourceforge.net/projects/unittest-cpp/files/UnitTest%2B%2B/1.4/unittest-cpp-1.4.zip/download link]. At the time of writing the latest version is 1.4.

== Setup our environment ==
Let's create a directory on our PC in which we will cary out our experiments. I will refer to this directory from now on as <TestPit>. For my laptop on which I am writing this article, that will be /home/lieven/Projects/UnitTestArticle. Note that everything we will do, works on linux and on windows!
Download the "unittest-cpp-1.4.zip" file from the link specified above. Extract it in the <TestPit> directory. All the files will end up in the <TestPit>/UnitTest++ directory.

== Build UnitTest++ ==
After the extracted the zip archive we have a directory structure like this :
<pre>
<TestPit>/UnitTest++
|
+docs
|
+src
</pre>
The files in the UnitTest++ directory are of little use for us, since they bring project files for some bizarre Microsoft IDE ;-) .
We will create our own Code::Blocks project to build the UnitTest++ framework.

Why do we need to build something ? Well as said, the framework will do a lot of chores for us, those chores are implemented by code, that code is the framework. We will build to framework into a static library, and for every unit test (or set of unit tests) we create a little (console/shell) program with the test code we wrote, which will link with the static library to obtain a unit test executable, driven by the framework.

We will put our Code::Blocks project file in a nice structured directory tree, therefor let's create a 'Project' subdirectory in the <TestPit>/UnitTest++ directory.

In there create a new file with the name "UnitTest++.cbp".
Give that file the following content :

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="UnitTest++" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option platforms="Windows;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option platforms="Windows;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
<Target title="Debug(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<VirtualTargets>
<Add alias="All" targets="Debug;Release;Debug(linux);Release(linux);" />
</VirtualTargets>
<Unit filename="../src/AssertException.cpp" />
<Unit filename="../src/AssertException.h" />
<Unit filename="../src/CheckMacros.h" />
<Unit filename="../src/Checks.cpp" />
<Unit filename="../src/Checks.h" />
<Unit filename="../src/Config.h" />
<Unit filename="../src/CurrentTest.cpp" />
<Unit filename="../src/CurrentTest.h" />
<Unit filename="../src/DeferredTestReporter.cpp" />
<Unit filename="../src/DeferredTestReporter.h" />
<Unit filename="../src/DeferredTestResult.cpp" />
<Unit filename="../src/DeferredTestResult.h" />
<Unit filename="../src/ExecuteTest.h" />
<Unit filename="../src/MemoryOutStream.cpp" />
<Unit filename="../src/MemoryOutStream.h" />
<Unit filename="../src/Posix/SignalTranslator.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/SignalTranslator.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/ReportAssert.cpp" />
<Unit filename="../src/ReportAssert.h" />
<Unit filename="../src/Test.cpp" />
<Unit filename="../src/Test.h" />
<Unit filename="../src/TestDetails.cpp" />
<Unit filename="../src/TestDetails.h" />
<Unit filename="../src/TestList.cpp" />
<Unit filename="../src/TestList.h" />
<Unit filename="../src/TestMacros.h" />
<Unit filename="../src/TestReporter.cpp" />
<Unit filename="../src/TestReporter.h" />
<Unit filename="../src/TestReporterStdout.cpp" />
<Unit filename="../src/TestReporterStdout.h" />
<Unit filename="../src/TestResults.cpp" />
<Unit filename="../src/TestResults.h" />
<Unit filename="../src/TestRunner.cpp" />
<Unit filename="../src/TestRunner.h" />
<Unit filename="../src/TestSuite.h" />
<Unit filename="../src/TimeConstraint.cpp" />
<Unit filename="../src/TimeConstraint.h" />
<Unit filename="../src/TimeHelpers.h" />
<Unit filename="../src/UnitTest++.h" />
<Unit filename="../src/Win32/TimeHelpers.cpp">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/Win32/TimeHelpers.h">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/XmlTestReporter.cpp" />
<Unit filename="../src/XmlTestReporter.h" />
<Extensions>
<envvars />
<code_completion />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

Some things to note about the content of the project file, the power of Code::Blocks.
* there are 4 targets : Debug/Release for Windows and Debug/Release for linux [yes : 1 project file that allows building on linux and on windows]
* some files are only part of the linux targets, some only for the windows targets

But before we build, let's modify some source files (not really needed, but I prefer to have warning free compilations). These are the changes I carried out :
* ReportAssert.cpp : #include "ReportAssert.h"
* win32/TimeHelpers.cpp : first the m_threadHandle and then the m_startTime in the initializerlist

Next open up this project file in Code::Blocks and build the debug and release target. From now one we will only use the Release target, we go for speed ;-)

The result of the build process will show up in subdirectories of the new 'Deliv' subdirectory of <testPit>/UnitTest++ : '''<testPit>/UnitTest++/Deliv/Release/libUnitTest++.a'''

Alright, we have build the unit test framework in a platform independent way, no silly makefiles, no obscure M$ IDE, good old super Code::Blocks. It is time to write some code so we have something to unit test.

In the first example we will create a simple free function that checks if a given year is a leap year or not.

The business logic is as follows : a year is a leap year when it can be divided by 4, unless it can be divided by 100. But in case it can be divided by 400, then again it is a leap year.

In the next section we will first setup a Code::Blocks project containing both the 'functionality files, and the unit test files. Typically one will package several functionality files into a static library and create a unit test project that tests all the class/functionalities in that library package, also called a component. That is we have a component (whose deliverable is the static library, and we have a unit test project that tests the entire component).

== Our first test project environment ==
Let's create a new directory in our <TestPit> : <TestPit>/LeapYear.
For the simplicity we will put the project file and the source file all together in this directory. Normally we would work in a more structured way, but in a demo article we have some artistic freedom ;-)
Next you can create with the Code::Block's wizard a new console project in the LeapYear directory. Or you can create the following 5 files and give the the contents as specified below. Note that this demo works on linux and on windows, everything is still completely platform independent. Long Live Code::Blocks.

The project file : LeapYear.cbp (the one below already contains the 4 source files, in case you use the wizard you have to add the LeapYear.h/cpp and LeapYearTest.cpp files to the project)

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="LeapYear" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option output="Deliv/Debug/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Debug/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option output="Deliv/Release/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Release/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-O2" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<Compiler>
<Add option="-Wall" />
<Add option="-fexceptions" />
</Compiler>
<Unit filename="LeapYear.cpp" />
<Unit filename="LeapYear.h" />
<Unit filename="LeapYearTest.cpp" />
<Unit filename="main.cpp" />
<Extensions>
<envvars />
<code_completion />
<lib_finder disable_auto="1" />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

The main source file : main.cpp
int main()
{
return 0;
}

The header exporting our powerful function : LeapYear.h

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

#endif // LEAPYEAR_H_INCLUDED

And the implementation of the leap year logic : LeapYear.cpp

#include "LeapYear.h"

And finishing with the source file for the tests : LeapYearTest.cpp (currently) empty

We can already build the project, we have a nice little program that does .... nothing.

Time to move to the next section, a little word about Test Driven Development.

== Test Driven Development ==
This is a practice where new code is only added to make a failing test pass. And one only adds the code needed to make that test pass. Once that is done, a new test is added that will check the next functionality to add.
On this really simple example we will more or less practice some TDD.

So get ready, it's time for LeapYear-Step1.

== LeapYear-Step1 ==
We will turn our main.cpp into the guy in charge to carry out the tests, all we need to do is change the contents of main.cpp into this :

<source lang="cpp">
#include "UnitTest++.h"

int main()
{
return UnitTest::RunAllTests();
}

</source>
And add '''../UnitTest++/src''' to the compiler search directories on the project level of our LeapYear project.
And add '''../UnitTest++/Deliv/Release/libUnitTest++.a''' to the link libraries of the project

Why : well we need to link with the framework and we need to include the UnitTest++ header so we can use it's functionalities.

The line '''UnitTest::RunAllTests()''' will make sure all test encountered in our sources will be carried out.
We don't have any tests yet, nor any functionality, but go ahead build the project and run it.
This is the output :

Success: 0 tests passed
Test time: 0.00 seconds.

Great : success, but no tests yet. Well it's a start.
Time to move forward, and write our first test.

== LeapYear-Step2 ==
Test, test, but there's nothing to test. Yes, absolutely. Let's think of a test, a test that will help us in the design. Now that's a good idea. Suppose I would be the user of the uplifting problem solving leap year checking library/component ... hmmm modesty first : leap year checking '''function'''.
How would I like that function to look.
<source lang="cpp">
bool IsLeapYear(int Year);
</source>
Yes that seems acceptable.
So let's write a test that will call that method.
We do that by adding the following code to LeapYearTest.cpp

<source lang="cpp">
#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

}

</source>
Things to note :
* we include the unit test header
* it is good to put the tests in a nameless namespace (will be explained later on)
* we use the TEST macro, the argument is the name of the test : OurFirstTest
* we use CHECK_EQUAL to check if the expected result (the first argument) matches the computed result (the second argument)

Time to build. Woooooops errors. The test fails completely, it does not even build. Time to add the code needed.
In order to compile the test file, we need to include the LeapYear.h header and have that header export our function.
Our LeapYear header will look like this now (don't forget the include in the test file of our LeapYear.h header, it is not shown here) :

<source lang="cpp">
#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

bool IsLeapYear(int Year);

#endif // LEAPYEAR_H_INCLUDED

</source>

At least now it compiles, but it doesn't link yet. Duh, that because we don't have an implementation yet.
Time to provide the bare minimum of code to make the test pass.
So we change the LeapYear.cpp into :

<source lang="cpp">
#include "LeapYear.h"

bool IsLeapYear(int /*Year*/)
{
return true;
}

</source>
Build it, run it. Yes, we have one working test.
Great. Let's move on.

== LeapYear-Step3 ==
Anyone having the feeling we are cheating. Well the user does not know how we wrote our code on the inside. So just to be sure the user (we) adds the following test, ending up in :

<source lang="cpp">
#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

TEST(OurSecondTest)
{
const bool Result = IsLeapYear(1973);
CHECK_EQUAL(false, Result);
}

}

</source>
Building is already no issue any more, we can run it. Oh boy, a test is failing.
The framework tell us something like this :
<filename>:<Line>: error: Failure in OurSecondTest: Expected 0 but was 1
FAILURE: 1 out of 2 tests failed (1 failures)
Test time: 0.00 seconds.

So we are informed of the line where the failing test occurs, next to that it tells us what it was expecting and what the actual outcome was. And it presents a resume of the total number of tests, and how many that failed. For you scripting hackers note that FAILURE != SUCCESS.

It seems we should do some more effort and implement some real logic.

== LeapYear-Step4 ==
Let's keep it taking one step at a time. Let's start by implementing the 'divisible by 4' logic. That will already solve our tests.
So our LeapYear.cpp will now look like this :

<source lang="cpp">
#include "LeapYear.h"

namespace
{

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year);
}

</source>
Build, run. All tests pass. Life is great.

But those changing requirements, always the change of the requirements. Years that can be divided by 100 should not be considered as a leap year.

Time for our next step.

== LeapYear-Step5 ==
We add a new test for checking for example the year 1900.

<source lang="cpp">
TEST(DivisableBy100)
{
const bool Result = IsLeapYear(1900);
CHECK_EQUAL(false, Result);
}
</source>

Build and run the tests. It will fail. So time to add the minimum code needed to make this test pass.
This will change our LeapYear.cpp into :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year) && !IsDivisableBy100(Year);
}

</source>

Build and run the tests, yes : success. All 3 tests pass.

It seems life might be great again ...

Wrong, someone just added the following test :

<source lang="cpp">
TEST(DivisableBy400)
{
const bool Result = IsLeapYear(2000);
CHECK_EQUAL(true, Result);
}
</source>

And we once again have a failing test.

Time for the next step.

== LeapYear-Step6 ==
We should add logic to deal with years that can be divided by 400, since those are leap years.
We change our LeapYear.cpp into this :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy400(int Year)
{
return (Year%400) == 0;
}

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
const bool LeapYear = IsDivisableBy400(Year) ||
(IsDivisableBy4(Year) && !IsDivisableBy100(Year));
return LeapYear;
}

</source>

And once again everything works OK.
And it seems all the logical rules have been implemented.
This one is ready for shipping, and till the end of time we have our tests that can be run whenever we want (more on this later, we'd prefer this to be done automatically) to ensure we never break anything.

== Increase the user experience ==
There are a few areas where we can increase the user experience.
When a unit test fails the framework tell use on which line in the the code his happens.
That's excellent.
BUT we see this information in a console/shell windows. So we need to find that window, read the issues, remember them and then go find our test source files and navigate manually to the offending line. This works but is very cumbersome.
We want this to be a no-brainer, and have these steps being carried out for us.

Well, didn't we say life is great, Code::Blocks and UnitTest++ to the rescue. The error/warning output of the framework is in the gcc format. That means Code::Blocks can parse it.
One restriction Code::Blocks can parse it during the 'build process'. But currently the build process stops after the unit test executable is built, and only then we run the test executable (manually).
Solution have Code::Blocks run the test executable as a post-build step. Pre-build and post-build steps are part of the build process !
Important consequence : if you want to debug something, the debugger will only kick off after Code::Blocks was able to carry out a successful build (including the pre/post builds steps). Therefor it is not wise to have the unit test executable being carried out as a post-build step of the 'Debug' target. But as a post-build step of the Release target, our goal is met.

Adjust the target settings for the 'Release' target [Build Options -> select Release target -> Pre/Post-build steps -> Post-build steps text field] and add the following '''$exe_output'''. you can tick the 'Always execute' if you want.

Now build your Release target, and look at what shows up in the 'Build Log' tab in Code::Blocks.
This is my output :
<pre>

-------------- Build: Release in LeapYear ---------------

[ 25.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/LeapYear.cpp -o Deliv/Release/LeapYear.o
[ 50.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/LeapYearTest.cpp -o Deliv/Release/LeapYearTest.o
[ 75.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/main.cpp -o Deliv/Release/main.o
[100.0%] g++ -o Deliv/Release/LeapYear Deliv/Release/LeapYear.o Deliv/Release/LeapYearTest.o Deliv/Release/main.o -s ../UnitTest++/Deliv/Release/libUnitTest++.a
Output size is 23.28 KB
[100.0%] Running target post-build steps
Deliv/Release/LeapYear
Success: 4 tests passed.
Test time: 0.00 seconds.
Process terminated with status 0 (0 minutes, 2 seconds)
0 errors, 0 warnings
Build log saved as:
file:///home/lieven/Projects/UnitTestArticle/LeapYear/LeapYear_build_log.html
</pre>

We see that the unit test has been carried out, automatically.

Let's demonstrate that upon a failed test, Code::Blocks will jump to the offending line.
Change the latest test, the one checking on the year 2000 : change 2000 to 2001.
And build : Code::Blocks will jump to the offending line, and shows an entry in the "Build messages" tab (error: Failure in DivisableBy400: Expected 1 but was 0), just like for a regular compiler warning/error.
In the "Build" tab, we now find something like (red colored since it is an error) :
<pre>

-------------- Build: Release in LeapYear ---------------

[ 50.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/LeapYearTest.cpp -o Deliv/Release/LeapYearTest.o
[100.0%] g++ -o Deliv/Release/LeapYear Deliv/Release/LeapYear.o Deliv/Release/LeapYearTest.o Deliv/Release/main.o -s ../UnitTest++/Deliv/Release/libUnitTest++.a
Output size is 23.28 KB
[100.0%] Running target post-build steps
Deliv/Release/LeapYear
/home/lieven/Projects/UnitTestArticle/LeapYear/LeapYearTest.cpp:28: error: Failure in DivisableBy400: Expected 1 but was 0
FAILURE: 1 out of 4 tests failed (1 failures).
Test time: 0.00 seconds.
Process terminated with status 1 (0 minutes, 1 seconds)
1 errors, 0 warnings
Build log saved as:
file:///home/lieven/Projects/UnitTestArticle/LeapYear/LeapYear_build_log.html
</pre>

Voila, we have increased the user experience.
Time to readjust the final test, 2001 becomes 2000 again ;-)

== Further automation ==
You can create a script that calls Code::Blocks on the command line and passes it our LeapYear.cbp project file, and it will build both targets (Debug/Release) and run the test, since it is a post-build step for the 'Release' target.
Bye bye funky makefiles, welcome Code::Blocks as your build system.

== More to come ==
More examples will be added, showcasing 'fixtures' (setup/teardown), some more CHECK macros of UnitTest++. In case you have some tips/ideas, drop me a PM in the forum.
On the planning is a full conversion of the Money example, but all with gcc and Code::Blocks instead of the crazy Microsoft IDE.

UnitTesting

2009-09-09T19:53:34Z

Killerbot: /* Increase the user experience */

This document is under development by killerbot. Starting from 7 September 2009.

== Introduction ==
This document will describe how unit testing can be combined with the Code::Blocks IDE. It will give a hands-on example on a unit testing framework and how it can be used with Code::Blocks.

== What is Unit Testing ==
Simply put Unit Testing is the discipline and best practice of writing and running little test programs that test little units of code.
Such a unit can be :
* a class
* a free function
* an interface
* ...
There are several unit test frameworks available to help you write, deploy, manage your unit tests. The most famous family is the xUnit framework, and some of it's descendants.

== Why Unit Testing ==
Well we write code that implements some functionality. We need a way to check and prove that the implementation is correct. Therefor we need tests. We need tests on the application level, at the integration level of different components, classes, interfaces. But we also need tests for the smallest building blocks, the units.
We also wans these tests to run very quickly. That way we can run the tests often, manually or automated.
These tests will also be our safeguards during refactoring of the code, extending the code or whatever maintenance tasks we carry out on the code.
These tests will also make us think of how our class, method, ... will be used. Since the test can be seen as a user of our code. Thanks to this, thinking about the tests before implementing the functionality can help us in the design : emergent design.
It will help us to avoid creating big classes, complex functions. We will only write the methods that are really needed, and no methods that we think might (n)ever be useful in the future. We are no good future tellers ! Those 'might be needed' methods and their tests are just a waste of time. Extending, refactoring will be done when it is actually needed, and at that time we have our unit tests to ensure we don't break any existing code.

Other times to add new unit tests are typically when a bug is discovered. Write a unit test to reproduce the bug, fix the code, and from now on the new unit test will watch your back so the bug won't reappear.

Unit test are also a good place of documentation. The little tests show how the class or method is used.
The code documents itself.

So the benefits are :
* better design
* prove of your code
* safe guard during code maintenance (refactoring, extensions)
* documentation
* ...

== Unit Test frameworks ==
When writing unit tests, one will create a lot of similar code. Since unit tests are nothing more then little programs, several tasks will be repeated, setting up the test environment, create your class, call a method, verify it's result, write out an error message when the test fails, preferably specifying what the wrong outcome was, and what the expected result is.
All these repetitive chores are taken care of by the frame work so the developer can focus on the real code of the test.
This document will use a small but very effective framework for the C++ language. It is called UnitTest++. It's homepage is at : [http://unittest-cpp.sourceforge.net/ UnitTest++].
You can download it directly at this [http://sourceforge.net/projects/unittest-cpp/files/UnitTest%2B%2B/1.4/unittest-cpp-1.4.zip/download link]. At the time of writing the latest version is 1.4.

== Setup our environment ==
Let's create a directory on our PC in which we will cary out our experiments. I will refer to this directory from now on as <TestPit>. For my laptop on which I am writing this article, that will be /home/lieven/Projects/UnitTestArticle. Note that everything we will do, works on linux and on windows!
Download the "unittest-cpp-1.4.zip" file from the link specified above. Extract it in the <TestPit> directory. All the files will end up in the <TestPit>/UnitTest++ directory.

== Build UnitTest++ ==
After the extracted the zip archive we have a directory structure like this :
<pre>
<TestPit>/UnitTest++
|
+docs
|
+src
</pre>
The files in the UnitTest++ directory are of little use for us, since they bring project files for some bizarre Microsoft IDE ;-) .
We will create our own Code::Blocks project to build the UnitTest++ framework.

Why do we need to build something ? Well as said, the framework will do a lot of chores for us, those chores are implemented by code, that code is the framework. We will build to framework into a static library, and for every unit test (or set of unit tests) we create a little (console/shell) program with the test code we wrote, which will link with the static library to obtain a unit test executable, driven by the framework.

We will put our Code::Blocks project file in a nice structured directory tree, therefor let's create a 'Project' subdirectory in the <TestPit>/UnitTest++ directory.

In there create a new file with the name "UnitTest++.cbp".
Give that file the following content :

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="UnitTest++" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option platforms="Windows;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option platforms="Windows;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
<Target title="Debug(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<VirtualTargets>
<Add alias="All" targets="Debug;Release;Debug(linux);Release(linux);" />
</VirtualTargets>
<Unit filename="../src/AssertException.cpp" />
<Unit filename="../src/AssertException.h" />
<Unit filename="../src/CheckMacros.h" />
<Unit filename="../src/Checks.cpp" />
<Unit filename="../src/Checks.h" />
<Unit filename="../src/Config.h" />
<Unit filename="../src/CurrentTest.cpp" />
<Unit filename="../src/CurrentTest.h" />
<Unit filename="../src/DeferredTestReporter.cpp" />
<Unit filename="../src/DeferredTestReporter.h" />
<Unit filename="../src/DeferredTestResult.cpp" />
<Unit filename="../src/DeferredTestResult.h" />
<Unit filename="../src/ExecuteTest.h" />
<Unit filename="../src/MemoryOutStream.cpp" />
<Unit filename="../src/MemoryOutStream.h" />
<Unit filename="../src/Posix/SignalTranslator.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/SignalTranslator.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/ReportAssert.cpp" />
<Unit filename="../src/ReportAssert.h" />
<Unit filename="../src/Test.cpp" />
<Unit filename="../src/Test.h" />
<Unit filename="../src/TestDetails.cpp" />
<Unit filename="../src/TestDetails.h" />
<Unit filename="../src/TestList.cpp" />
<Unit filename="../src/TestList.h" />
<Unit filename="../src/TestMacros.h" />
<Unit filename="../src/TestReporter.cpp" />
<Unit filename="../src/TestReporter.h" />
<Unit filename="../src/TestReporterStdout.cpp" />
<Unit filename="../src/TestReporterStdout.h" />
<Unit filename="../src/TestResults.cpp" />
<Unit filename="../src/TestResults.h" />
<Unit filename="../src/TestRunner.cpp" />
<Unit filename="../src/TestRunner.h" />
<Unit filename="../src/TestSuite.h" />
<Unit filename="../src/TimeConstraint.cpp" />
<Unit filename="../src/TimeConstraint.h" />
<Unit filename="../src/TimeHelpers.h" />
<Unit filename="../src/UnitTest++.h" />
<Unit filename="../src/Win32/TimeHelpers.cpp">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/Win32/TimeHelpers.h">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/XmlTestReporter.cpp" />
<Unit filename="../src/XmlTestReporter.h" />
<Extensions>
<envvars />
<code_completion />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

Some things to note about the content of the project file, the power of Code::Blocks.
* there are 4 targets : Debug/Release for Windows and Debug/Release for linux [yes : 1 project file that allows building on linux and on windows]
* some files are only part of the linux targets, some only for the windows targets

But before we build, let's modify some source files (not really needed, but I prefer to have warning free compilations). These are the changes I carried out :
* ReportAssert.cpp : #include "ReportAssert.h"
* win32/TimeHelpers.cpp : first the m_threadHandle and then the m_startTime in the initializerlist

Next open up this project file in Code::Blocks and build the debug and release target. From now one we will only use the Release target, we go for speed ;-)

The result of the build process will show up in subdirectories of the new 'Deliv' subdirectory of <testPit>/UnitTest++ : '''<testPit>/UnitTest++/Deliv/Release/libUnitTest++.a'''

Alright, we have build the unit test framework in a platform independent way, no silly makefiles, no obscure M$ IDE, good old super Code::Blocks. It is time to write some code so we have something to unit test.

In the first example we will create a simple free function that checks if a given year is a leap year or not.

The business logic is as follows : a year is a leap year when it can be divided by 4, unless it can be divided by 100. But in case it can be divided by 400, then again it is a leap year.

In the next section we will first setup a Code::Blocks project containing both the 'functionality files, and the unit test files. Typically one will package several functionality files into a static library and create a unit test project that tests all the class/functionalities in that library package, also called a component. That is we have a component (whose deliverable is the static library, and we have a unit test project that tests the entire component).

== Our first test project environment ==
Let's create a new directory in our <TestPit> : <TestPit>/LeapYear.
For the simplicity we will put the project file and the source file all together in this directory. Normally we would work in a more structured way, but in a demo article we have some artistic freedom ;-)
Next you can create with the Code::Block's wizard a new console project in the LeapYear directory. Or you can create the following 5 files and give the the contents as specified below. Note that this demo works on linux and on windows, everything is still completely platform independent. Long Live Code::Blocks.

The project file : LeapYear.cbp (the one below already contains the 4 source files, in case you use the wizard you have to add the LeapYear.h/cpp and LeapYearTest.cpp files to the project)

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="LeapYear" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option output="Deliv/Debug/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Debug/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option output="Deliv/Release/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Release/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-O2" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<Compiler>
<Add option="-Wall" />
<Add option="-fexceptions" />
</Compiler>
<Unit filename="LeapYear.cpp" />
<Unit filename="LeapYear.h" />
<Unit filename="LeapYearTest.cpp" />
<Unit filename="main.cpp" />
<Extensions>
<envvars />
<code_completion />
<lib_finder disable_auto="1" />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

The main source file : main.cpp
int main()
{
return 0;
}

The header exporting our powerful function : LeapYear.h

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

#endif // LEAPYEAR_H_INCLUDED

And the implementation of the leap year logic : LeapYear.cpp

#include "LeapYear.h"

And finishing with the source file for the tests : LeapYearTest.cpp (currently) empty

We can already build the project, we have a nice little program that does .... nothing.

Time to move to the next section, a little word about Test Driven Development.

== Test Driven Development ==
This is a practice where new code is only added to make a failing test pass. And one only adds the code needed to make that test pass. Once that is done, a new test is added that will check the next functionality to add.
On this really simple example we will more or less practice some TDD.

So get ready, it's time for LeapYear-Step1.

== LeapYear-Step1 ==
We will turn our main.cpp into the guy in charge to carry out the tests, all we need to do is change the contents of main.cpp into this :

<source lang="cpp">
#include "UnitTest++.h"

int main()
{
return UnitTest::RunAllTests();
}

</source>
And add '''../UnitTest++/src''' to the compiler search directories on the project level of our LeapYear project.
And add '''../UnitTest++/Deliv/Release/libUnitTest++.a''' to the link libraries of the project

Why : well we need to link with the framework and we need to include the UnitTest++ header so we can use it's functionalities.

The line '''UnitTest::RunAllTests()''' will make sure all test encountered in our sources will be carried out.
We don't have any tests yet, nor any functionality, but go ahead build the project and run it.
This is the output :

Success: 0 tests passed
Test time: 0.00 seconds.

Great : success, but no tests yet. Well it's a start.
Time to move forward, and write our first test.

== LeapYear-Step2 ==
Test, test, but there's nothing to test. Yes, absolutely. Let's think of a test, a test that will help us in the design. Now that's a good idea. Suppose I would be the user of the uplifting problem solving leap year checking library/component ... hmmm modesty first : leap year checking '''function'''.
How would I like that function to look.
<source lang="cpp">
bool IsLeapYear(int Year);
</source>
Yes that seems acceptable.
So let's write a test that will call that method.
We do that by adding the following code to LeapYearTest.cpp

<source lang="cpp">
#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

}

</source>
Things to note :
* we include the unit test header
* it is good to put the tests in a nameless namespace (will be explained later on)
* we use the TEST macro, the argument is the name of the test : OurFirstTest
* we use CHECK_EQUAL to check if the expected result (the first argument) matches the computed result (the second argument)

Time to build. Woooooops errors. The test fails completely, it does not even build. Time to add the code needed.
In order to compile the test file, we need to include the LeapYear.h header and have that header export our function.
Our LeapYear header will look like this now (don't forget the include in the test file of our LeapYear.h header, it is not shown here) :

<source lang="cpp">
#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

bool IsLeapYear(int Year);

#endif // LEAPYEAR_H_INCLUDED

</source>

At least now it compiles, but it doesn't link yet. Duh, that because we don't have an implementation yet.
Time to provide the bare minimum of code to make the test pass.
So we change the LeapYear.cpp into :

<source lang="cpp">
#include "LeapYear.h"

bool IsLeapYear(int /*Year*/)
{
return true;
}

</source>
Build it, run it. Yes, we have one working test.
Great. Let's move on.

== LeapYear-Step3 ==
Anyone having the feeling we are cheating. Well the user does not know how we wrote our code on the inside. So just to be sure the user (we) adds the following test, ending up in :

<source lang="cpp">
#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

TEST(OurSecondTest)
{
const bool Result = IsLeapYear(1973);
CHECK_EQUAL(false, Result);
}

}

</source>
Building is already no issue any more, we can run it. Oh boy, a test is failing.
The framework tell us something like this :
<filename>:<Line>: error: Failure in OurSecondTest: Expected 0 but was 1
FAILURE: 1 out of 2 tests failed (1 failures)
Test time: 0.00 seconds.

So we are informed of the line where the failing test occurs, next to that it tells us what it was expecting and what the actual outcome was. And it presents a resume of the total number of tests, and how many that failed. For you scripting hackers note that FAILURE != SUCCESS.

It seems we should do some more effort and implement some real logic.

== LeapYear-Step4 ==
Let's keep it taking one step at a time. Let's start by implementing the 'divisible by 4' logic. That will already solve our tests.
So our LeapYear.cpp will now look like this :

<source lang="cpp">
#include "LeapYear.h"

namespace
{

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year);
}

</source>
Build, run. All tests pass. Life is great.

But those changing requirements, always the change of the requirements. Years that can be divided by 100 should not be considered as a leap year.

Time for our next step.

== LeapYear-Step5 ==
We add a new test for checking for example the year 1900.

<source lang="cpp">
TEST(DivisableBy100)
{
const bool Result = IsLeapYear(1900);
CHECK_EQUAL(false, Result);
}
</source>

Build and run the tests. It will fail. So time to add the minimum code needed to make this test pass.
This will change our LeapYear.cpp into :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year) && !IsDivisableBy100(Year);
}

</source>

Build and run the tests, yes : success. All 3 tests pass.

It seems life might be great again ...

Wrong, someone just added the following test :

<source lang="cpp">
TEST(DivisableBy400)
{
const bool Result = IsLeapYear(2000);
CHECK_EQUAL(true, Result);
}
</source>

And we once again have a failing test.

Time for the next step.

== LeapYear-Step6 ==
We should add logic to deal with years that can be divided by 400, since those are leap years.
We change our LeapYear.cpp into this :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy400(int Year)
{
return (Year%400) == 0;
}

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
const bool LeapYear = IsDivisableBy400(Year) ||
(IsDivisableBy4(Year) && !IsDivisableBy100(Year));
return LeapYear;
}

</source>

And once again everything works OK.
And it seems all the logical rules have been implemented.
This one is ready for shipping, and till the end of time we have our tests that can be run whenever we want (more on this later, we'd prefer this to be done automatically) to ensure we never break anything.

== Increase the user experience ==
There are a few areas where we can increase the user experience.
When a unit test fails the framework tell use on which line in the the code his happens.
That's excellent.
BUT we see this information in a console/shell windows. So we need to find that window, read the issues, remember them and then go find our test source files and navigate manually to the offending line. This works but is very cumbersome.
We want this to be a no-brainer, and have these steps being carried out for us.

Well, didn't we say life is great, Code::Blocks and UnitTest++ to the rescue. The error/warning output of the framework is in the gcc format. That means Code::Blocks can parse it.
One restriction Code::Blocks can parse it during the 'build process'. But currently the build process stops after the unit test executable is build, and only then we run the test executable (manually).
Solution have Code::Blocks run the test executable as a post-build step. Pre-build and post-build steps are part of the build process !
Important consequence : if you want to debug something, the debugger will only kick off after Code::Blocks was able to carry out a successful build (including the pre/post builds steps). Therefor it is not wise to have the unit test executable being carried out as a post-build step of the 'Debug' target. But as a post-build step of the Release target, our goal is met.

Adjust the target settings for the 'Release' target [Build Options -> select Release target -> Pre/Post-build steps -> Post-build steps text field] and add the following '''$exe_output'''. you can tick the 'Always execute' if you want.

Now build your Release target, and look at what shows up in the 'Build Log' tab in Code::Blocks.
This is my output :
<pre>

-------------- Build: Release in LeapYear ---------------

[ 25.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/LeapYear.cpp -o Deliv/Release/LeapYear.o
[ 50.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/LeapYearTest.cpp -o Deliv/Release/LeapYearTest.o
[ 75.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/main.cpp -o Deliv/Release/main.o
[100.0%] g++ -o Deliv/Release/LeapYear Deliv/Release/LeapYear.o Deliv/Release/LeapYearTest.o Deliv/Release/main.o -s ../UnitTest++/Deliv/Release/libUnitTest++.a
Output size is 23.28 KB
[100.0%] Running target post-build steps
Deliv/Release/LeapYear
Success: 4 tests passed.
Test time: 0.00 seconds.
Process terminated with status 0 (0 minutes, 2 seconds)
0 errors, 0 warnings
Build log saved as:
file:///home/lieven/Projects/UnitTestArticle/LeapYear/LeapYear_build_log.html
</pre>

We see that the unit test has been carried out, automatically.

Let's demonstrate that upon a failed test, Code::Blocks will jump to the offending line.
Change the latest test, the one checking on the year 2000 : change 2000 to 2001.
And build : Code::Blocks will jump to the offending line, and shows an entry in the "Build messages" tab (error: Failure in DivisableBy400: Expected 1 but was 0), just like for a regular compiler warning/error.
In the "Build" tab, we now find something like (red colored since it is an error) :
<pre>

-------------- Build: Release in LeapYear ---------------

[ 50.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/LeapYearTest.cpp -o Deliv/Release/LeapYearTest.o
[100.0%] g++ -o Deliv/Release/LeapYear Deliv/Release/LeapYear.o Deliv/Release/LeapYearTest.o Deliv/Release/main.o -s ../UnitTest++/Deliv/Release/libUnitTest++.a
Output size is 23.28 KB
[100.0%] Running target post-build steps
Deliv/Release/LeapYear
/home/lieven/Projects/UnitTestArticle/LeapYear/LeapYearTest.cpp:28: error: Failure in DivisableBy400: Expected 1 but was 0
FAILURE: 1 out of 4 tests failed (1 failures).
Test time: 0.00 seconds.
Process terminated with status 1 (0 minutes, 1 seconds)
1 errors, 0 warnings
Build log saved as:
file:///home/lieven/Projects/UnitTestArticle/LeapYear/LeapYear_build_log.html
</pre>

Voila, we have increased the user experience.
Time to readjust the final test, 2001 becomes 2000 again ;-)

== Further automation ==
You can create a script that calls Code::Blocks on the command line and passes it our LeapYear.cbp project file, and it will build both targets (Debug/Release) and run the test, since it is a post-build step for the 'Release' target.
Bye bye funky makefiles, welcome Code::Blocks as your build system.

== More to come ==
More examples will be added, showcasing 'fixtures' (setup/teardown), some more CHECK macros of UnitTest++. In case you have some tips/ideas, drop me a PM in the forum.
On the planning is a full conversion of the Money example, but all with gcc and Code::Blocks instead of the crazy Microsoft IDE.

UnitTesting

2009-09-09T19:51:00Z

Killerbot: /* LeapYear-Step3 */

This document is under development by killerbot. Starting from 7 September 2009.

== Introduction ==
This document will describe how unit testing can be combined with the Code::Blocks IDE. It will give a hands-on example on a unit testing framework and how it can be used with Code::Blocks.

== What is Unit Testing ==
Simply put Unit Testing is the discipline and best practice of writing and running little test programs that test little units of code.
Such a unit can be :
* a class
* a free function
* an interface
* ...
There are several unit test frameworks available to help you write, deploy, manage your unit tests. The most famous family is the xUnit framework, and some of it's descendants.

== Why Unit Testing ==
Well we write code that implements some functionality. We need a way to check and prove that the implementation is correct. Therefor we need tests. We need tests on the application level, at the integration level of different components, classes, interfaces. But we also need tests for the smallest building blocks, the units.
We also wans these tests to run very quickly. That way we can run the tests often, manually or automated.
These tests will also be our safeguards during refactoring of the code, extending the code or whatever maintenance tasks we carry out on the code.
These tests will also make us think of how our class, method, ... will be used. Since the test can be seen as a user of our code. Thanks to this, thinking about the tests before implementing the functionality can help us in the design : emergent design.
It will help us to avoid creating big classes, complex functions. We will only write the methods that are really needed, and no methods that we think might (n)ever be useful in the future. We are no good future tellers ! Those 'might be needed' methods and their tests are just a waste of time. Extending, refactoring will be done when it is actually needed, and at that time we have our unit tests to ensure we don't break any existing code.

Other times to add new unit tests are typically when a bug is discovered. Write a unit test to reproduce the bug, fix the code, and from now on the new unit test will watch your back so the bug won't reappear.

Unit test are also a good place of documentation. The little tests show how the class or method is used.
The code documents itself.

So the benefits are :
* better design
* prove of your code
* safe guard during code maintenance (refactoring, extensions)
* documentation
* ...

== Unit Test frameworks ==
When writing unit tests, one will create a lot of similar code. Since unit tests are nothing more then little programs, several tasks will be repeated, setting up the test environment, create your class, call a method, verify it's result, write out an error message when the test fails, preferably specifying what the wrong outcome was, and what the expected result is.
All these repetitive chores are taken care of by the frame work so the developer can focus on the real code of the test.
This document will use a small but very effective framework for the C++ language. It is called UnitTest++. It's homepage is at : [http://unittest-cpp.sourceforge.net/ UnitTest++].
You can download it directly at this [http://sourceforge.net/projects/unittest-cpp/files/UnitTest%2B%2B/1.4/unittest-cpp-1.4.zip/download link]. At the time of writing the latest version is 1.4.

== Setup our environment ==
Let's create a directory on our PC in which we will cary out our experiments. I will refer to this directory from now on as <TestPit>. For my laptop on which I am writing this article, that will be /home/lieven/Projects/UnitTestArticle. Note that everything we will do, works on linux and on windows!
Download the "unittest-cpp-1.4.zip" file from the link specified above. Extract it in the <TestPit> directory. All the files will end up in the <TestPit>/UnitTest++ directory.

== Build UnitTest++ ==
After the extracted the zip archive we have a directory structure like this :
<pre>
<TestPit>/UnitTest++
|
+docs
|
+src
</pre>
The files in the UnitTest++ directory are of little use for us, since they bring project files for some bizarre Microsoft IDE ;-) .
We will create our own Code::Blocks project to build the UnitTest++ framework.

Why do we need to build something ? Well as said, the framework will do a lot of chores for us, those chores are implemented by code, that code is the framework. We will build to framework into a static library, and for every unit test (or set of unit tests) we create a little (console/shell) program with the test code we wrote, which will link with the static library to obtain a unit test executable, driven by the framework.

We will put our Code::Blocks project file in a nice structured directory tree, therefor let's create a 'Project' subdirectory in the <TestPit>/UnitTest++ directory.

In there create a new file with the name "UnitTest++.cbp".
Give that file the following content :

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="UnitTest++" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option platforms="Windows;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option platforms="Windows;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
<Target title="Debug(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<VirtualTargets>
<Add alias="All" targets="Debug;Release;Debug(linux);Release(linux);" />
</VirtualTargets>
<Unit filename="../src/AssertException.cpp" />
<Unit filename="../src/AssertException.h" />
<Unit filename="../src/CheckMacros.h" />
<Unit filename="../src/Checks.cpp" />
<Unit filename="../src/Checks.h" />
<Unit filename="../src/Config.h" />
<Unit filename="../src/CurrentTest.cpp" />
<Unit filename="../src/CurrentTest.h" />
<Unit filename="../src/DeferredTestReporter.cpp" />
<Unit filename="../src/DeferredTestReporter.h" />
<Unit filename="../src/DeferredTestResult.cpp" />
<Unit filename="../src/DeferredTestResult.h" />
<Unit filename="../src/ExecuteTest.h" />
<Unit filename="../src/MemoryOutStream.cpp" />
<Unit filename="../src/MemoryOutStream.h" />
<Unit filename="../src/Posix/SignalTranslator.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/SignalTranslator.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/ReportAssert.cpp" />
<Unit filename="../src/ReportAssert.h" />
<Unit filename="../src/Test.cpp" />
<Unit filename="../src/Test.h" />
<Unit filename="../src/TestDetails.cpp" />
<Unit filename="../src/TestDetails.h" />
<Unit filename="../src/TestList.cpp" />
<Unit filename="../src/TestList.h" />
<Unit filename="../src/TestMacros.h" />
<Unit filename="../src/TestReporter.cpp" />
<Unit filename="../src/TestReporter.h" />
<Unit filename="../src/TestReporterStdout.cpp" />
<Unit filename="../src/TestReporterStdout.h" />
<Unit filename="../src/TestResults.cpp" />
<Unit filename="../src/TestResults.h" />
<Unit filename="../src/TestRunner.cpp" />
<Unit filename="../src/TestRunner.h" />
<Unit filename="../src/TestSuite.h" />
<Unit filename="../src/TimeConstraint.cpp" />
<Unit filename="../src/TimeConstraint.h" />
<Unit filename="../src/TimeHelpers.h" />
<Unit filename="../src/UnitTest++.h" />
<Unit filename="../src/Win32/TimeHelpers.cpp">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/Win32/TimeHelpers.h">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/XmlTestReporter.cpp" />
<Unit filename="../src/XmlTestReporter.h" />
<Extensions>
<envvars />
<code_completion />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

Some things to note about the content of the project file, the power of Code::Blocks.
* there are 4 targets : Debug/Release for Windows and Debug/Release for linux [yes : 1 project file that allows building on linux and on windows]
* some files are only part of the linux targets, some only for the windows targets

But before we build, let's modify some source files (not really needed, but I prefer to have warning free compilations). These are the changes I carried out :
* ReportAssert.cpp : #include "ReportAssert.h"
* win32/TimeHelpers.cpp : first the m_threadHandle and then the m_startTime in the initializerlist

Next open up this project file in Code::Blocks and build the debug and release target. From now one we will only use the Release target, we go for speed ;-)

The result of the build process will show up in subdirectories of the new 'Deliv' subdirectory of <testPit>/UnitTest++ : '''<testPit>/UnitTest++/Deliv/Release/libUnitTest++.a'''

Alright, we have build the unit test framework in a platform independent way, no silly makefiles, no obscure M$ IDE, good old super Code::Blocks. It is time to write some code so we have something to unit test.

In the first example we will create a simple free function that checks if a given year is a leap year or not.

The business logic is as follows : a year is a leap year when it can be divided by 4, unless it can be divided by 100. But in case it can be divided by 400, then again it is a leap year.

In the next section we will first setup a Code::Blocks project containing both the 'functionality files, and the unit test files. Typically one will package several functionality files into a static library and create a unit test project that tests all the class/functionalities in that library package, also called a component. That is we have a component (whose deliverable is the static library, and we have a unit test project that tests the entire component).

== Our first test project environment ==
Let's create a new directory in our <TestPit> : <TestPit>/LeapYear.
For the simplicity we will put the project file and the source file all together in this directory. Normally we would work in a more structured way, but in a demo article we have some artistic freedom ;-)
Next you can create with the Code::Block's wizard a new console project in the LeapYear directory. Or you can create the following 5 files and give the the contents as specified below. Note that this demo works on linux and on windows, everything is still completely platform independent. Long Live Code::Blocks.

The project file : LeapYear.cbp (the one below already contains the 4 source files, in case you use the wizard you have to add the LeapYear.h/cpp and LeapYearTest.cpp files to the project)

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="LeapYear" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option output="Deliv/Debug/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Debug/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option output="Deliv/Release/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Release/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-O2" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<Compiler>
<Add option="-Wall" />
<Add option="-fexceptions" />
</Compiler>
<Unit filename="LeapYear.cpp" />
<Unit filename="LeapYear.h" />
<Unit filename="LeapYearTest.cpp" />
<Unit filename="main.cpp" />
<Extensions>
<envvars />
<code_completion />
<lib_finder disable_auto="1" />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

The main source file : main.cpp
int main()
{
return 0;
}

The header exporting our powerful function : LeapYear.h

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

#endif // LEAPYEAR_H_INCLUDED

And the implementation of the leap year logic : LeapYear.cpp

#include "LeapYear.h"

And finishing with the source file for the tests : LeapYearTest.cpp (currently) empty

We can already build the project, we have a nice little program that does .... nothing.

Time to move to the next section, a little word about Test Driven Development.

== Test Driven Development ==
This is a practice where new code is only added to make a failing test pass. And one only adds the code needed to make that test pass. Once that is done, a new test is added that will check the next functionality to add.
On this really simple example we will more or less practice some TDD.

So get ready, it's time for LeapYear-Step1.

== LeapYear-Step1 ==
We will turn our main.cpp into the guy in charge to carry out the tests, all we need to do is change the contents of main.cpp into this :

<source lang="cpp">
#include "UnitTest++.h"

int main()
{
return UnitTest::RunAllTests();
}

</source>
And add '''../UnitTest++/src''' to the compiler search directories on the project level of our LeapYear project.
And add '''../UnitTest++/Deliv/Release/libUnitTest++.a''' to the link libraries of the project

Why : well we need to link with the framework and we need to include the UnitTest++ header so we can use it's functionalities.

The line '''UnitTest::RunAllTests()''' will make sure all test encountered in our sources will be carried out.
We don't have any tests yet, nor any functionality, but go ahead build the project and run it.
This is the output :

Success: 0 tests passed
Test time: 0.00 seconds.

Great : success, but no tests yet. Well it's a start.
Time to move forward, and write our first test.

== LeapYear-Step2 ==
Test, test, but there's nothing to test. Yes, absolutely. Let's think of a test, a test that will help us in the design. Now that's a good idea. Suppose I would be the user of the uplifting problem solving leap year checking library/component ... hmmm modesty first : leap year checking '''function'''.
How would I like that function to look.
<source lang="cpp">
bool IsLeapYear(int Year);
</source>
Yes that seems acceptable.
So let's write a test that will call that method.
We do that by adding the following code to LeapYearTest.cpp

<source lang="cpp">
#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

}

</source>
Things to note :
* we include the unit test header
* it is good to put the tests in a nameless namespace (will be explained later on)
* we use the TEST macro, the argument is the name of the test : OurFirstTest
* we use CHECK_EQUAL to check if the expected result (the first argument) matches the computed result (the second argument)

Time to build. Woooooops errors. The test fails completely, it does not even build. Time to add the code needed.
In order to compile the test file, we need to include the LeapYear.h header and have that header export our function.
Our LeapYear header will look like this now (don't forget the include in the test file of our LeapYear.h header, it is not shown here) :

<source lang="cpp">
#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

bool IsLeapYear(int Year);

#endif // LEAPYEAR_H_INCLUDED

</source>

At least now it compiles, but it doesn't link yet. Duh, that because we don't have an implementation yet.
Time to provide the bare minimum of code to make the test pass.
So we change the LeapYear.cpp into :

<source lang="cpp">
#include "LeapYear.h"

bool IsLeapYear(int /*Year*/)
{
return true;
}

</source>
Build it, run it. Yes, we have one working test.
Great. Let's move on.

== LeapYear-Step3 ==
Anyone having the feeling we are cheating. Well the user does not know how we wrote our code on the inside. So just to be sure the user (we) adds the following test, ending up in :

<source lang="cpp">
#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

TEST(OurSecondTest)
{
const bool Result = IsLeapYear(1973);
CHECK_EQUAL(false, Result);
}

}

</source>
Building is already no issue any more, we can run it. Oh boy, a test is failing.
The framework tell us something like this :
<filename>:<Line>: error: Failure in OurSecondTest: Expected 0 but was 1
FAILURE: 1 out of 2 tests failed (1 failures)
Test time: 0.00 seconds.

So we are informed of the line where the failing test occurs, next to that it tells us what it was expecting and what the actual outcome was. And it presents a resume of the total number of tests, and how many that failed. For you scripting hackers note that FAILURE != SUCCESS.

It seems we should do some more effort and implement some real logic.

== LeapYear-Step4 ==
Let's keep it taking one step at a time. Let's start by implementing the 'divisible by 4' logic. That will already solve our tests.
So our LeapYear.cpp will now look like this :

<source lang="cpp">
#include "LeapYear.h"

namespace
{

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year);
}

</source>
Build, run. All tests pass. Life is great.

But those changing requirements, always the change of the requirements. Years that can be divided by 100 should not be considered as a leap year.

Time for our next step.

== LeapYear-Step5 ==
We add a new test for checking for example the year 1900.

<source lang="cpp">
TEST(DivisableBy100)
{
const bool Result = IsLeapYear(1900);
CHECK_EQUAL(false, Result);
}
</source>

Build and run the tests. It will fail. So time to add the minimum code needed to make this test pass.
This will change our LeapYear.cpp into :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year) && !IsDivisableBy100(Year);
}

</source>

Build and run the tests, yes : success. All 3 tests pass.

It seems life might be great again ...

Wrong, someone just added the following test :

<source lang="cpp">
TEST(DivisableBy400)
{
const bool Result = IsLeapYear(2000);
CHECK_EQUAL(true, Result);
}
</source>

And we once again have a failing test.

Time for the next step.

== LeapYear-Step6 ==
We should add logic to deal with years that can be divided by 400, since those are leap years.
We change our LeapYear.cpp into this :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy400(int Year)
{
return (Year%400) == 0;
}

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
const bool LeapYear = IsDivisableBy400(Year) ||
(IsDivisableBy4(Year) && !IsDivisableBy100(Year));
return LeapYear;
}

</source>

And once again everything works OK.
And it seems all the logical rules have been implemented.
This one is ready for shipping, and till the end of time we have our tests that can be run whenever we want (more on this later, we'd prefer this to be done automatically) to ensure we never break anything.

== Increase the user experience ==
There are a few areas where we can increase the user experience.
When a unit test fails the framework tell use on which line in the the code his happens.
That's excellent.
BUT we see this information in a console/shell windows. So we need to find that window, read the issues, remember them and then go find our test source files and navigate manually to the offending line. This works but is very cumbersome.
We want this to be a no-brainer, and have these steps being carried out for us.

Well, didn't we say life is great, Code::Blocks and UnitTest+= to the rescue. The error/warning output of the framework is in the gcc format. That means Code::Blocks can parse it.
One restriction Code::Blocks can parse it during the 'build process'. But currently the build procss stops after the unit test executable is build, and only then we run the test executable (manually).
Solution have Code::Blocks run the test executable as a post-build step. Pre-build and post-build steps are part of the build process !
Important consequence : if you want to debug something, the debugger will only kick off after Code::Blocks was able to carry out a successful build (including the pre/post builds steps). Therefor it is not wise to have the unit test executable being carried out as a post-bild step of the 'Debug' target. But as a post-build step of the Release target, our goal is met.

Adjust the target settings for the 'Release' target [Build Options -> select Release target -> Pre/Post-build steps -> Post-build steps text field] and add the following '''$exe_output'''. you can tick the 'Always execute' if you want.

Now build your Release target, and look at what shows up in the 'Build Log' tab in Code::Blocks.
This is my output :
<pre>

-------------- Build: Release in LeapYear ---------------

[ 25.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/LeapYear.cpp -o Deliv/Release/LeapYear.o
[ 50.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/LeapYearTest.cpp -o Deliv/Release/LeapYearTest.o
[ 75.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/main.cpp -o Deliv/Release/main.o
[100.0%] g++ -o Deliv/Release/LeapYear Deliv/Release/LeapYear.o Deliv/Release/LeapYearTest.o Deliv/Release/main.o -s ../UnitTest++/Deliv/Release/libUnitTest++.a
Output size is 23.28 KB
[100.0%] Running target post-build steps
Deliv/Release/LeapYear
Success: 4 tests passed.
Test time: 0.00 seconds.
Process terminated with status 0 (0 minutes, 2 seconds)
0 errors, 0 warnings
Build log saved as:
file:///home/lieven/Projects/UnitTestArticle/LeapYear/LeapYear_build_log.html
</pre>

We see that the unit test has been carried out, automatically.

Let's demonstrate that upon a failed test, Code::Blocks will jump to the offending line.
Change the latest test, the one checking on the year 2000 : change 2000 to 2001.
And build : Code::Blocks will jump to the offending line, and shows an entry in the "Build messages" tab (error: Failure in DivisableBy400: Expected 1 but was 0), just like for a regular compiler warning/error.
In the "Build" tab, we now find something like (red colored since it is an error) :
<pre>

-------------- Build: Release in LeapYear ---------------

[ 50.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/LeapYearTest.cpp -o Deliv/Release/LeapYearTest.o
[100.0%] g++ -o Deliv/Release/LeapYear Deliv/Release/LeapYear.o Deliv/Release/LeapYearTest.o Deliv/Release/main.o -s ../UnitTest++/Deliv/Release/libUnitTest++.a
Output size is 23.28 KB
[100.0%] Running target post-build steps
Deliv/Release/LeapYear
/home/lieven/Projects/UnitTestArticle/LeapYear/LeapYearTest.cpp:28: error: Failure in DivisableBy400: Expected 1 but was 0
FAILURE: 1 out of 4 tests failed (1 failures).
Test time: 0.00 seconds.
Process terminated with status 1 (0 minutes, 1 seconds)
1 errors, 0 warnings
Build log saved as:
file:///home/lieven/Projects/UnitTestArticle/LeapYear/LeapYear_build_log.html
</pre>

Voila, we have increased the user experience.
Time to readjust the final test, 2001 becomes 2000 again ;-)

== Further automation ==
You can create a script that calls Code::Blocks on the command line and passes it our LeapYear.cbp project file, and it will build both targets (Debug/Release) and run the test, since it is a post-build step for the 'Release' target.
Bye bye funky makefiles, welcome Code::Blocks as your build system.

== More to come ==
More examples will be added, showcasing 'fixtures' (setup/teardown), some more CHECK macros of UnitTest++. In case you have some tips/ideas, drop me a PM in the forum.
On the planning is a full conversion of the Money example, but all with gcc and Code::Blocks instead of the crazy Microsoft IDE.

UnitTesting

2009-09-09T19:49:46Z

Killerbot: /* LeapYear-Step2 */

This document is under development by killerbot. Starting from 7 September 2009.

== Introduction ==
This document will describe how unit testing can be combined with the Code::Blocks IDE. It will give a hands-on example on a unit testing framework and how it can be used with Code::Blocks.

== What is Unit Testing ==
Simply put Unit Testing is the discipline and best practice of writing and running little test programs that test little units of code.
Such a unit can be :
* a class
* a free function
* an interface
* ...
There are several unit test frameworks available to help you write, deploy, manage your unit tests. The most famous family is the xUnit framework, and some of it's descendants.

== Why Unit Testing ==
Well we write code that implements some functionality. We need a way to check and prove that the implementation is correct. Therefor we need tests. We need tests on the application level, at the integration level of different components, classes, interfaces. But we also need tests for the smallest building blocks, the units.
We also wans these tests to run very quickly. That way we can run the tests often, manually or automated.
These tests will also be our safeguards during refactoring of the code, extending the code or whatever maintenance tasks we carry out on the code.
These tests will also make us think of how our class, method, ... will be used. Since the test can be seen as a user of our code. Thanks to this, thinking about the tests before implementing the functionality can help us in the design : emergent design.
It will help us to avoid creating big classes, complex functions. We will only write the methods that are really needed, and no methods that we think might (n)ever be useful in the future. We are no good future tellers ! Those 'might be needed' methods and their tests are just a waste of time. Extending, refactoring will be done when it is actually needed, and at that time we have our unit tests to ensure we don't break any existing code.

Other times to add new unit tests are typically when a bug is discovered. Write a unit test to reproduce the bug, fix the code, and from now on the new unit test will watch your back so the bug won't reappear.

Unit test are also a good place of documentation. The little tests show how the class or method is used.
The code documents itself.

So the benefits are :
* better design
* prove of your code
* safe guard during code maintenance (refactoring, extensions)
* documentation
* ...

== Unit Test frameworks ==
When writing unit tests, one will create a lot of similar code. Since unit tests are nothing more then little programs, several tasks will be repeated, setting up the test environment, create your class, call a method, verify it's result, write out an error message when the test fails, preferably specifying what the wrong outcome was, and what the expected result is.
All these repetitive chores are taken care of by the frame work so the developer can focus on the real code of the test.
This document will use a small but very effective framework for the C++ language. It is called UnitTest++. It's homepage is at : [http://unittest-cpp.sourceforge.net/ UnitTest++].
You can download it directly at this [http://sourceforge.net/projects/unittest-cpp/files/UnitTest%2B%2B/1.4/unittest-cpp-1.4.zip/download link]. At the time of writing the latest version is 1.4.

== Setup our environment ==
Let's create a directory on our PC in which we will cary out our experiments. I will refer to this directory from now on as <TestPit>. For my laptop on which I am writing this article, that will be /home/lieven/Projects/UnitTestArticle. Note that everything we will do, works on linux and on windows!
Download the "unittest-cpp-1.4.zip" file from the link specified above. Extract it in the <TestPit> directory. All the files will end up in the <TestPit>/UnitTest++ directory.

== Build UnitTest++ ==
After the extracted the zip archive we have a directory structure like this :
<pre>
<TestPit>/UnitTest++
|
+docs
|
+src
</pre>
The files in the UnitTest++ directory are of little use for us, since they bring project files for some bizarre Microsoft IDE ;-) .
We will create our own Code::Blocks project to build the UnitTest++ framework.

Why do we need to build something ? Well as said, the framework will do a lot of chores for us, those chores are implemented by code, that code is the framework. We will build to framework into a static library, and for every unit test (or set of unit tests) we create a little (console/shell) program with the test code we wrote, which will link with the static library to obtain a unit test executable, driven by the framework.

We will put our Code::Blocks project file in a nice structured directory tree, therefor let's create a 'Project' subdirectory in the <TestPit>/UnitTest++ directory.

In there create a new file with the name "UnitTest++.cbp".
Give that file the following content :

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="UnitTest++" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option platforms="Windows;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option platforms="Windows;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
<Target title="Debug(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<VirtualTargets>
<Add alias="All" targets="Debug;Release;Debug(linux);Release(linux);" />
</VirtualTargets>
<Unit filename="../src/AssertException.cpp" />
<Unit filename="../src/AssertException.h" />
<Unit filename="../src/CheckMacros.h" />
<Unit filename="../src/Checks.cpp" />
<Unit filename="../src/Checks.h" />
<Unit filename="../src/Config.h" />
<Unit filename="../src/CurrentTest.cpp" />
<Unit filename="../src/CurrentTest.h" />
<Unit filename="../src/DeferredTestReporter.cpp" />
<Unit filename="../src/DeferredTestReporter.h" />
<Unit filename="../src/DeferredTestResult.cpp" />
<Unit filename="../src/DeferredTestResult.h" />
<Unit filename="../src/ExecuteTest.h" />
<Unit filename="../src/MemoryOutStream.cpp" />
<Unit filename="../src/MemoryOutStream.h" />
<Unit filename="../src/Posix/SignalTranslator.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/SignalTranslator.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/ReportAssert.cpp" />
<Unit filename="../src/ReportAssert.h" />
<Unit filename="../src/Test.cpp" />
<Unit filename="../src/Test.h" />
<Unit filename="../src/TestDetails.cpp" />
<Unit filename="../src/TestDetails.h" />
<Unit filename="../src/TestList.cpp" />
<Unit filename="../src/TestList.h" />
<Unit filename="../src/TestMacros.h" />
<Unit filename="../src/TestReporter.cpp" />
<Unit filename="../src/TestReporter.h" />
<Unit filename="../src/TestReporterStdout.cpp" />
<Unit filename="../src/TestReporterStdout.h" />
<Unit filename="../src/TestResults.cpp" />
<Unit filename="../src/TestResults.h" />
<Unit filename="../src/TestRunner.cpp" />
<Unit filename="../src/TestRunner.h" />
<Unit filename="../src/TestSuite.h" />
<Unit filename="../src/TimeConstraint.cpp" />
<Unit filename="../src/TimeConstraint.h" />
<Unit filename="../src/TimeHelpers.h" />
<Unit filename="../src/UnitTest++.h" />
<Unit filename="../src/Win32/TimeHelpers.cpp">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/Win32/TimeHelpers.h">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/XmlTestReporter.cpp" />
<Unit filename="../src/XmlTestReporter.h" />
<Extensions>
<envvars />
<code_completion />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

Some things to note about the content of the project file, the power of Code::Blocks.
* there are 4 targets : Debug/Release for Windows and Debug/Release for linux [yes : 1 project file that allows building on linux and on windows]
* some files are only part of the linux targets, some only for the windows targets

But before we build, let's modify some source files (not really needed, but I prefer to have warning free compilations). These are the changes I carried out :
* ReportAssert.cpp : #include "ReportAssert.h"
* win32/TimeHelpers.cpp : first the m_threadHandle and then the m_startTime in the initializerlist

Next open up this project file in Code::Blocks and build the debug and release target. From now one we will only use the Release target, we go for speed ;-)

The result of the build process will show up in subdirectories of the new 'Deliv' subdirectory of <testPit>/UnitTest++ : '''<testPit>/UnitTest++/Deliv/Release/libUnitTest++.a'''

Alright, we have build the unit test framework in a platform independent way, no silly makefiles, no obscure M$ IDE, good old super Code::Blocks. It is time to write some code so we have something to unit test.

In the first example we will create a simple free function that checks if a given year is a leap year or not.

The business logic is as follows : a year is a leap year when it can be divided by 4, unless it can be divided by 100. But in case it can be divided by 400, then again it is a leap year.

In the next section we will first setup a Code::Blocks project containing both the 'functionality files, and the unit test files. Typically one will package several functionality files into a static library and create a unit test project that tests all the class/functionalities in that library package, also called a component. That is we have a component (whose deliverable is the static library, and we have a unit test project that tests the entire component).

== Our first test project environment ==
Let's create a new directory in our <TestPit> : <TestPit>/LeapYear.
For the simplicity we will put the project file and the source file all together in this directory. Normally we would work in a more structured way, but in a demo article we have some artistic freedom ;-)
Next you can create with the Code::Block's wizard a new console project in the LeapYear directory. Or you can create the following 5 files and give the the contents as specified below. Note that this demo works on linux and on windows, everything is still completely platform independent. Long Live Code::Blocks.

The project file : LeapYear.cbp (the one below already contains the 4 source files, in case you use the wizard you have to add the LeapYear.h/cpp and LeapYearTest.cpp files to the project)

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="LeapYear" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option output="Deliv/Debug/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Debug/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option output="Deliv/Release/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Release/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-O2" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<Compiler>
<Add option="-Wall" />
<Add option="-fexceptions" />
</Compiler>
<Unit filename="LeapYear.cpp" />
<Unit filename="LeapYear.h" />
<Unit filename="LeapYearTest.cpp" />
<Unit filename="main.cpp" />
<Extensions>
<envvars />
<code_completion />
<lib_finder disable_auto="1" />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

The main source file : main.cpp
int main()
{
return 0;
}

The header exporting our powerful function : LeapYear.h

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

#endif // LEAPYEAR_H_INCLUDED

And the implementation of the leap year logic : LeapYear.cpp

#include "LeapYear.h"

And finishing with the source file for the tests : LeapYearTest.cpp (currently) empty

We can already build the project, we have a nice little program that does .... nothing.

Time to move to the next section, a little word about Test Driven Development.

== Test Driven Development ==
This is a practice where new code is only added to make a failing test pass. And one only adds the code needed to make that test pass. Once that is done, a new test is added that will check the next functionality to add.
On this really simple example we will more or less practice some TDD.

So get ready, it's time for LeapYear-Step1.

== LeapYear-Step1 ==
We will turn our main.cpp into the guy in charge to carry out the tests, all we need to do is change the contents of main.cpp into this :

<source lang="cpp">
#include "UnitTest++.h"

int main()
{
return UnitTest::RunAllTests();
}

</source>
And add '''../UnitTest++/src''' to the compiler search directories on the project level of our LeapYear project.
And add '''../UnitTest++/Deliv/Release/libUnitTest++.a''' to the link libraries of the project

Why : well we need to link with the framework and we need to include the UnitTest++ header so we can use it's functionalities.

The line '''UnitTest::RunAllTests()''' will make sure all test encountered in our sources will be carried out.
We don't have any tests yet, nor any functionality, but go ahead build the project and run it.
This is the output :

Success: 0 tests passed
Test time: 0.00 seconds.

Great : success, but no tests yet. Well it's a start.
Time to move forward, and write our first test.

== LeapYear-Step2 ==
Test, test, but there's nothing to test. Yes, absolutely. Let's think of a test, a test that will help us in the design. Now that's a good idea. Suppose I would be the user of the uplifting problem solving leap year checking library/component ... hmmm modesty first : leap year checking '''function'''.
How would I like that function to look.
<source lang="cpp">
bool IsLeapYear(int Year);
</source>
Yes that seems acceptable.
So let's write a test that will call that method.
We do that by adding the following code to LeapYearTest.cpp

<source lang="cpp">
#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

}

</source>
Things to note :
* we include the unit test header
* it is good to put the tests in a nameless namespace (will be explained later on)
* we use the TEST macro, the argument is the name of the test : OurFirstTest
* we use CHECK_EQUAL to check if the expected result (the first argument) matches the computed result (the second argument)

Time to build. Woooooops errors. The test fails completely, it does not even build. Time to add the code needed.
In order to compile the test file, we need to include the LeapYear.h header and have that header export our function.
Our LeapYear header will look like this now (don't forget the include in the test file of our LeapYear.h header, it is not shown here) :

<source lang="cpp">
#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

bool IsLeapYear(int Year);

#endif // LEAPYEAR_H_INCLUDED

</source>

At least now it compiles, but it doesn't link yet. Duh, that because we don't have an implementation yet.
Time to provide the bare minimum of code to make the test pass.
So we change the LeapYear.cpp into :

<source lang="cpp">
#include "LeapYear.h"

bool IsLeapYear(int /*Year*/)
{
return true;
}

</source>
Build it, run it. Yes, we have one working test.
Great. Let's move on.

== LeapYear-Step3 ==
Anyone having the feeling we are cheating. Well the user does not know how we wrote our code on the inside. So just to be sure the user (we) adds the following test, ending up in :

<source lang="cpp">
#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

TEST(OurSecondTest)
{
const bool Result = IsLeapYear(1973);
CHECK_EQUAL(false, Result);
}

}

</source>
Building is already no issue any more, we can run it. Oh boy, a test is failing.
The framework tell us something like this :
<filename>:<Line>: error: Failure in OurSecondTest: Expected 0 but was 1
FAILURE: 1 out of 2 tests failed (1 failures)
Test time: 0.00 seconds.

So we are informed of the line where the failing tests occurs, next to that it tells us what it was expecting and what the actual outcome was. And it presents a resume of the total number of tests, and how many that failed. For you scripting hackers note that FAILURE != SUCCESS.

It seems we should do some more effort and implement some real logic.

== LeapYear-Step4 ==
Let's keep it taking one step at a time. Let's start by implementing the 'divisible by 4' logic. That will already solve our tests.
So our LeapYear.cpp will now look like this :

<source lang="cpp">
#include "LeapYear.h"

namespace
{

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year);
}

</source>
Build, run. All tests pass. Life is great.

But those changing requirements, always the change of the requirements. Years that can be divided by 100 should not be considered as a leap year.

Time for our next step.

== LeapYear-Step5 ==
We add a new test for checking for example the year 1900.

<source lang="cpp">
TEST(DivisableBy100)
{
const bool Result = IsLeapYear(1900);
CHECK_EQUAL(false, Result);
}
</source>

Build and run the tests. It will fail. So time to add the minimum code needed to make this test pass.
This will change our LeapYear.cpp into :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year) && !IsDivisableBy100(Year);
}

</source>

Build and run the tests, yes : success. All 3 tests pass.

It seems life might be great again ...

Wrong, someone just added the following test :

<source lang="cpp">
TEST(DivisableBy400)
{
const bool Result = IsLeapYear(2000);
CHECK_EQUAL(true, Result);
}
</source>

And we once again have a failing test.

Time for the next step.

== LeapYear-Step6 ==
We should add logic to deal with years that can be divided by 400, since those are leap years.
We change our LeapYear.cpp into this :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy400(int Year)
{
return (Year%400) == 0;
}

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
const bool LeapYear = IsDivisableBy400(Year) ||
(IsDivisableBy4(Year) && !IsDivisableBy100(Year));
return LeapYear;
}

</source>

And once again everything works OK.
And it seems all the logical rules have been implemented.
This one is ready for shipping, and till the end of time we have our tests that can be run whenever we want (more on this later, we'd prefer this to be done automatically) to ensure we never break anything.

== Increase the user experience ==
There are a few areas where we can increase the user experience.
When a unit test fails the framework tell use on which line in the the code his happens.
That's excellent.
BUT we see this information in a console/shell windows. So we need to find that window, read the issues, remember them and then go find our test source files and navigate manually to the offending line. This works but is very cumbersome.
We want this to be a no-brainer, and have these steps being carried out for us.

Well, didn't we say life is great, Code::Blocks and UnitTest+= to the rescue. The error/warning output of the framework is in the gcc format. That means Code::Blocks can parse it.
One restriction Code::Blocks can parse it during the 'build process'. But currently the build procss stops after the unit test executable is build, and only then we run the test executable (manually).
Solution have Code::Blocks run the test executable as a post-build step. Pre-build and post-build steps are part of the build process !
Important consequence : if you want to debug something, the debugger will only kick off after Code::Blocks was able to carry out a successful build (including the pre/post builds steps). Therefor it is not wise to have the unit test executable being carried out as a post-bild step of the 'Debug' target. But as a post-build step of the Release target, our goal is met.

Adjust the target settings for the 'Release' target [Build Options -> select Release target -> Pre/Post-build steps -> Post-build steps text field] and add the following '''$exe_output'''. you can tick the 'Always execute' if you want.

Now build your Release target, and look at what shows up in the 'Build Log' tab in Code::Blocks.
This is my output :
<pre>

-------------- Build: Release in LeapYear ---------------

[ 25.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/LeapYear.cpp -o Deliv/Release/LeapYear.o
[ 50.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/LeapYearTest.cpp -o Deliv/Release/LeapYearTest.o
[ 75.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/main.cpp -o Deliv/Release/main.o
[100.0%] g++ -o Deliv/Release/LeapYear Deliv/Release/LeapYear.o Deliv/Release/LeapYearTest.o Deliv/Release/main.o -s ../UnitTest++/Deliv/Release/libUnitTest++.a
Output size is 23.28 KB
[100.0%] Running target post-build steps
Deliv/Release/LeapYear
Success: 4 tests passed.
Test time: 0.00 seconds.
Process terminated with status 0 (0 minutes, 2 seconds)
0 errors, 0 warnings
Build log saved as:
file:///home/lieven/Projects/UnitTestArticle/LeapYear/LeapYear_build_log.html
</pre>

We see that the unit test has been carried out, automatically.

Let's demonstrate that upon a failed test, Code::Blocks will jump to the offending line.
Change the latest test, the one checking on the year 2000 : change 2000 to 2001.
And build : Code::Blocks will jump to the offending line, and shows an entry in the "Build messages" tab (error: Failure in DivisableBy400: Expected 1 but was 0), just like for a regular compiler warning/error.
In the "Build" tab, we now find something like (red colored since it is an error) :
<pre>

-------------- Build: Release in LeapYear ---------------

[ 50.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/LeapYearTest.cpp -o Deliv/Release/LeapYearTest.o
[100.0%] g++ -o Deliv/Release/LeapYear Deliv/Release/LeapYear.o Deliv/Release/LeapYearTest.o Deliv/Release/main.o -s ../UnitTest++/Deliv/Release/libUnitTest++.a
Output size is 23.28 KB
[100.0%] Running target post-build steps
Deliv/Release/LeapYear
/home/lieven/Projects/UnitTestArticle/LeapYear/LeapYearTest.cpp:28: error: Failure in DivisableBy400: Expected 1 but was 0
FAILURE: 1 out of 4 tests failed (1 failures).
Test time: 0.00 seconds.
Process terminated with status 1 (0 minutes, 1 seconds)
1 errors, 0 warnings
Build log saved as:
file:///home/lieven/Projects/UnitTestArticle/LeapYear/LeapYear_build_log.html
</pre>

Voila, we have increased the user experience.
Time to readjust the final test, 2001 becomes 2000 again ;-)

== Further automation ==
You can create a script that calls Code::Blocks on the command line and passes it our LeapYear.cbp project file, and it will build both targets (Debug/Release) and run the test, since it is a post-build step for the 'Release' target.
Bye bye funky makefiles, welcome Code::Blocks as your build system.

== More to come ==
More examples will be added, showcasing 'fixtures' (setup/teardown), some more CHECK macros of UnitTest++. In case you have some tips/ideas, drop me a PM in the forum.
On the planning is a full conversion of the Money example, but all with gcc and Code::Blocks instead of the crazy Microsoft IDE.

UnitTesting

2009-09-09T19:42:19Z

Killerbot: /* Test Driven Development */

This document is under development by killerbot. Starting from 7 September 2009.

== Introduction ==
This document will describe how unit testing can be combined with the Code::Blocks IDE. It will give a hands-on example on a unit testing framework and how it can be used with Code::Blocks.

== What is Unit Testing ==
Simply put Unit Testing is the discipline and best practice of writing and running little test programs that test little units of code.
Such a unit can be :
* a class
* a free function
* an interface
* ...
There are several unit test frameworks available to help you write, deploy, manage your unit tests. The most famous family is the xUnit framework, and some of it's descendants.

== Why Unit Testing ==
Well we write code that implements some functionality. We need a way to check and prove that the implementation is correct. Therefor we need tests. We need tests on the application level, at the integration level of different components, classes, interfaces. But we also need tests for the smallest building blocks, the units.
We also wans these tests to run very quickly. That way we can run the tests often, manually or automated.
These tests will also be our safeguards during refactoring of the code, extending the code or whatever maintenance tasks we carry out on the code.
These tests will also make us think of how our class, method, ... will be used. Since the test can be seen as a user of our code. Thanks to this, thinking about the tests before implementing the functionality can help us in the design : emergent design.
It will help us to avoid creating big classes, complex functions. We will only write the methods that are really needed, and no methods that we think might (n)ever be useful in the future. We are no good future tellers ! Those 'might be needed' methods and their tests are just a waste of time. Extending, refactoring will be done when it is actually needed, and at that time we have our unit tests to ensure we don't break any existing code.

Other times to add new unit tests are typically when a bug is discovered. Write a unit test to reproduce the bug, fix the code, and from now on the new unit test will watch your back so the bug won't reappear.

Unit test are also a good place of documentation. The little tests show how the class or method is used.
The code documents itself.

So the benefits are :
* better design
* prove of your code
* safe guard during code maintenance (refactoring, extensions)
* documentation
* ...

== Unit Test frameworks ==
When writing unit tests, one will create a lot of similar code. Since unit tests are nothing more then little programs, several tasks will be repeated, setting up the test environment, create your class, call a method, verify it's result, write out an error message when the test fails, preferably specifying what the wrong outcome was, and what the expected result is.
All these repetitive chores are taken care of by the frame work so the developer can focus on the real code of the test.
This document will use a small but very effective framework for the C++ language. It is called UnitTest++. It's homepage is at : [http://unittest-cpp.sourceforge.net/ UnitTest++].
You can download it directly at this [http://sourceforge.net/projects/unittest-cpp/files/UnitTest%2B%2B/1.4/unittest-cpp-1.4.zip/download link]. At the time of writing the latest version is 1.4.

== Setup our environment ==
Let's create a directory on our PC in which we will cary out our experiments. I will refer to this directory from now on as <TestPit>. For my laptop on which I am writing this article, that will be /home/lieven/Projects/UnitTestArticle. Note that everything we will do, works on linux and on windows!
Download the "unittest-cpp-1.4.zip" file from the link specified above. Extract it in the <TestPit> directory. All the files will end up in the <TestPit>/UnitTest++ directory.

== Build UnitTest++ ==
After the extracted the zip archive we have a directory structure like this :
<pre>
<TestPit>/UnitTest++
|
+docs
|
+src
</pre>
The files in the UnitTest++ directory are of little use for us, since they bring project files for some bizarre Microsoft IDE ;-) .
We will create our own Code::Blocks project to build the UnitTest++ framework.

Why do we need to build something ? Well as said, the framework will do a lot of chores for us, those chores are implemented by code, that code is the framework. We will build to framework into a static library, and for every unit test (or set of unit tests) we create a little (console/shell) program with the test code we wrote, which will link with the static library to obtain a unit test executable, driven by the framework.

We will put our Code::Blocks project file in a nice structured directory tree, therefor let's create a 'Project' subdirectory in the <TestPit>/UnitTest++ directory.

In there create a new file with the name "UnitTest++.cbp".
Give that file the following content :

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="UnitTest++" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option platforms="Windows;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option platforms="Windows;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
<Target title="Debug(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<VirtualTargets>
<Add alias="All" targets="Debug;Release;Debug(linux);Release(linux);" />
</VirtualTargets>
<Unit filename="../src/AssertException.cpp" />
<Unit filename="../src/AssertException.h" />
<Unit filename="../src/CheckMacros.h" />
<Unit filename="../src/Checks.cpp" />
<Unit filename="../src/Checks.h" />
<Unit filename="../src/Config.h" />
<Unit filename="../src/CurrentTest.cpp" />
<Unit filename="../src/CurrentTest.h" />
<Unit filename="../src/DeferredTestReporter.cpp" />
<Unit filename="../src/DeferredTestReporter.h" />
<Unit filename="../src/DeferredTestResult.cpp" />
<Unit filename="../src/DeferredTestResult.h" />
<Unit filename="../src/ExecuteTest.h" />
<Unit filename="../src/MemoryOutStream.cpp" />
<Unit filename="../src/MemoryOutStream.h" />
<Unit filename="../src/Posix/SignalTranslator.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/SignalTranslator.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/ReportAssert.cpp" />
<Unit filename="../src/ReportAssert.h" />
<Unit filename="../src/Test.cpp" />
<Unit filename="../src/Test.h" />
<Unit filename="../src/TestDetails.cpp" />
<Unit filename="../src/TestDetails.h" />
<Unit filename="../src/TestList.cpp" />
<Unit filename="../src/TestList.h" />
<Unit filename="../src/TestMacros.h" />
<Unit filename="../src/TestReporter.cpp" />
<Unit filename="../src/TestReporter.h" />
<Unit filename="../src/TestReporterStdout.cpp" />
<Unit filename="../src/TestReporterStdout.h" />
<Unit filename="../src/TestResults.cpp" />
<Unit filename="../src/TestResults.h" />
<Unit filename="../src/TestRunner.cpp" />
<Unit filename="../src/TestRunner.h" />
<Unit filename="../src/TestSuite.h" />
<Unit filename="../src/TimeConstraint.cpp" />
<Unit filename="../src/TimeConstraint.h" />
<Unit filename="../src/TimeHelpers.h" />
<Unit filename="../src/UnitTest++.h" />
<Unit filename="../src/Win32/TimeHelpers.cpp">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/Win32/TimeHelpers.h">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/XmlTestReporter.cpp" />
<Unit filename="../src/XmlTestReporter.h" />
<Extensions>
<envvars />
<code_completion />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

Some things to note about the content of the project file, the power of Code::Blocks.
* there are 4 targets : Debug/Release for Windows and Debug/Release for linux [yes : 1 project file that allows building on linux and on windows]
* some files are only part of the linux targets, some only for the windows targets

But before we build, let's modify some source files (not really needed, but I prefer to have warning free compilations). These are the changes I carried out :
* ReportAssert.cpp : #include "ReportAssert.h"
* win32/TimeHelpers.cpp : first the m_threadHandle and then the m_startTime in the initializerlist

Next open up this project file in Code::Blocks and build the debug and release target. From now one we will only use the Release target, we go for speed ;-)

The result of the build process will show up in subdirectories of the new 'Deliv' subdirectory of <testPit>/UnitTest++ : '''<testPit>/UnitTest++/Deliv/Release/libUnitTest++.a'''

Alright, we have build the unit test framework in a platform independent way, no silly makefiles, no obscure M$ IDE, good old super Code::Blocks. It is time to write some code so we have something to unit test.

In the first example we will create a simple free function that checks if a given year is a leap year or not.

The business logic is as follows : a year is a leap year when it can be divided by 4, unless it can be divided by 100. But in case it can be divided by 400, then again it is a leap year.

In the next section we will first setup a Code::Blocks project containing both the 'functionality files, and the unit test files. Typically one will package several functionality files into a static library and create a unit test project that tests all the class/functionalities in that library package, also called a component. That is we have a component (whose deliverable is the static library, and we have a unit test project that tests the entire component).

== Our first test project environment ==
Let's create a new directory in our <TestPit> : <TestPit>/LeapYear.
For the simplicity we will put the project file and the source file all together in this directory. Normally we would work in a more structured way, but in a demo article we have some artistic freedom ;-)
Next you can create with the Code::Block's wizard a new console project in the LeapYear directory. Or you can create the following 5 files and give the the contents as specified below. Note that this demo works on linux and on windows, everything is still completely platform independent. Long Live Code::Blocks.

The project file : LeapYear.cbp (the one below already contains the 4 source files, in case you use the wizard you have to add the LeapYear.h/cpp and LeapYearTest.cpp files to the project)

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="LeapYear" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option output="Deliv/Debug/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Debug/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option output="Deliv/Release/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Release/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-O2" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<Compiler>
<Add option="-Wall" />
<Add option="-fexceptions" />
</Compiler>
<Unit filename="LeapYear.cpp" />
<Unit filename="LeapYear.h" />
<Unit filename="LeapYearTest.cpp" />
<Unit filename="main.cpp" />
<Extensions>
<envvars />
<code_completion />
<lib_finder disable_auto="1" />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

The main source file : main.cpp
int main()
{
return 0;
}

The header exporting our powerful function : LeapYear.h

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

#endif // LEAPYEAR_H_INCLUDED

And the implementation of the leap year logic : LeapYear.cpp

#include "LeapYear.h"

And finishing with the source file for the tests : LeapYearTest.cpp (currently) empty

We can already build the project, we have a nice little program that does .... nothing.

Time to move to the next section, a little word about Test Driven Development.

== Test Driven Development ==
This is a practice where new code is only added to make a failing test pass. And one only adds the code needed to make that test pass. Once that is done, a new test is added that will check the next functionality to add.
On this really simple example we will more or less practice some TDD.

So get ready, it's time for LeapYear-Step1.

== LeapYear-Step1 ==
We will turn our main.cpp into the guy in charge to carry out the tests, all we need to do is change the contents of main.cpp into this :

<source lang="cpp">
#include "UnitTest++.h"

int main()
{
return UnitTest::RunAllTests();
}

</source>
And add '''../UnitTest++/src''' to the compiler search directories on the project level of our LeapYear project.
And add '''../UnitTest++/Deliv/Release/libUnitTest++.a''' to the link libraries of the project

Why : well we need to link with the framework and we need to include the UnitTest++ header so we can use it's functionalities.

The line '''UnitTest::RunAllTests()''' will make sure all test encountered in our sources will be carried out.
We don't have any tests yet, nor any functionality, but go ahead build the project and run it.
This is the output :

Success: 0 tests passed
Test time: 0.00 seconds.

Great : success, but no tests yet. Well it's a start.
Time to move forward, and write our first test.

== LeapYear-Step2 ==
Test, test, but there's nothing to test. Yes, absolutely. Let's think of a test, a test that will help us in the design. Now that's a good idea. Suppose I would be the user of the uplifting problem solving leap year checking library/component ... hmmm modesty first : leap year checking '''function'''.
How would I like that function to look.
<source lang="cpp">
bool IsLeapYear(int Year);
</source>
Yes that seems acceptable.
So let's write a test that will call that method.
We do that by adding the following code to LeapYearTest.cpp

<source lang="cpp">
#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

}

</source>
Things to note :
* we include the unit test header
* it is good to put the tests in nameless namespace (will be explained later on)
* we use the TEST macro, the argument is the name of the test : OurFirstTest
* we use CHECK_EQUAL to check if the expected result (the first argument) matches the computed result (the second argument)

Time to build. Woooooops errors. The tests fails completely, it does not even build. Time to add the code needed.
In order to compiler the test file, we need to include the LeapYear.h header and have that header export our function.
Our LeapYear header will look like this now (don't forget the include in the test file, it is not shown here) :

<source lang="cpp">
#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

bool IsLeapYear(int Year);

#endif // LEAPYEAR_H_INCLUDED

</source>

At least now it compiles, but it doesn't link yet. Duh, that because we don't have an implementation yet.
Time to provide the bare minimum of code to make the test pass.
So we change the LeapYear.cpp into :

<source lang="cpp">
#include "LeapYear.h"

bool IsLeapYear(int /*Year*/)
{
return true;
}

</source>
Build it, run it. Yes, we have one test passed.
Great. Let's move on.

== LeapYear-Step3 ==
Anyone having the feeling we are cheating. Well the user does not know how we wrote our code on the inside. So just to be sure the user (we) adds the following test, ending up in :

<source lang="cpp">
#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

TEST(OurSecondTest)
{
const bool Result = IsLeapYear(1973);
CHECK_EQUAL(false, Result);
}

}

</source>
Building is already no issue any more, we can run it. Oh boy, a test is failing.
The framework tell us something like this :
<filename>:<Line>: error: Failure in OurSecondTest: Expected 0 but was 1
FAILURE: 1 out of 2 tests failed (1 failures)
Test time: 0.00 seconds.

So we are informed of the line where the failing tests occurs, next to that it tells us what it was expecting and what the actual outcome was. And it presents a resume of the total number of tests, and how many that failed. For you scripting hackers note that FAILURE != SUCCESS.

It seems we should do some more effort and implement some real logic.

== LeapYear-Step4 ==
Let's keep it taking one step at a time. Let's start by implementing the 'divisible by 4' logic. That will already solve our tests.
So our LeapYear.cpp will now look like this :

<source lang="cpp">
#include "LeapYear.h"

namespace
{

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year);
}

</source>
Build, run. All tests pass. Life is great.

But those changing requirements, always the change of the requirements. Years that can be divided by 100 should not be considered as a leap year.

Time for our next step.

== LeapYear-Step5 ==
We add a new test for checking for example the year 1900.

<source lang="cpp">
TEST(DivisableBy100)
{
const bool Result = IsLeapYear(1900);
CHECK_EQUAL(false, Result);
}
</source>

Build and run the tests. It will fail. So time to add the minimum code needed to make this test pass.
This will change our LeapYear.cpp into :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year) && !IsDivisableBy100(Year);
}

</source>

Build and run the tests, yes : success. All 3 tests pass.

It seems life might be great again ...

Wrong, someone just added the following test :

<source lang="cpp">
TEST(DivisableBy400)
{
const bool Result = IsLeapYear(2000);
CHECK_EQUAL(true, Result);
}
</source>

And we once again have a failing test.

Time for the next step.

== LeapYear-Step6 ==
We should add logic to deal with years that can be divided by 400, since those are leap years.
We change our LeapYear.cpp into this :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy400(int Year)
{
return (Year%400) == 0;
}

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
const bool LeapYear = IsDivisableBy400(Year) ||
(IsDivisableBy4(Year) && !IsDivisableBy100(Year));
return LeapYear;
}

</source>

And once again everything works OK.
And it seems all the logical rules have been implemented.
This one is ready for shipping, and till the end of time we have our tests that can be run whenever we want (more on this later, we'd prefer this to be done automatically) to ensure we never break anything.

== Increase the user experience ==
There are a few areas where we can increase the user experience.
When a unit test fails the framework tell use on which line in the the code his happens.
That's excellent.
BUT we see this information in a console/shell windows. So we need to find that window, read the issues, remember them and then go find our test source files and navigate manually to the offending line. This works but is very cumbersome.
We want this to be a no-brainer, and have these steps being carried out for us.

Well, didn't we say life is great, Code::Blocks and UnitTest+= to the rescue. The error/warning output of the framework is in the gcc format. That means Code::Blocks can parse it.
One restriction Code::Blocks can parse it during the 'build process'. But currently the build procss stops after the unit test executable is build, and only then we run the test executable (manually).
Solution have Code::Blocks run the test executable as a post-build step. Pre-build and post-build steps are part of the build process !
Important consequence : if you want to debug something, the debugger will only kick off after Code::Blocks was able to carry out a successful build (including the pre/post builds steps). Therefor it is not wise to have the unit test executable being carried out as a post-bild step of the 'Debug' target. But as a post-build step of the Release target, our goal is met.

Adjust the target settings for the 'Release' target [Build Options -> select Release target -> Pre/Post-build steps -> Post-build steps text field] and add the following '''$exe_output'''. you can tick the 'Always execute' if you want.

Now build your Release target, and look at what shows up in the 'Build Log' tab in Code::Blocks.
This is my output :
<pre>

-------------- Build: Release in LeapYear ---------------

[ 25.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/LeapYear.cpp -o Deliv/Release/LeapYear.o
[ 50.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/LeapYearTest.cpp -o Deliv/Release/LeapYearTest.o
[ 75.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/main.cpp -o Deliv/Release/main.o
[100.0%] g++ -o Deliv/Release/LeapYear Deliv/Release/LeapYear.o Deliv/Release/LeapYearTest.o Deliv/Release/main.o -s ../UnitTest++/Deliv/Release/libUnitTest++.a
Output size is 23.28 KB
[100.0%] Running target post-build steps
Deliv/Release/LeapYear
Success: 4 tests passed.
Test time: 0.00 seconds.
Process terminated with status 0 (0 minutes, 2 seconds)
0 errors, 0 warnings
Build log saved as:
file:///home/lieven/Projects/UnitTestArticle/LeapYear/LeapYear_build_log.html
</pre>

We see that the unit test has been carried out, automatically.

Let's demonstrate that upon a failed test, Code::Blocks will jump to the offending line.
Change the latest test, the one checking on the year 2000 : change 2000 to 2001.
And build : Code::Blocks will jump to the offending line, and shows an entry in the "Build messages" tab (error: Failure in DivisableBy400: Expected 1 but was 0), just like for a regular compiler warning/error.
In the "Build" tab, we now find something like (red colored since it is an error) :
<pre>

-------------- Build: Release in LeapYear ---------------

[ 50.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/LeapYearTest.cpp -o Deliv/Release/LeapYearTest.o
[100.0%] g++ -o Deliv/Release/LeapYear Deliv/Release/LeapYear.o Deliv/Release/LeapYearTest.o Deliv/Release/main.o -s ../UnitTest++/Deliv/Release/libUnitTest++.a
Output size is 23.28 KB
[100.0%] Running target post-build steps
Deliv/Release/LeapYear
/home/lieven/Projects/UnitTestArticle/LeapYear/LeapYearTest.cpp:28: error: Failure in DivisableBy400: Expected 1 but was 0
FAILURE: 1 out of 4 tests failed (1 failures).
Test time: 0.00 seconds.
Process terminated with status 1 (0 minutes, 1 seconds)
1 errors, 0 warnings
Build log saved as:
file:///home/lieven/Projects/UnitTestArticle/LeapYear/LeapYear_build_log.html
</pre>

Voila, we have increased the user experience.
Time to readjust the final test, 2001 becomes 2000 again ;-)

== Further automation ==
You can create a script that calls Code::Blocks on the command line and passes it our LeapYear.cbp project file, and it will build both targets (Debug/Release) and run the test, since it is a post-build step for the 'Release' target.
Bye bye funky makefiles, welcome Code::Blocks as your build system.

== More to come ==
More examples will be added, showcasing 'fixtures' (setup/teardown), some more CHECK macros of UnitTest++. In case you have some tips/ideas, drop me a PM in the forum.
On the planning is a full conversion of the Money example, but all with gcc and Code::Blocks instead of the crazy Microsoft IDE.

UnitTesting

2009-09-09T19:39:10Z

Killerbot: /* Our first test project environment */

This document is under development by killerbot. Starting from 7 September 2009.

== Introduction ==
This document will describe how unit testing can be combined with the Code::Blocks IDE. It will give a hands-on example on a unit testing framework and how it can be used with Code::Blocks.

== What is Unit Testing ==
Simply put Unit Testing is the discipline and best practice of writing and running little test programs that test little units of code.
Such a unit can be :
* a class
* a free function
* an interface
* ...
There are several unit test frameworks available to help you write, deploy, manage your unit tests. The most famous family is the xUnit framework, and some of it's descendants.

== Why Unit Testing ==
Well we write code that implements some functionality. We need a way to check and prove that the implementation is correct. Therefor we need tests. We need tests on the application level, at the integration level of different components, classes, interfaces. But we also need tests for the smallest building blocks, the units.
We also wans these tests to run very quickly. That way we can run the tests often, manually or automated.
These tests will also be our safeguards during refactoring of the code, extending the code or whatever maintenance tasks we carry out on the code.
These tests will also make us think of how our class, method, ... will be used. Since the test can be seen as a user of our code. Thanks to this, thinking about the tests before implementing the functionality can help us in the design : emergent design.
It will help us to avoid creating big classes, complex functions. We will only write the methods that are really needed, and no methods that we think might (n)ever be useful in the future. We are no good future tellers ! Those 'might be needed' methods and their tests are just a waste of time. Extending, refactoring will be done when it is actually needed, and at that time we have our unit tests to ensure we don't break any existing code.

Other times to add new unit tests are typically when a bug is discovered. Write a unit test to reproduce the bug, fix the code, and from now on the new unit test will watch your back so the bug won't reappear.

Unit test are also a good place of documentation. The little tests show how the class or method is used.
The code documents itself.

So the benefits are :
* better design
* prove of your code
* safe guard during code maintenance (refactoring, extensions)
* documentation
* ...

== Unit Test frameworks ==
When writing unit tests, one will create a lot of similar code. Since unit tests are nothing more then little programs, several tasks will be repeated, setting up the test environment, create your class, call a method, verify it's result, write out an error message when the test fails, preferably specifying what the wrong outcome was, and what the expected result is.
All these repetitive chores are taken care of by the frame work so the developer can focus on the real code of the test.
This document will use a small but very effective framework for the C++ language. It is called UnitTest++. It's homepage is at : [http://unittest-cpp.sourceforge.net/ UnitTest++].
You can download it directly at this [http://sourceforge.net/projects/unittest-cpp/files/UnitTest%2B%2B/1.4/unittest-cpp-1.4.zip/download link]. At the time of writing the latest version is 1.4.

== Setup our environment ==
Let's create a directory on our PC in which we will cary out our experiments. I will refer to this directory from now on as <TestPit>. For my laptop on which I am writing this article, that will be /home/lieven/Projects/UnitTestArticle. Note that everything we will do, works on linux and on windows!
Download the "unittest-cpp-1.4.zip" file from the link specified above. Extract it in the <TestPit> directory. All the files will end up in the <TestPit>/UnitTest++ directory.

== Build UnitTest++ ==
After the extracted the zip archive we have a directory structure like this :
<pre>
<TestPit>/UnitTest++
|
+docs
|
+src
</pre>
The files in the UnitTest++ directory are of little use for us, since they bring project files for some bizarre Microsoft IDE ;-) .
We will create our own Code::Blocks project to build the UnitTest++ framework.

Why do we need to build something ? Well as said, the framework will do a lot of chores for us, those chores are implemented by code, that code is the framework. We will build to framework into a static library, and for every unit test (or set of unit tests) we create a little (console/shell) program with the test code we wrote, which will link with the static library to obtain a unit test executable, driven by the framework.

We will put our Code::Blocks project file in a nice structured directory tree, therefor let's create a 'Project' subdirectory in the <TestPit>/UnitTest++ directory.

In there create a new file with the name "UnitTest++.cbp".
Give that file the following content :

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="UnitTest++" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option platforms="Windows;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option platforms="Windows;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
<Target title="Debug(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<VirtualTargets>
<Add alias="All" targets="Debug;Release;Debug(linux);Release(linux);" />
</VirtualTargets>
<Unit filename="../src/AssertException.cpp" />
<Unit filename="../src/AssertException.h" />
<Unit filename="../src/CheckMacros.h" />
<Unit filename="../src/Checks.cpp" />
<Unit filename="../src/Checks.h" />
<Unit filename="../src/Config.h" />
<Unit filename="../src/CurrentTest.cpp" />
<Unit filename="../src/CurrentTest.h" />
<Unit filename="../src/DeferredTestReporter.cpp" />
<Unit filename="../src/DeferredTestReporter.h" />
<Unit filename="../src/DeferredTestResult.cpp" />
<Unit filename="../src/DeferredTestResult.h" />
<Unit filename="../src/ExecuteTest.h" />
<Unit filename="../src/MemoryOutStream.cpp" />
<Unit filename="../src/MemoryOutStream.h" />
<Unit filename="../src/Posix/SignalTranslator.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/SignalTranslator.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/ReportAssert.cpp" />
<Unit filename="../src/ReportAssert.h" />
<Unit filename="../src/Test.cpp" />
<Unit filename="../src/Test.h" />
<Unit filename="../src/TestDetails.cpp" />
<Unit filename="../src/TestDetails.h" />
<Unit filename="../src/TestList.cpp" />
<Unit filename="../src/TestList.h" />
<Unit filename="../src/TestMacros.h" />
<Unit filename="../src/TestReporter.cpp" />
<Unit filename="../src/TestReporter.h" />
<Unit filename="../src/TestReporterStdout.cpp" />
<Unit filename="../src/TestReporterStdout.h" />
<Unit filename="../src/TestResults.cpp" />
<Unit filename="../src/TestResults.h" />
<Unit filename="../src/TestRunner.cpp" />
<Unit filename="../src/TestRunner.h" />
<Unit filename="../src/TestSuite.h" />
<Unit filename="../src/TimeConstraint.cpp" />
<Unit filename="../src/TimeConstraint.h" />
<Unit filename="../src/TimeHelpers.h" />
<Unit filename="../src/UnitTest++.h" />
<Unit filename="../src/Win32/TimeHelpers.cpp">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/Win32/TimeHelpers.h">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/XmlTestReporter.cpp" />
<Unit filename="../src/XmlTestReporter.h" />
<Extensions>
<envvars />
<code_completion />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

Some things to note about the content of the project file, the power of Code::Blocks.
* there are 4 targets : Debug/Release for Windows and Debug/Release for linux [yes : 1 project file that allows building on linux and on windows]
* some files are only part of the linux targets, some only for the windows targets

But before we build, let's modify some source files (not really needed, but I prefer to have warning free compilations). These are the changes I carried out :
* ReportAssert.cpp : #include "ReportAssert.h"
* win32/TimeHelpers.cpp : first the m_threadHandle and then the m_startTime in the initializerlist

Next open up this project file in Code::Blocks and build the debug and release target. From now one we will only use the Release target, we go for speed ;-)

The result of the build process will show up in subdirectories of the new 'Deliv' subdirectory of <testPit>/UnitTest++ : '''<testPit>/UnitTest++/Deliv/Release/libUnitTest++.a'''

Alright, we have build the unit test framework in a platform independent way, no silly makefiles, no obscure M$ IDE, good old super Code::Blocks. It is time to write some code so we have something to unit test.

In the first example we will create a simple free function that checks if a given year is a leap year or not.

The business logic is as follows : a year is a leap year when it can be divided by 4, unless it can be divided by 100. But in case it can be divided by 400, then again it is a leap year.

In the next section we will first setup a Code::Blocks project containing both the 'functionality files, and the unit test files. Typically one will package several functionality files into a static library and create a unit test project that tests all the class/functionalities in that library package, also called a component. That is we have a component (whose deliverable is the static library, and we have a unit test project that tests the entire component).

== Our first test project environment ==
Let's create a new directory in our <TestPit> : <TestPit>/LeapYear.
For the simplicity we will put the project file and the source file all together in this directory. Normally we would work in a more structured way, but in a demo article we have some artistic freedom ;-)
Next you can create with the Code::Block's wizard a new console project in the LeapYear directory. Or you can create the following 5 files and give the the contents as specified below. Note that this demo works on linux and on windows, everything is still completely platform independent. Long Live Code::Blocks.

The project file : LeapYear.cbp (the one below already contains the 4 source files, in case you use the wizard you have to add the LeapYear.h/cpp and LeapYearTest.cpp files to the project)

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="LeapYear" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option output="Deliv/Debug/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Debug/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option output="Deliv/Release/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Release/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-O2" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<Compiler>
<Add option="-Wall" />
<Add option="-fexceptions" />
</Compiler>
<Unit filename="LeapYear.cpp" />
<Unit filename="LeapYear.h" />
<Unit filename="LeapYearTest.cpp" />
<Unit filename="main.cpp" />
<Extensions>
<envvars />
<code_completion />
<lib_finder disable_auto="1" />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

The main source file : main.cpp
int main()
{
return 0;
}

The header exporting our powerful function : LeapYear.h

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

#endif // LEAPYEAR_H_INCLUDED

And the implementation of the leap year logic : LeapYear.cpp

#include "LeapYear.h"

And finishing with the source file for the tests : LeapYearTest.cpp (currently) empty

We can already build the project, we have a nice little program that does .... nothing.

Time to move to the next section, a little word about Test Driven Development.

== Test Driven Development ==
This is a practice where new code is only added to make a failing test pass. And one only adds the code needed to make that test pass. Once that is done, a new test is added to will check the next functionality to add.
On this really simple example we will more or less practice some TDD.

So get ready, it's time for LeapYear-Step1.

== LeapYear-Step1 ==
We will turn our main.cpp into the guy in charge to carry out the tests, all we need to do is change the contents of main.cpp into this :

<source lang="cpp">
#include "UnitTest++.h"

int main()
{
return UnitTest::RunAllTests();
}

</source>
And add '''../UnitTest++/src''' to the compiler search directories on the project level of our LeapYear project.
And add '''../UnitTest++/Deliv/Release/libUnitTest++.a''' to the link libraries of the project

Why : well we need to link with the framework and we need to include the UnitTest++ header so we can use it's functionalities.

The line '''UnitTest::RunAllTests()''' will make sure all test encountered in our sources will be carried out.
We don't have any tests yet, nor any functionality, but go ahead build the project and run it.
This is the output :

Success: 0 tests passed
Test time: 0.00 seconds.

Great : success, but no tests yet. Well it's a start.
Time to move forward, and write our first test.

== LeapYear-Step2 ==
Test, test, but there's nothing to test. Yes, absolutely. Let's think of a test, a test that will help us in the design. Now that's a good idea. Suppose I would be the user of the uplifting problem solving leap year checking library/component ... hmmm modesty first : leap year checking '''function'''.
How would I like that function to look.
<source lang="cpp">
bool IsLeapYear(int Year);
</source>
Yes that seems acceptable.
So let's write a test that will call that method.
We do that by adding the following code to LeapYearTest.cpp

<source lang="cpp">
#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

}

</source>
Things to note :
* we include the unit test header
* it is good to put the tests in nameless namespace (will be explained later on)
* we use the TEST macro, the argument is the name of the test : OurFirstTest
* we use CHECK_EQUAL to check if the expected result (the first argument) matches the computed result (the second argument)

Time to build. Woooooops errors. The tests fails completely, it does not even build. Time to add the code needed.
In order to compiler the test file, we need to include the LeapYear.h header and have that header export our function.
Our LeapYear header will look like this now (don't forget the include in the test file, it is not shown here) :

<source lang="cpp">
#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

bool IsLeapYear(int Year);

#endif // LEAPYEAR_H_INCLUDED

</source>

At least now it compiles, but it doesn't link yet. Duh, that because we don't have an implementation yet.
Time to provide the bare minimum of code to make the test pass.
So we change the LeapYear.cpp into :

<source lang="cpp">
#include "LeapYear.h"

bool IsLeapYear(int /*Year*/)
{
return true;
}

</source>
Build it, run it. Yes, we have one test passed.
Great. Let's move on.

== LeapYear-Step3 ==
Anyone having the feeling we are cheating. Well the user does not know how we wrote our code on the inside. So just to be sure the user (we) adds the following test, ending up in :

<source lang="cpp">
#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

TEST(OurSecondTest)
{
const bool Result = IsLeapYear(1973);
CHECK_EQUAL(false, Result);
}

}

</source>
Building is already no issue any more, we can run it. Oh boy, a test is failing.
The framework tell us something like this :
<filename>:<Line>: error: Failure in OurSecondTest: Expected 0 but was 1
FAILURE: 1 out of 2 tests failed (1 failures)
Test time: 0.00 seconds.

So we are informed of the line where the failing tests occurs, next to that it tells us what it was expecting and what the actual outcome was. And it presents a resume of the total number of tests, and how many that failed. For you scripting hackers note that FAILURE != SUCCESS.

It seems we should do some more effort and implement some real logic.

== LeapYear-Step4 ==
Let's keep it taking one step at a time. Let's start by implementing the 'divisible by 4' logic. That will already solve our tests.
So our LeapYear.cpp will now look like this :

<source lang="cpp">
#include "LeapYear.h"

namespace
{

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year);
}

</source>
Build, run. All tests pass. Life is great.

But those changing requirements, always the change of the requirements. Years that can be divided by 100 should not be considered as a leap year.

Time for our next step.

== LeapYear-Step5 ==
We add a new test for checking for example the year 1900.

<source lang="cpp">
TEST(DivisableBy100)
{
const bool Result = IsLeapYear(1900);
CHECK_EQUAL(false, Result);
}
</source>

Build and run the tests. It will fail. So time to add the minimum code needed to make this test pass.
This will change our LeapYear.cpp into :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year) && !IsDivisableBy100(Year);
}

</source>

Build and run the tests, yes : success. All 3 tests pass.

It seems life might be great again ...

Wrong, someone just added the following test :

<source lang="cpp">
TEST(DivisableBy400)
{
const bool Result = IsLeapYear(2000);
CHECK_EQUAL(true, Result);
}
</source>

And we once again have a failing test.

Time for the next step.

== LeapYear-Step6 ==
We should add logic to deal with years that can be divided by 400, since those are leap years.
We change our LeapYear.cpp into this :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy400(int Year)
{
return (Year%400) == 0;
}

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
const bool LeapYear = IsDivisableBy400(Year) ||
(IsDivisableBy4(Year) && !IsDivisableBy100(Year));
return LeapYear;
}

</source>

And once again everything works OK.
And it seems all the logical rules have been implemented.
This one is ready for shipping, and till the end of time we have our tests that can be run whenever we want (more on this later, we'd prefer this to be done automatically) to ensure we never break anything.

== Increase the user experience ==
There are a few areas where we can increase the user experience.
When a unit test fails the framework tell use on which line in the the code his happens.
That's excellent.
BUT we see this information in a console/shell windows. So we need to find that window, read the issues, remember them and then go find our test source files and navigate manually to the offending line. This works but is very cumbersome.
We want this to be a no-brainer, and have these steps being carried out for us.

Well, didn't we say life is great, Code::Blocks and UnitTest+= to the rescue. The error/warning output of the framework is in the gcc format. That means Code::Blocks can parse it.
One restriction Code::Blocks can parse it during the 'build process'. But currently the build procss stops after the unit test executable is build, and only then we run the test executable (manually).
Solution have Code::Blocks run the test executable as a post-build step. Pre-build and post-build steps are part of the build process !
Important consequence : if you want to debug something, the debugger will only kick off after Code::Blocks was able to carry out a successful build (including the pre/post builds steps). Therefor it is not wise to have the unit test executable being carried out as a post-bild step of the 'Debug' target. But as a post-build step of the Release target, our goal is met.

Adjust the target settings for the 'Release' target [Build Options -> select Release target -> Pre/Post-build steps -> Post-build steps text field] and add the following '''$exe_output'''. you can tick the 'Always execute' if you want.

Now build your Release target, and look at what shows up in the 'Build Log' tab in Code::Blocks.
This is my output :
<pre>

-------------- Build: Release in LeapYear ---------------

[ 25.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/LeapYear.cpp -o Deliv/Release/LeapYear.o
[ 50.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/LeapYearTest.cpp -o Deliv/Release/LeapYearTest.o
[ 75.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/main.cpp -o Deliv/Release/main.o
[100.0%] g++ -o Deliv/Release/LeapYear Deliv/Release/LeapYear.o Deliv/Release/LeapYearTest.o Deliv/Release/main.o -s ../UnitTest++/Deliv/Release/libUnitTest++.a
Output size is 23.28 KB
[100.0%] Running target post-build steps
Deliv/Release/LeapYear
Success: 4 tests passed.
Test time: 0.00 seconds.
Process terminated with status 0 (0 minutes, 2 seconds)
0 errors, 0 warnings
Build log saved as:
file:///home/lieven/Projects/UnitTestArticle/LeapYear/LeapYear_build_log.html
</pre>

We see that the unit test has been carried out, automatically.

Let's demonstrate that upon a failed test, Code::Blocks will jump to the offending line.
Change the latest test, the one checking on the year 2000 : change 2000 to 2001.
And build : Code::Blocks will jump to the offending line, and shows an entry in the "Build messages" tab (error: Failure in DivisableBy400: Expected 1 but was 0), just like for a regular compiler warning/error.
In the "Build" tab, we now find something like (red colored since it is an error) :
<pre>

-------------- Build: Release in LeapYear ---------------

[ 50.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/LeapYearTest.cpp -o Deliv/Release/LeapYearTest.o
[100.0%] g++ -o Deliv/Release/LeapYear Deliv/Release/LeapYear.o Deliv/Release/LeapYearTest.o Deliv/Release/main.o -s ../UnitTest++/Deliv/Release/libUnitTest++.a
Output size is 23.28 KB
[100.0%] Running target post-build steps
Deliv/Release/LeapYear
/home/lieven/Projects/UnitTestArticle/LeapYear/LeapYearTest.cpp:28: error: Failure in DivisableBy400: Expected 1 but was 0
FAILURE: 1 out of 4 tests failed (1 failures).
Test time: 0.00 seconds.
Process terminated with status 1 (0 minutes, 1 seconds)
1 errors, 0 warnings
Build log saved as:
file:///home/lieven/Projects/UnitTestArticle/LeapYear/LeapYear_build_log.html
</pre>

Voila, we have increased the user experience.
Time to readjust the final test, 2001 becomes 2000 again ;-)

== Further automation ==
You can create a script that calls Code::Blocks on the command line and passes it our LeapYear.cbp project file, and it will build both targets (Debug/Release) and run the test, since it is a post-build step for the 'Release' target.
Bye bye funky makefiles, welcome Code::Blocks as your build system.

== More to come ==
More examples will be added, showcasing 'fixtures' (setup/teardown), some more CHECK macros of UnitTest++. In case you have some tips/ideas, drop me a PM in the forum.
On the planning is a full conversion of the Money example, but all with gcc and Code::Blocks instead of the crazy Microsoft IDE.

UnitTesting

2009-09-09T19:36:34Z

Killerbot: /* Build UnitTest++ */

This document is under development by killerbot. Starting from 7 September 2009.

== Introduction ==
This document will describe how unit testing can be combined with the Code::Blocks IDE. It will give a hands-on example on a unit testing framework and how it can be used with Code::Blocks.

== What is Unit Testing ==
Simply put Unit Testing is the discipline and best practice of writing and running little test programs that test little units of code.
Such a unit can be :
* a class
* a free function
* an interface
* ...
There are several unit test frameworks available to help you write, deploy, manage your unit tests. The most famous family is the xUnit framework, and some of it's descendants.

== Why Unit Testing ==
Well we write code that implements some functionality. We need a way to check and prove that the implementation is correct. Therefor we need tests. We need tests on the application level, at the integration level of different components, classes, interfaces. But we also need tests for the smallest building blocks, the units.
We also wans these tests to run very quickly. That way we can run the tests often, manually or automated.
These tests will also be our safeguards during refactoring of the code, extending the code or whatever maintenance tasks we carry out on the code.
These tests will also make us think of how our class, method, ... will be used. Since the test can be seen as a user of our code. Thanks to this, thinking about the tests before implementing the functionality can help us in the design : emergent design.
It will help us to avoid creating big classes, complex functions. We will only write the methods that are really needed, and no methods that we think might (n)ever be useful in the future. We are no good future tellers ! Those 'might be needed' methods and their tests are just a waste of time. Extending, refactoring will be done when it is actually needed, and at that time we have our unit tests to ensure we don't break any existing code.

Other times to add new unit tests are typically when a bug is discovered. Write a unit test to reproduce the bug, fix the code, and from now on the new unit test will watch your back so the bug won't reappear.

Unit test are also a good place of documentation. The little tests show how the class or method is used.
The code documents itself.

So the benefits are :
* better design
* prove of your code
* safe guard during code maintenance (refactoring, extensions)
* documentation
* ...

== Unit Test frameworks ==
When writing unit tests, one will create a lot of similar code. Since unit tests are nothing more then little programs, several tasks will be repeated, setting up the test environment, create your class, call a method, verify it's result, write out an error message when the test fails, preferably specifying what the wrong outcome was, and what the expected result is.
All these repetitive chores are taken care of by the frame work so the developer can focus on the real code of the test.
This document will use a small but very effective framework for the C++ language. It is called UnitTest++. It's homepage is at : [http://unittest-cpp.sourceforge.net/ UnitTest++].
You can download it directly at this [http://sourceforge.net/projects/unittest-cpp/files/UnitTest%2B%2B/1.4/unittest-cpp-1.4.zip/download link]. At the time of writing the latest version is 1.4.

== Setup our environment ==
Let's create a directory on our PC in which we will cary out our experiments. I will refer to this directory from now on as <TestPit>. For my laptop on which I am writing this article, that will be /home/lieven/Projects/UnitTestArticle. Note that everything we will do, works on linux and on windows!
Download the "unittest-cpp-1.4.zip" file from the link specified above. Extract it in the <TestPit> directory. All the files will end up in the <TestPit>/UnitTest++ directory.

== Build UnitTest++ ==
After the extracted the zip archive we have a directory structure like this :
<pre>
<TestPit>/UnitTest++
|
+docs
|
+src
</pre>
The files in the UnitTest++ directory are of little use for us, since they bring project files for some bizarre Microsoft IDE ;-) .
We will create our own Code::Blocks project to build the UnitTest++ framework.

Why do we need to build something ? Well as said, the framework will do a lot of chores for us, those chores are implemented by code, that code is the framework. We will build to framework into a static library, and for every unit test (or set of unit tests) we create a little (console/shell) program with the test code we wrote, which will link with the static library to obtain a unit test executable, driven by the framework.

We will put our Code::Blocks project file in a nice structured directory tree, therefor let's create a 'Project' subdirectory in the <TestPit>/UnitTest++ directory.

In there create a new file with the name "UnitTest++.cbp".
Give that file the following content :

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="UnitTest++" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option platforms="Windows;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option platforms="Windows;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
<Target title="Debug(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<VirtualTargets>
<Add alias="All" targets="Debug;Release;Debug(linux);Release(linux);" />
</VirtualTargets>
<Unit filename="../src/AssertException.cpp" />
<Unit filename="../src/AssertException.h" />
<Unit filename="../src/CheckMacros.h" />
<Unit filename="../src/Checks.cpp" />
<Unit filename="../src/Checks.h" />
<Unit filename="../src/Config.h" />
<Unit filename="../src/CurrentTest.cpp" />
<Unit filename="../src/CurrentTest.h" />
<Unit filename="../src/DeferredTestReporter.cpp" />
<Unit filename="../src/DeferredTestReporter.h" />
<Unit filename="../src/DeferredTestResult.cpp" />
<Unit filename="../src/DeferredTestResult.h" />
<Unit filename="../src/ExecuteTest.h" />
<Unit filename="../src/MemoryOutStream.cpp" />
<Unit filename="../src/MemoryOutStream.h" />
<Unit filename="../src/Posix/SignalTranslator.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/SignalTranslator.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/ReportAssert.cpp" />
<Unit filename="../src/ReportAssert.h" />
<Unit filename="../src/Test.cpp" />
<Unit filename="../src/Test.h" />
<Unit filename="../src/TestDetails.cpp" />
<Unit filename="../src/TestDetails.h" />
<Unit filename="../src/TestList.cpp" />
<Unit filename="../src/TestList.h" />
<Unit filename="../src/TestMacros.h" />
<Unit filename="../src/TestReporter.cpp" />
<Unit filename="../src/TestReporter.h" />
<Unit filename="../src/TestReporterStdout.cpp" />
<Unit filename="../src/TestReporterStdout.h" />
<Unit filename="../src/TestResults.cpp" />
<Unit filename="../src/TestResults.h" />
<Unit filename="../src/TestRunner.cpp" />
<Unit filename="../src/TestRunner.h" />
<Unit filename="../src/TestSuite.h" />
<Unit filename="../src/TimeConstraint.cpp" />
<Unit filename="../src/TimeConstraint.h" />
<Unit filename="../src/TimeHelpers.h" />
<Unit filename="../src/UnitTest++.h" />
<Unit filename="../src/Win32/TimeHelpers.cpp">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/Win32/TimeHelpers.h">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/XmlTestReporter.cpp" />
<Unit filename="../src/XmlTestReporter.h" />
<Extensions>
<envvars />
<code_completion />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

Some things to note about the content of the project file, the power of Code::Blocks.
* there are 4 targets : Debug/Release for Windows and Debug/Release for linux [yes : 1 project file that allows building on linux and on windows]
* some files are only part of the linux targets, some only for the windows targets

But before we build, let's modify some source files (not really needed, but I prefer to have warning free compilations). These are the changes I carried out :
* ReportAssert.cpp : #include "ReportAssert.h"
* win32/TimeHelpers.cpp : first the m_threadHandle and then the m_startTime in the initializerlist

Next open up this project file in Code::Blocks and build the debug and release target. From now one we will only use the Release target, we go for speed ;-)

The result of the build process will show up in subdirectories of the new 'Deliv' subdirectory of <testPit>/UnitTest++ : '''<testPit>/UnitTest++/Deliv/Release/libUnitTest++.a'''

Alright, we have build the unit test framework in a platform independent way, no silly makefiles, no obscure M$ IDE, good old super Code::Blocks. It is time to write some code so we have something to unit test.

In the first example we will create a simple free function that checks if a given year is a leap year or not.

The business logic is as follows : a year is a leap year when it can be divided by 4, unless it can be divided by 100. But in case it can be divided by 400, then again it is a leap year.

In the next section we will first setup a Code::Blocks project containing both the 'functionality files, and the unit test files. Typically one will package several functionality files into a static library and create a unit test project that tests all the class/functionalities in that library package, also called a component. That is we have a component (whose deliverable is the static library, and we have a unit test project that tests the entire component).

== Our first test project environment ==
Let's create a new directory in our <TestPit> : <TestPit>/LeapYear.
For the simplicity we will put the project file and the source file all together in this directory. Normally we would work in a more structured way, but in a demo article we have some artistic freedom ;-)
Next you can create with the Code::Block's wizard a new console project in the LeapYear directory. Or you can create the following 5 files and give the the contents as specified below. Note that this demo works on linux and on windows, everything is still completely platform independent. Long Live Code::Blocks.

The project file : LeapYear.cbp (the one below already contains the 5 source files, in case you use the wizard you have to add the LeapYear.h/cpp and LeapYearTest.cpp files to the project)

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="LeapYear" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option output="Deliv/Debug/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Debug/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option output="Deliv/Release/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Release/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-O2" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<Compiler>
<Add option="-Wall" />
<Add option="-fexceptions" />
</Compiler>
<Unit filename="LeapYear.cpp" />
<Unit filename="LeapYear.h" />
<Unit filename="LeapYearTest.cpp" />
<Unit filename="main.cpp" />
<Extensions>
<envvars />
<code_completion />
<lib_finder disable_auto="1" />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

The main source file : main.cpp
int main()
{
return 0;
}

The header exporting our powerful function : LeapYear.h

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

#endif // LEAPYEAR_H_INCLUDED

And the implementation of the leap year logic : LeapYear.cpp

#include "LeapYear.h"

And finishing with the source file for the tests : LeapYearTest.cpp (currently) empty

We can already build the project, we have a nice little program that does .... nothing.

Time to move to the next section, a little word about Test Driven Development.

== Test Driven Development ==
This is a practice where new code is only added to make a failing test pass. And one only adds the code needed to make that test pass. Once that is done, a new test is added to will check the next functionality to add.
On this really simple example we will more or less practice some TDD.

So get ready, it's time for LeapYear-Step1.

== LeapYear-Step1 ==
We will turn our main.cpp into the guy in charge to carry out the tests, all we need to do is change the contents of main.cpp into this :

<source lang="cpp">
#include "UnitTest++.h"

int main()
{
return UnitTest::RunAllTests();
}

</source>
And add '''../UnitTest++/src''' to the compiler search directories on the project level of our LeapYear project.
And add '''../UnitTest++/Deliv/Release/libUnitTest++.a''' to the link libraries of the project

Why : well we need to link with the framework and we need to include the UnitTest++ header so we can use it's functionalities.

The line '''UnitTest::RunAllTests()''' will make sure all test encountered in our sources will be carried out.
We don't have any tests yet, nor any functionality, but go ahead build the project and run it.
This is the output :

Success: 0 tests passed
Test time: 0.00 seconds.

Great : success, but no tests yet. Well it's a start.
Time to move forward, and write our first test.

== LeapYear-Step2 ==
Test, test, but there's nothing to test. Yes, absolutely. Let's think of a test, a test that will help us in the design. Now that's a good idea. Suppose I would be the user of the uplifting problem solving leap year checking library/component ... hmmm modesty first : leap year checking '''function'''.
How would I like that function to look.
<source lang="cpp">
bool IsLeapYear(int Year);
</source>
Yes that seems acceptable.
So let's write a test that will call that method.
We do that by adding the following code to LeapYearTest.cpp

<source lang="cpp">
#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

}

</source>
Things to note :
* we include the unit test header
* it is good to put the tests in nameless namespace (will be explained later on)
* we use the TEST macro, the argument is the name of the test : OurFirstTest
* we use CHECK_EQUAL to check if the expected result (the first argument) matches the computed result (the second argument)

Time to build. Woooooops errors. The tests fails completely, it does not even build. Time to add the code needed.
In order to compiler the test file, we need to include the LeapYear.h header and have that header export our function.
Our LeapYear header will look like this now (don't forget the include in the test file, it is not shown here) :

<source lang="cpp">
#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

bool IsLeapYear(int Year);

#endif // LEAPYEAR_H_INCLUDED

</source>

At least now it compiles, but it doesn't link yet. Duh, that because we don't have an implementation yet.
Time to provide the bare minimum of code to make the test pass.
So we change the LeapYear.cpp into :

<source lang="cpp">
#include "LeapYear.h"

bool IsLeapYear(int /*Year*/)
{
return true;
}

</source>
Build it, run it. Yes, we have one test passed.
Great. Let's move on.

== LeapYear-Step3 ==
Anyone having the feeling we are cheating. Well the user does not know how we wrote our code on the inside. So just to be sure the user (we) adds the following test, ending up in :

<source lang="cpp">
#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

TEST(OurSecondTest)
{
const bool Result = IsLeapYear(1973);
CHECK_EQUAL(false, Result);
}

}

</source>
Building is already no issue any more, we can run it. Oh boy, a test is failing.
The framework tell us something like this :
<filename>:<Line>: error: Failure in OurSecondTest: Expected 0 but was 1
FAILURE: 1 out of 2 tests failed (1 failures)
Test time: 0.00 seconds.

So we are informed of the line where the failing tests occurs, next to that it tells us what it was expecting and what the actual outcome was. And it presents a resume of the total number of tests, and how many that failed. For you scripting hackers note that FAILURE != SUCCESS.

It seems we should do some more effort and implement some real logic.

== LeapYear-Step4 ==
Let's keep it taking one step at a time. Let's start by implementing the 'divisible by 4' logic. That will already solve our tests.
So our LeapYear.cpp will now look like this :

<source lang="cpp">
#include "LeapYear.h"

namespace
{

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year);
}

</source>
Build, run. All tests pass. Life is great.

But those changing requirements, always the change of the requirements. Years that can be divided by 100 should not be considered as a leap year.

Time for our next step.

== LeapYear-Step5 ==
We add a new test for checking for example the year 1900.

<source lang="cpp">
TEST(DivisableBy100)
{
const bool Result = IsLeapYear(1900);
CHECK_EQUAL(false, Result);
}
</source>

Build and run the tests. It will fail. So time to add the minimum code needed to make this test pass.
This will change our LeapYear.cpp into :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year) && !IsDivisableBy100(Year);
}

</source>

Build and run the tests, yes : success. All 3 tests pass.

It seems life might be great again ...

Wrong, someone just added the following test :

<source lang="cpp">
TEST(DivisableBy400)
{
const bool Result = IsLeapYear(2000);
CHECK_EQUAL(true, Result);
}
</source>

And we once again have a failing test.

Time for the next step.

== LeapYear-Step6 ==
We should add logic to deal with years that can be divided by 400, since those are leap years.
We change our LeapYear.cpp into this :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy400(int Year)
{
return (Year%400) == 0;
}

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
const bool LeapYear = IsDivisableBy400(Year) ||
(IsDivisableBy4(Year) && !IsDivisableBy100(Year));
return LeapYear;
}

</source>

And once again everything works OK.
And it seems all the logical rules have been implemented.
This one is ready for shipping, and till the end of time we have our tests that can be run whenever we want (more on this later, we'd prefer this to be done automatically) to ensure we never break anything.

== Increase the user experience ==
There are a few areas where we can increase the user experience.
When a unit test fails the framework tell use on which line in the the code his happens.
That's excellent.
BUT we see this information in a console/shell windows. So we need to find that window, read the issues, remember them and then go find our test source files and navigate manually to the offending line. This works but is very cumbersome.
We want this to be a no-brainer, and have these steps being carried out for us.

Well, didn't we say life is great, Code::Blocks and UnitTest+= to the rescue. The error/warning output of the framework is in the gcc format. That means Code::Blocks can parse it.
One restriction Code::Blocks can parse it during the 'build process'. But currently the build procss stops after the unit test executable is build, and only then we run the test executable (manually).
Solution have Code::Blocks run the test executable as a post-build step. Pre-build and post-build steps are part of the build process !
Important consequence : if you want to debug something, the debugger will only kick off after Code::Blocks was able to carry out a successful build (including the pre/post builds steps). Therefor it is not wise to have the unit test executable being carried out as a post-bild step of the 'Debug' target. But as a post-build step of the Release target, our goal is met.

Adjust the target settings for the 'Release' target [Build Options -> select Release target -> Pre/Post-build steps -> Post-build steps text field] and add the following '''$exe_output'''. you can tick the 'Always execute' if you want.

Now build your Release target, and look at what shows up in the 'Build Log' tab in Code::Blocks.
This is my output :
<pre>

-------------- Build: Release in LeapYear ---------------

[ 25.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/LeapYear.cpp -o Deliv/Release/LeapYear.o
[ 50.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/LeapYearTest.cpp -o Deliv/Release/LeapYearTest.o
[ 75.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/main.cpp -o Deliv/Release/main.o
[100.0%] g++ -o Deliv/Release/LeapYear Deliv/Release/LeapYear.o Deliv/Release/LeapYearTest.o Deliv/Release/main.o -s ../UnitTest++/Deliv/Release/libUnitTest++.a
Output size is 23.28 KB
[100.0%] Running target post-build steps
Deliv/Release/LeapYear
Success: 4 tests passed.
Test time: 0.00 seconds.
Process terminated with status 0 (0 minutes, 2 seconds)
0 errors, 0 warnings
Build log saved as:
file:///home/lieven/Projects/UnitTestArticle/LeapYear/LeapYear_build_log.html
</pre>

We see that the unit test has been carried out, automatically.

Let's demonstrate that upon a failed test, Code::Blocks will jump to the offending line.
Change the latest test, the one checking on the year 2000 : change 2000 to 2001.
And build : Code::Blocks will jump to the offending line, and shows an entry in the "Build messages" tab (error: Failure in DivisableBy400: Expected 1 but was 0), just like for a regular compiler warning/error.
In the "Build" tab, we now find something like (red colored since it is an error) :
<pre>

-------------- Build: Release in LeapYear ---------------

[ 50.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/LeapYearTest.cpp -o Deliv/Release/LeapYearTest.o
[100.0%] g++ -o Deliv/Release/LeapYear Deliv/Release/LeapYear.o Deliv/Release/LeapYearTest.o Deliv/Release/main.o -s ../UnitTest++/Deliv/Release/libUnitTest++.a
Output size is 23.28 KB
[100.0%] Running target post-build steps
Deliv/Release/LeapYear
/home/lieven/Projects/UnitTestArticle/LeapYear/LeapYearTest.cpp:28: error: Failure in DivisableBy400: Expected 1 but was 0
FAILURE: 1 out of 4 tests failed (1 failures).
Test time: 0.00 seconds.
Process terminated with status 1 (0 minutes, 1 seconds)
1 errors, 0 warnings
Build log saved as:
file:///home/lieven/Projects/UnitTestArticle/LeapYear/LeapYear_build_log.html
</pre>

Voila, we have increased the user experience.
Time to readjust the final test, 2001 becomes 2000 again ;-)

== Further automation ==
You can create a script that calls Code::Blocks on the command line and passes it our LeapYear.cbp project file, and it will build both targets (Debug/Release) and run the test, since it is a post-build step for the 'Release' target.
Bye bye funky makefiles, welcome Code::Blocks as your build system.

== More to come ==
More examples will be added, showcasing 'fixtures' (setup/teardown), some more CHECK macros of UnitTest++. In case you have some tips/ideas, drop me a PM in the forum.
On the planning is a full conversion of the Money example, but all with gcc and Code::Blocks instead of the crazy Microsoft IDE.

UnitTesting

2009-09-09T19:25:55Z

Killerbot: /* Why Unit Testing */

This document is under development by killerbot. Starting from 7 September 2009.

== Introduction ==
This document will describe how unit testing can be combined with the Code::Blocks IDE. It will give a hands-on example on a unit testing framework and how it can be used with Code::Blocks.

== What is Unit Testing ==
Simply put Unit Testing is the discipline and best practice of writing and running little test programs that test little units of code.
Such a unit can be :
* a class
* a free function
* an interface
* ...
There are several unit test frameworks available to help you write, deploy, manage your unit tests. The most famous family is the xUnit framework, and some of it's descendants.

== Why Unit Testing ==
Well we write code that implements some functionality. We need a way to check and prove that the implementation is correct. Therefor we need tests. We need tests on the application level, at the integration level of different components, classes, interfaces. But we also need tests for the smallest building blocks, the units.
We also wans these tests to run very quickly. That way we can run the tests often, manually or automated.
These tests will also be our safeguards during refactoring of the code, extending the code or whatever maintenance tasks we carry out on the code.
These tests will also make us think of how our class, method, ... will be used. Since the test can be seen as a user of our code. Thanks to this, thinking about the tests before implementing the functionality can help us in the design : emergent design.
It will help us to avoid creating big classes, complex functions. We will only write the methods that are really needed, and no methods that we think might (n)ever be useful in the future. We are no good future tellers ! Those 'might be needed' methods and their tests are just a waste of time. Extending, refactoring will be done when it is actually needed, and at that time we have our unit tests to ensure we don't break any existing code.

Other times to add new unit tests are typically when a bug is discovered. Write a unit test to reproduce the bug, fix the code, and from now on the new unit test will watch your back so the bug won't reappear.

Unit test are also a good place of documentation. The little tests show how the class or method is used.
The code documents itself.

So the benefits are :
* better design
* prove of your code
* safe guard during code maintenance (refactoring, extensions)
* documentation
* ...

== Unit Test frameworks ==
When writing unit tests, one will create a lot of similar code. Since unit tests are nothing more then little programs, several tasks will be repeated, setting up the test environment, create your class, call a method, verify it's result, write out an error message when the test fails, preferably specifying what the wrong outcome was, and what the expected result is.
All these repetitive chores are taken care of by the frame work so the developer can focus on the real code of the test.
This document will use a small but very effective framework for the C++ language. It is called UnitTest++. It's homepage is at : [http://unittest-cpp.sourceforge.net/ UnitTest++].
You can download it directly at this [http://sourceforge.net/projects/unittest-cpp/files/UnitTest%2B%2B/1.4/unittest-cpp-1.4.zip/download link]. At the time of writing the latest version is 1.4.

== Setup our environment ==
Let's create a directory on our PC in which we will cary out our experiments. I will refer to this directory from now on as <TestPit>. For my laptop on which I am writing this article, that will be /home/lieven/Projects/UnitTestArticle. Note that everything we will do, works on linux and on windows!
Download the "unittest-cpp-1.4.zip" file from the link specified above. Extract it in the <TestPit> directory. All the files will end up in the <TestPit>/UnitTest++ directory.

== Build UnitTest++ ==
After the extracted the zip archive we have a directory structure like this :
<TestPit>/UnitTest++
|
+docs
|
+src

The files in the UnitTest++ directory are of little use for us, since they bring project files for some bizarre Microsoft IDE ;-) .
We will create our own Code::Blocks project to build the UnitTest++ framework.

Why do we need to build something ? Well as said, the framework will do a lot of chores for us, those chores are implemented by code, that code is framework. We will build to frame work into a static library, and for every unit test (or set of unit tests) we create a little (console/shell) program with the test code we wrote, which will link with the static library to obtain a unit test executable, driven by the framework.

We will put our Code::Blocks project file in a nice structured directory tree, therefor let's create a 'Project' subdirectory in the <TestPit>/UniTest++ directory.

In there create a new file with the name "UnitTest++.cbp".
Give that file the following content :

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="UnitTest++" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option platforms="Windows;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option platforms="Windows;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
<Target title="Debug(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<VirtualTargets>
<Add alias="All" targets="Debug;Release;Debug(linux);Release(linux);" />
</VirtualTargets>
<Unit filename="../src/AssertException.cpp" />
<Unit filename="../src/AssertException.h" />
<Unit filename="../src/CheckMacros.h" />
<Unit filename="../src/Checks.cpp" />
<Unit filename="../src/Checks.h" />
<Unit filename="../src/Config.h" />
<Unit filename="../src/CurrentTest.cpp" />
<Unit filename="../src/CurrentTest.h" />
<Unit filename="../src/DeferredTestReporter.cpp" />
<Unit filename="../src/DeferredTestReporter.h" />
<Unit filename="../src/DeferredTestResult.cpp" />
<Unit filename="../src/DeferredTestResult.h" />
<Unit filename="../src/ExecuteTest.h" />
<Unit filename="../src/MemoryOutStream.cpp" />
<Unit filename="../src/MemoryOutStream.h" />
<Unit filename="../src/Posix/SignalTranslator.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/SignalTranslator.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/ReportAssert.cpp" />
<Unit filename="../src/ReportAssert.h" />
<Unit filename="../src/Test.cpp" />
<Unit filename="../src/Test.h" />
<Unit filename="../src/TestDetails.cpp" />
<Unit filename="../src/TestDetails.h" />
<Unit filename="../src/TestList.cpp" />
<Unit filename="../src/TestList.h" />
<Unit filename="../src/TestMacros.h" />
<Unit filename="../src/TestReporter.cpp" />
<Unit filename="../src/TestReporter.h" />
<Unit filename="../src/TestReporterStdout.cpp" />
<Unit filename="../src/TestReporterStdout.h" />
<Unit filename="../src/TestResults.cpp" />
<Unit filename="../src/TestResults.h" />
<Unit filename="../src/TestRunner.cpp" />
<Unit filename="../src/TestRunner.h" />
<Unit filename="../src/TestSuite.h" />
<Unit filename="../src/TimeConstraint.cpp" />
<Unit filename="../src/TimeConstraint.h" />
<Unit filename="../src/TimeHelpers.h" />
<Unit filename="../src/UnitTest++.h" />
<Unit filename="../src/Win32/TimeHelpers.cpp">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/Win32/TimeHelpers.h">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/XmlTestReporter.cpp" />
<Unit filename="../src/XmlTestReporter.h" />
<Extensions>
<envvars />
<code_completion />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

Some things to note about the content of the project file, the power of Code::Blocks.
* there are 4 targets : Debug/Release for Windows and Debug/Release for linux [yes : 1 project file that allows building on linux and on windows]
* some files are only part of the linux targets, some only for the windows targets

But before we build, let's modify some source files (not really needed, but I prefer to have warning free compilations). These are the changes I carried out :
* ReportAssert.cpp : #include "ReportAssert.h"
* win32/TimeHelpers.cpp : first the m_threadHandle and then the m_startTime in the initializerlist

Next open up this project file in Code::Blocks and build the debug and release target. From now one we will only use the Release target, we go for speed ;-)

The result of the build process will show up in subdirectories of the new 'Deliv' subdirectory of <testPit>/UnitTest++ : '''<testPit>/UnitTest++/Deliv/Release/libUnitTest++.a'''

Alright, we have build the unit test framework in a platform independent way, no silly makefiles, no obscure M$ IDE, good old super Code::Blocks. It is time to write some code so we have something to unit test.

In the first example we will create a simple free function that checks if a a give year is a leap your or not.

The business logic is as follows : a year is a leap year when it can be divided by 4, unless itcan be divided by 100. But in case it can be divided by 400, then again it is a leap year.

In the next section we will first setup a Code::Blocks project containing both the 'functionality files, and the unit test files. Typically one will package several functionality files into a static library and create a unit test project that tests all the class/functionalities in that library package, also called a component. That is we have a component (whose deliverable is the static library, and we have a unit test project that tests the entire component).

== Our first test project environment ==
Let's create a new directory in our <TestPit> : <TestPit>/LeapYear.
For the simplicity we will put the project file and the source file all together in this directory. Normally we would work in a more structured way, but in a demo article we have some artistic freedom ;-)
Next you can create with the Code::Block's wizard a new console project in the LeapYear directory. Or you can create the following 5 files and give the the contents as specified below. Note that this demo works on linux and on windows, everything is still completely platform independent. Long Live Code::Blocks.

The project file : LeapYear.cbp (the one below already contains the 5 source files, in case you use the wizard you have to add the LeapYear.h/cpp and LeapYearTest.cpp files to the project)

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="LeapYear" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option output="Deliv/Debug/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Debug/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option output="Deliv/Release/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Release/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-O2" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<Compiler>
<Add option="-Wall" />
<Add option="-fexceptions" />
</Compiler>
<Unit filename="LeapYear.cpp" />
<Unit filename="LeapYear.h" />
<Unit filename="LeapYearTest.cpp" />
<Unit filename="main.cpp" />
<Extensions>
<envvars />
<code_completion />
<lib_finder disable_auto="1" />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

The main source file : main.cpp
int main()
{
return 0;
}

The header exporting our powerful function : LeapYear.h

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

#endif // LEAPYEAR_H_INCLUDED

And the implementation of the leap year logic : LeapYear.cpp

#include "LeapYear.h"

And finishing with the source file for the tests : LeapYearTest.cpp (currently) empty

We can already build the project, we have a nice little program that does .... nothing.

Time to move to the next section, a little word about Test Driven Development.

== Test Driven Development ==
This is a practice where new code is only added to make a failing test pass. And one only adds the code needed to make that test pass. Once that is done, a new test is added to will check the next functionality to add.
On this really simple example we will more or less practice some TDD.

So get ready, it's time for LeapYear-Step1.

== LeapYear-Step1 ==
We will turn our main.cpp into the guy in charge to carry out the tests, all we need to do is change the contents of main.cpp into this :

<source lang="cpp">
#include "UnitTest++.h"

int main()
{
return UnitTest::RunAllTests();
}

</source>
And add '''../UnitTest++/src''' to the compiler search directories on the project level of our LeapYear project.
And add '''../UnitTest++/Deliv/Release/libUnitTest++.a''' to the link libraries of the project

Why : well we need to link with the framework and we need to include the UnitTest++ header so we can use it's functionalities.

The line '''UnitTest::RunAllTests()''' will make sure all test encountered in our sources will be carried out.
We don't have any tests yet, nor any functionality, but go ahead build the project and run it.
This is the output :

Success: 0 tests passed
Test time: 0.00 seconds.

Great : success, but no tests yet. Well it's a start.
Time to move forward, and write our first test.

== LeapYear-Step2 ==
Test, test, but there's nothing to test. Yes, absolutely. Let's think of a test, a test that will help us in the design. Now that's a good idea. Suppose I would be the user of the uplifting problem solving leap year checking library/component ... hmmm modesty first : leap year checking '''function'''.
How would I like that function to look.
<source lang="cpp">
bool IsLeapYear(int Year);
</source>
Yes that seems acceptable.
So let's write a test that will call that method.
We do that by adding the following code to LeapYearTest.cpp

<source lang="cpp">
#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

}

</source>
Things to note :
* we include the unit test header
* it is good to put the tests in nameless namespace (will be explained later on)
* we use the TEST macro, the argument is the name of the test : OurFirstTest
* we use CHECK_EQUAL to check if the expected result (the first argument) matches the computed result (the second argument)

Time to build. Woooooops errors. The tests fails completely, it does not even build. Time to add the code needed.
In order to compiler the test file, we need to include the LeapYear.h header and have that header export our function.
Our LeapYear header will look like this now (don't forget the include in the test file, it is not shown here) :

<source lang="cpp">
#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

bool IsLeapYear(int Year);

#endif // LEAPYEAR_H_INCLUDED

</source>

At least now it compiles, but it doesn't link yet. Duh, that because we don't have an implementation yet.
Time to provide the bare minimum of code to make the test pass.
So we change the LeapYear.cpp into :

<source lang="cpp">
#include "LeapYear.h"

bool IsLeapYear(int /*Year*/)
{
return true;
}

</source>
Build it, run it. Yes, we have one test passed.
Great. Let's move on.

== LeapYear-Step3 ==
Anyone having the feeling we are cheating. Well the user does not know how we wrote our code on the inside. So just to be sure the user (we) adds the following test, ending up in :

<source lang="cpp">
#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

TEST(OurSecondTest)
{
const bool Result = IsLeapYear(1973);
CHECK_EQUAL(false, Result);
}

}

</source>
Building is already no issue any more, we can run it. Oh boy, a test is failing.
The framework tell us something like this :
<filename>:<Line>: error: Failure in OurSecondTest: Expected 0 but was 1
FAILURE: 1 out of 2 tests failed (1 failures)
Test time: 0.00 seconds.

So we are informed of the line where the failing tests occurs, next to that it tells us what it was expecting and what the actual outcome was. And it presents a resume of the total number of tests, and how many that failed. For you scripting hackers note that FAILURE != SUCCESS.

It seems we should do some more effort and implement some real logic.

== LeapYear-Step4 ==
Let's keep it taking one step at a time. Let's start by implementing the 'divisible by 4' logic. That will already solve our tests.
So our LeapYear.cpp will now look like this :

<source lang="cpp">
#include "LeapYear.h"

namespace
{

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year);
}

</source>
Build, run. All tests pass. Life is great.

But those changing requirements, always the change of the requirements. Years that can be divided by 100 should not be considered as a leap year.

Time for our next step.

== LeapYear-Step5 ==
We add a new test for checking for example the year 1900.

<source lang="cpp">
TEST(DivisableBy100)
{
const bool Result = IsLeapYear(1900);
CHECK_EQUAL(false, Result);
}
</source>

Build and run the tests. It will fail. So time to add the minimum code needed to make this test pass.
This will change our LeapYear.cpp into :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year) && !IsDivisableBy100(Year);
}

</source>

Build and run the tests, yes : success. All 3 tests pass.

It seems life might be great again ...

Wrong, someone just added the following test :

<source lang="cpp">
TEST(DivisableBy400)
{
const bool Result = IsLeapYear(2000);
CHECK_EQUAL(true, Result);
}
</source>

And we once again have a failing test.

Time for the next step.

== LeapYear-Step6 ==
We should add logic to deal with years that can be divided by 400, since those are leap years.
We change our LeapYear.cpp into this :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy400(int Year)
{
return (Year%400) == 0;
}

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
const bool LeapYear = IsDivisableBy400(Year) ||
(IsDivisableBy4(Year) && !IsDivisableBy100(Year));
return LeapYear;
}

</source>

And once again everything works OK.
And it seems all the logical rules have been implemented.
This one is ready for shipping, and till the end of time we have our tests that can be run whenever we want (more on this later, we'd prefer this to be done automatically) to ensure we never break anything.

== Increase the user experience ==
There are a few areas where we can increase the user experience.
When a unit test fails the framework tell use on which line in the the code his happens.
That's excellent.
BUT we see this information in a console/shell windows. So we need to find that window, read the issues, remember them and then go find our test source files and navigate manually to the offending line. This works but is very cumbersome.
We want this to be a no-brainer, and have these steps being carried out for us.

Well, didn't we say life is great, Code::Blocks and UnitTest+= to the rescue. The error/warning output of the framework is in the gcc format. That means Code::Blocks can parse it.
One restriction Code::Blocks can parse it during the 'build process'. But currently the build procss stops after the unit test executable is build, and only then we run the test executable (manually).
Solution have Code::Blocks run the test executable as a post-build step. Pre-build and post-build steps are part of the build process !
Important consequence : if you want to debug something, the debugger will only kick off after Code::Blocks was able to carry out a successful build (including the pre/post builds steps). Therefor it is not wise to have the unit test executable being carried out as a post-bild step of the 'Debug' target. But as a post-build step of the Release target, our goal is met.

Adjust the target settings for the 'Release' target [Build Options -> select Release target -> Pre/Post-build steps -> Post-build steps text field] and add the following '''$exe_output'''. you can tick the 'Always execute' if you want.

Now build your Release target, and look at what shows up in the 'Build Log' tab in Code::Blocks.
This is my output :
<pre>

-------------- Build: Release in LeapYear ---------------

[ 25.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/LeapYear.cpp -o Deliv/Release/LeapYear.o
[ 50.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/LeapYearTest.cpp -o Deliv/Release/LeapYearTest.o
[ 75.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/main.cpp -o Deliv/Release/main.o
[100.0%] g++ -o Deliv/Release/LeapYear Deliv/Release/LeapYear.o Deliv/Release/LeapYearTest.o Deliv/Release/main.o -s ../UnitTest++/Deliv/Release/libUnitTest++.a
Output size is 23.28 KB
[100.0%] Running target post-build steps
Deliv/Release/LeapYear
Success: 4 tests passed.
Test time: 0.00 seconds.
Process terminated with status 0 (0 minutes, 2 seconds)
0 errors, 0 warnings
Build log saved as:
file:///home/lieven/Projects/UnitTestArticle/LeapYear/LeapYear_build_log.html
</pre>

We see that the unit test has been carried out, automatically.

Let's demonstrate that upon a failed test, Code::Blocks will jump to the offending line.
Change the latest test, the one checking on the year 2000 : change 2000 to 2001.
And build : Code::Blocks will jump to the offending line, and shows an entry in the "Build messages" tab (error: Failure in DivisableBy400: Expected 1 but was 0), just like for a regular compiler warning/error.
In the "Build" tab, we now find something like (red colored since it is an error) :
<pre>

-------------- Build: Release in LeapYear ---------------

[ 50.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/LeapYearTest.cpp -o Deliv/Release/LeapYearTest.o
[100.0%] g++ -o Deliv/Release/LeapYear Deliv/Release/LeapYear.o Deliv/Release/LeapYearTest.o Deliv/Release/main.o -s ../UnitTest++/Deliv/Release/libUnitTest++.a
Output size is 23.28 KB
[100.0%] Running target post-build steps
Deliv/Release/LeapYear
/home/lieven/Projects/UnitTestArticle/LeapYear/LeapYearTest.cpp:28: error: Failure in DivisableBy400: Expected 1 but was 0
FAILURE: 1 out of 4 tests failed (1 failures).
Test time: 0.00 seconds.
Process terminated with status 1 (0 minutes, 1 seconds)
1 errors, 0 warnings
Build log saved as:
file:///home/lieven/Projects/UnitTestArticle/LeapYear/LeapYear_build_log.html
</pre>

Voila, we have increased the user experience.
Time to readjust the final test, 2001 becomes 2000 again ;-)

== Further automation ==
You can create a script that calls Code::Blocks on the command line and passes it our LeapYear.cbp project file, and it will build both targets (Debug/Release) and run the test, since it is a post-build step for the 'Release' target.
Bye bye funky makefiles, welcome Code::Blocks as your build system.

== More to come ==
More examples will be added, showcasing 'fixtures' (setup/teardown), some more CHECK macros of UnitTest++. In case you have some tips/ideas, drop me a PM in the forum.
On the planning is a full conversion of the Money example, but all with gcc and Code::Blocks instead of the crazy Microsoft IDE.

UnitTesting

2009-09-09T11:30:44Z

Killerbot: /* Further automation */

This document is under development by killerbot. Starting from 7 September 2009.

== Introduction ==
This document will describe how unit testing can be combined with the Code::Blocks IDE. It will give a hands-on example on a unit testing framework and how it can be used with Code::Blocks.

== What is Unit Testing ==
Simply put Unit Testing is the discipline and best practice of writing and running little test programs that test little units of code.
Such a unit can be :
* a class
* a free function
* an interface
* ...
There are several unit test frameworks available to help you write, deploy, manage your unit tests. The most famous family is the xUnit framework, and some of it's descendants.

== Why Unit Testing ==
Well we write code that implements some functionality. We need a way to check and prove that the implementation is correct. Therefor we need tests. We need tests on the application level, at the integration level of different components, classes, interfaces. But we also need tests for the smallest building blocks, the units.
We also wans these tests to run very quickly. That we we can run the tests often, manually or automated.
These tests will also be our safeguards during refactoring of the code, extending the code or whatever maintenance tasks we carry out on the code.
These tests will also make us think of how our class, method, ... will be used. Since the test can be seen as a user of our code. Thanks do this, thinking about the tests before implementing the functionality can help us in the design : emergent design.
It will help us to avoid creating big classes, complex functions. We will only write the methods that are really needed, and no methods that we think might (n)ever be useful in the future. We are no good future tellers ! Those 'might be needed' methods and their tests are just a waste of time. Extending, refactoring will be done when it is actually needed, and at that time we have our unit tests to ensure we don't break any existing code.

Other times to add new unit tests are typically when a bug is discovered; Write a unit test to reproduces the bug, fix the code, and from now on the new unit test will watch your back so the bug won't reappear.

Unit test are also a good place of documentation. The little tests show how the class or method is used.
The code documents itself.

So the benefits are :
* better design
* prove of your code
* safe guard during code maintenance (refactoring, extensions)
* documentation
* ...

== Unit Test frameworks ==
When writing unit tests, one will create a lot of similar code. Since unit tests are nothing more then little programs, several tasks will be repeated, setting up the test environment, create your class, call a method, verify it's result, write out an error message when the test fails, preferably specifying what the wrong outcome was, and what the expected result is.
All these repetitive chores are taken care of by the frame work so the developer can focus on the real code of the test.
This document will use a small but very effective framework for the C++ language. It is called UnitTest++. It's homepage is at : [http://unittest-cpp.sourceforge.net/ UnitTest++].
You can download it directly at this [http://sourceforge.net/projects/unittest-cpp/files/UnitTest%2B%2B/1.4/unittest-cpp-1.4.zip/download link]. At the time of writing the latest version is 1.4.

== Setup our environment ==
Let's create a directory on our PC in which we will cary out our experiments. I will refer to this directory from now on as <TestPit>. For my laptop on which I am writing this article, that will be /home/lieven/Projects/UnitTestArticle. Note that everything we will do, works on linux and on windows!
Download the "unittest-cpp-1.4.zip" file from the link specified above. Extract it in the <TestPit> directory. All the files will end up in the <TestPit>/UnitTest++ directory.

== Build UnitTest++ ==
After the extracted the zip archive we have a directory structure like this :
<TestPit>/UnitTest++
|
+docs
|
+src

The files in the UnitTest++ directory are of little use for us, since they bring project files for some bizarre Microsoft IDE ;-) .
We will create our own Code::Blocks project to build the UnitTest++ framework.

Why do we need to build something ? Well as said, the framework will do a lot of chores for us, those chores are implemented by code, that code is framework. We will build to frame work into a static library, and for every unit test (or set of unit tests) we create a little (console/shell) program with the test code we wrote, which will link with the static library to obtain a unit test executable, driven by the framework.

We will put our Code::Blocks project file in a nice structured directory tree, therefor let's create a 'Project' subdirectory in the <TestPit>/UniTest++ directory.

In there create a new file with the name "UnitTest++.cbp".
Give that file the following content :

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="UnitTest++" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option platforms="Windows;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option platforms="Windows;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
<Target title="Debug(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<VirtualTargets>
<Add alias="All" targets="Debug;Release;Debug(linux);Release(linux);" />
</VirtualTargets>
<Unit filename="../src/AssertException.cpp" />
<Unit filename="../src/AssertException.h" />
<Unit filename="../src/CheckMacros.h" />
<Unit filename="../src/Checks.cpp" />
<Unit filename="../src/Checks.h" />
<Unit filename="../src/Config.h" />
<Unit filename="../src/CurrentTest.cpp" />
<Unit filename="../src/CurrentTest.h" />
<Unit filename="../src/DeferredTestReporter.cpp" />
<Unit filename="../src/DeferredTestReporter.h" />
<Unit filename="../src/DeferredTestResult.cpp" />
<Unit filename="../src/DeferredTestResult.h" />
<Unit filename="../src/ExecuteTest.h" />
<Unit filename="../src/MemoryOutStream.cpp" />
<Unit filename="../src/MemoryOutStream.h" />
<Unit filename="../src/Posix/SignalTranslator.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/SignalTranslator.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/ReportAssert.cpp" />
<Unit filename="../src/ReportAssert.h" />
<Unit filename="../src/Test.cpp" />
<Unit filename="../src/Test.h" />
<Unit filename="../src/TestDetails.cpp" />
<Unit filename="../src/TestDetails.h" />
<Unit filename="../src/TestList.cpp" />
<Unit filename="../src/TestList.h" />
<Unit filename="../src/TestMacros.h" />
<Unit filename="../src/TestReporter.cpp" />
<Unit filename="../src/TestReporter.h" />
<Unit filename="../src/TestReporterStdout.cpp" />
<Unit filename="../src/TestReporterStdout.h" />
<Unit filename="../src/TestResults.cpp" />
<Unit filename="../src/TestResults.h" />
<Unit filename="../src/TestRunner.cpp" />
<Unit filename="../src/TestRunner.h" />
<Unit filename="../src/TestSuite.h" />
<Unit filename="../src/TimeConstraint.cpp" />
<Unit filename="../src/TimeConstraint.h" />
<Unit filename="../src/TimeHelpers.h" />
<Unit filename="../src/UnitTest++.h" />
<Unit filename="../src/Win32/TimeHelpers.cpp">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/Win32/TimeHelpers.h">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/XmlTestReporter.cpp" />
<Unit filename="../src/XmlTestReporter.h" />
<Extensions>
<envvars />
<code_completion />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

Some things to note about the content of the project file, the power of Code::Blocks.
* there are 4 targets : Debug/Release for Windows and Debug/Release for linux [yes : 1 project file that allows building on linux and on windows]
* some files are only part of the linux targets, some only for the windows targets

But before we build, let's modify some source files (not really needed, but I prefer to have warning free compilations). These are the changes I carried out :
* ReportAssert.cpp : #include "ReportAssert.h"
* win32/TimeHelpers.cpp : first the m_threadHandle and then the m_startTime in the initializerlist

Next open up this project file in Code::Blocks and build the debug and release target. From now one we will only use the Release target, we go for speed ;-)

The result of the build process will show up in subdirectories of the new 'Deliv' subdirectory of <testPit>/UnitTest++ : '''<testPit>/UnitTest++/Deliv/Release/libUnitTest++.a'''

Alright, we have build the unit test framework in a platform independent way, no silly makefiles, no obscure M$ IDE, good old super Code::Blocks. It is time to write some code so we have something to unit test.

In the first example we will create a simple free function that checks if a a give year is a leap your or not.

The business logic is as follows : a year is a leap year when it can be divided by 4, unless itcan be divided by 100. But in case it can be divided by 400, then again it is a leap year.

In the next section we will first setup a Code::Blocks project containing both the 'functionality files, and the unit test files. Typically one will package several functionality files into a static library and create a unit test project that tests all the class/functionalities in that library package, also called a component. That is we have a component (whose deliverable is the static library, and we have a unit test project that tests the entire component).

== Our first test project environment ==
Let's create a new directory in our <TestPit> : <TestPit>/LeapYear.
For the simplicity we will put the project file and the source file all together in this directory. Normally we would work in a more structured way, but in a demo article we have some artistic freedom ;-)
Next you can create with the Code::Block's wizard a new console project in the LeapYear directory. Or you can create the following 5 files and give the the contents as specified below. Note that this demo works on linux and on windows, everything is still completely platform independent. Long Live Code::Blocks.

The project file : LeapYear.cbp (the one below already contains the 5 source files, in case you use the wizard you have to add the LeapYear.h/cpp and LeapYearTest.cpp files to the project)

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="LeapYear" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option output="Deliv/Debug/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Debug/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option output="Deliv/Release/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Release/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-O2" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<Compiler>
<Add option="-Wall" />
<Add option="-fexceptions" />
</Compiler>
<Unit filename="LeapYear.cpp" />
<Unit filename="LeapYear.h" />
<Unit filename="LeapYearTest.cpp" />
<Unit filename="main.cpp" />
<Extensions>
<envvars />
<code_completion />
<lib_finder disable_auto="1" />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

The main source file : main.cpp
int main()
{
return 0;
}

The header exporting our powerful function : LeapYear.h

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

#endif // LEAPYEAR_H_INCLUDED

And the implementation of the leap year logic : LeapYear.cpp

#include "LeapYear.h"

And finishing with the source file for the tests : LeapYearTest.cpp (currently) empty

We can already build the project, we have a nice little program that does .... nothing.

Time to move to the next section, a little word about Test Driven Development.

== Test Driven Development ==
This is a practice where new code is only added to make a failing test pass. And one only adds the code needed to make that test pass. Once that is done, a new test is added to will check the next functionality to add.
On this really simple example we will more or less practice some TDD.

So get ready, it's time for LeapYear-Step1.

== LeapYear-Step1 ==
We will turn our main.cpp into the guy in charge to carry out the tests, all we need to do is change the contents of main.cpp into this :

<source lang="cpp">
#include "UnitTest++.h"

int main()
{
return UnitTest::RunAllTests();
}

</source>
And add '''../UnitTest++/src''' to the compiler search directories on the project level of our LeapYear project.
And add '''../UnitTest++/Deliv/Release/libUnitTest++.a''' to the link libraries of the project

Why : well we need to link with the framework and we need to include the UnitTest++ header so we can use it's functionalities.

The line '''UnitTest::RunAllTests()''' will make sure all test encountered in our sources will be carried out.
We don't have any tests yet, nor any functionality, but go ahead build the project and run it.
This is the output :

Success: 0 tests passed
Test time: 0.00 seconds.

Great : success, but no tests yet. Well it's a start.
Time to move forward, and write our first test.

== LeapYear-Step2 ==
Test, test, but there's nothing to test. Yes, absolutely. Let's think of a test, a test that will help us in the design. Now that's a good idea. Suppose I would be the user of the uplifting problem solving leap year checking library/component ... hmmm modesty first : leap year checking '''function'''.
How would I like that function to look.
<source lang="cpp">
bool IsLeapYear(int Year);
</source>
Yes that seems acceptable.
So let's write a test that will call that method.
We do that by adding the following code to LeapYearTest.cpp

<source lang="cpp">
#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

}

</source>
Things to note :
* we include the unit test header
* it is good to put the tests in nameless namespace (will be explained later on)
* we use the TEST macro, the argument is the name of the test : OurFirstTest
* we use CHECK_EQUAL to check if the expected result (the first argument) matches the computed result (the second argument)

Time to build. Woooooops errors. The tests fails completely, it does not even build. Time to add the code needed.
In order to compiler the test file, we need to include the LeapYear.h header and have that header export our function.
Our LeapYear header will look like this now (don't forget the include in the test file, it is not shown here) :

<source lang="cpp">
#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

bool IsLeapYear(int Year);

#endif // LEAPYEAR_H_INCLUDED

</source>

At least now it compiles, but it doesn't link yet. Duh, that because we don't have an implementation yet.
Time to provide the bare minimum of code to make the test pass.
So we change the LeapYear.cpp into :

<source lang="cpp">
#include "LeapYear.h"

bool IsLeapYear(int /*Year*/)
{
return true;
}

</source>
Build it, run it. Yes, we have one test passed.
Great. Let's move on.

== LeapYear-Step3 ==
Anyone having the feeling we are cheating. Well the user does not know how we wrote our code on the inside. So just to be sure the user (we) adds the following test, ending up in :

<source lang="cpp">
#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

TEST(OurSecondTest)
{
const bool Result = IsLeapYear(1973);
CHECK_EQUAL(false, Result);
}

}

</source>
Building is already no issue any more, we can run it. Oh boy, a test is failing.
The framework tell us something like this :
<filename>:<Line>: error: Failure in OurSecondTest: Expected 0 but was 1
FAILURE: 1 out of 2 tests failed (1 failures)
Test time: 0.00 seconds.

So we are informed of the line where the failing tests occurs, next to that it tells us what it was expecting and what the actual outcome was. And it presents a resume of the total number of tests, and how many that failed. For you scripting hackers note that FAILURE != SUCCESS.

It seems we should do some more effort and implement some real logic.

== LeapYear-Step4 ==
Let's keep it taking one step at a time. Let's start by implementing the 'divisible by 4' logic. That will already solve our tests.
So our LeapYear.cpp will now look like this :

<source lang="cpp">
#include "LeapYear.h"

namespace
{

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year);
}

</source>
Build, run. All tests pass. Life is great.

But those changing requirements, always the change of the requirements. Years that can be divided by 100 should not be considered as a leap year.

Time for our next step.

== LeapYear-Step5 ==
We add a new test for checking for example the year 1900.

<source lang="cpp">
TEST(DivisableBy100)
{
const bool Result = IsLeapYear(1900);
CHECK_EQUAL(false, Result);
}
</source>

Build and run the tests. It will fail. So time to add the minimum code needed to make this test pass.
This will change our LeapYear.cpp into :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year) && !IsDivisableBy100(Year);
}

</source>

Build and run the tests, yes : success. All 3 tests pass.

It seems life might be great again ...

Wrong, someone just added the following test :

<source lang="cpp">
TEST(DivisableBy400)
{
const bool Result = IsLeapYear(2000);
CHECK_EQUAL(true, Result);
}
</source>

And we once again have a failing test.

Time for the next step.

== LeapYear-Step6 ==
We should add logic to deal with years that can be divided by 400, since those are leap years.
We change our LeapYear.cpp into this :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy400(int Year)
{
return (Year%400) == 0;
}

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
const bool LeapYear = IsDivisableBy400(Year) ||
(IsDivisableBy4(Year) && !IsDivisableBy100(Year));
return LeapYear;
}

</source>

And once again everything works OK.
And it seems all the logical rules have been implemented.
This one is ready for shipping, and till the end of time we have our tests that can be run whenever we want (more on this later, we'd prefer this to be done automatically) to ensure we never break anything.

== Increase the user experience ==
There are a few areas where we can increase the user experience.
When a unit test fails the framework tell use on which line in the the code his happens.
That's excellent.
BUT we see this information in a console/shell windows. So we need to find that window, read the issues, remember them and then go find our test source files and navigate manually to the offending line. This works but is very cumbersome.
We want this to be a no-brainer, and have these steps being carried out for us.

Well, didn't we say life is great, Code::Blocks and UnitTest+= to the rescue. The error/warning output of the framework is in the gcc format. That means Code::Blocks can parse it.
One restriction Code::Blocks can parse it during the 'build process'. But currently the build procss stops after the unit test executable is build, and only then we run the test executable (manually).
Solution have Code::Blocks run the test executable as a post-build step. Pre-build and post-build steps are part of the build process !
Important consequence : if you want to debug something, the debugger will only kick off after Code::Blocks was able to carry out a successful build (including the pre/post builds steps). Therefor it is not wise to have the unit test executable being carried out as a post-bild step of the 'Debug' target. But as a post-build step of the Release target, our goal is met.

Adjust the target settings for the 'Release' target [Build Options -> select Release target -> Pre/Post-build steps -> Post-build steps text field] and add the following '''$exe_output'''. you can tick the 'Always execute' if you want.

Now build your Release target, and look at what shows up in the 'Build Log' tab in Code::Blocks.
This is my output :
<pre>

-------------- Build: Release in LeapYear ---------------

[ 25.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/LeapYear.cpp -o Deliv/Release/LeapYear.o
[ 50.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/LeapYearTest.cpp -o Deliv/Release/LeapYearTest.o
[ 75.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/main.cpp -o Deliv/Release/main.o
[100.0%] g++ -o Deliv/Release/LeapYear Deliv/Release/LeapYear.o Deliv/Release/LeapYearTest.o Deliv/Release/main.o -s ../UnitTest++/Deliv/Release/libUnitTest++.a
Output size is 23.28 KB
[100.0%] Running target post-build steps
Deliv/Release/LeapYear
Success: 4 tests passed.
Test time: 0.00 seconds.
Process terminated with status 0 (0 minutes, 2 seconds)
0 errors, 0 warnings
Build log saved as:
file:///home/lieven/Projects/UnitTestArticle/LeapYear/LeapYear_build_log.html
</pre>

We see that the unit test has been carried out, automatically.

Let's demonstrate that upon a failed test, Code::Blocks will jump to the offending line.
Change the latest test, the one checking on the year 2000 : change 2000 to 2001.
And build : Code::Blocks will jump to the offending line, and shows an entry in the "Build messages" tab (error: Failure in DivisableBy400: Expected 1 but was 0), just like for a regular compiler warning/error.
In the "Build" tab, we now find something like (red colored since it is an error) :
<pre>

-------------- Build: Release in LeapYear ---------------

[ 50.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/LeapYearTest.cpp -o Deliv/Release/LeapYearTest.o
[100.0%] g++ -o Deliv/Release/LeapYear Deliv/Release/LeapYear.o Deliv/Release/LeapYearTest.o Deliv/Release/main.o -s ../UnitTest++/Deliv/Release/libUnitTest++.a
Output size is 23.28 KB
[100.0%] Running target post-build steps
Deliv/Release/LeapYear
/home/lieven/Projects/UnitTestArticle/LeapYear/LeapYearTest.cpp:28: error: Failure in DivisableBy400: Expected 1 but was 0
FAILURE: 1 out of 4 tests failed (1 failures).
Test time: 0.00 seconds.
Process terminated with status 1 (0 minutes, 1 seconds)
1 errors, 0 warnings
Build log saved as:
file:///home/lieven/Projects/UnitTestArticle/LeapYear/LeapYear_build_log.html
</pre>

Voila, we have increased the user experience.
Time to readjust the final test, 2001 becomes 2000 again ;-)

== Further automation ==
You can create a script that calls Code::Blocks on the command line and passes it our LeapYear.cbp project file, and it will build both targets (Debug/Release) and run the test, since it is a post-build step for the 'Release' target.
Bye bye funky makefiles, welcome Code::Blocks as your build system.

== More to come ==
More examples will be added, showcasing 'fixtures' (setup/teardown), some more CHECK macros of UnitTest++. In case you have some tips/ideas, drop me a PM in the forum.
On the planning is a full conversion of the Money example, but all with gcc and Code::Blocks instead of the crazy Microsoft IDE.

UnitTesting

2009-09-09T11:26:12Z

Killerbot: /* Increase the user experience */

This document is under development by killerbot. Starting from 7 September 2009.

== Introduction ==
This document will describe how unit testing can be combined with the Code::Blocks IDE. It will give a hands-on example on a unit testing framework and how it can be used with Code::Blocks.

== What is Unit Testing ==
Simply put Unit Testing is the discipline and best practice of writing and running little test programs that test little units of code.
Such a unit can be :
* a class
* a free function
* an interface
* ...
There are several unit test frameworks available to help you write, deploy, manage your unit tests. The most famous family is the xUnit framework, and some of it's descendants.

== Why Unit Testing ==
Well we write code that implements some functionality. We need a way to check and prove that the implementation is correct. Therefor we need tests. We need tests on the application level, at the integration level of different components, classes, interfaces. But we also need tests for the smallest building blocks, the units.
We also wans these tests to run very quickly. That we we can run the tests often, manually or automated.
These tests will also be our safeguards during refactoring of the code, extending the code or whatever maintenance tasks we carry out on the code.
These tests will also make us think of how our class, method, ... will be used. Since the test can be seen as a user of our code. Thanks do this, thinking about the tests before implementing the functionality can help us in the design : emergent design.
It will help us to avoid creating big classes, complex functions. We will only write the methods that are really needed, and no methods that we think might (n)ever be useful in the future. We are no good future tellers ! Those 'might be needed' methods and their tests are just a waste of time. Extending, refactoring will be done when it is actually needed, and at that time we have our unit tests to ensure we don't break any existing code.

Other times to add new unit tests are typically when a bug is discovered; Write a unit test to reproduces the bug, fix the code, and from now on the new unit test will watch your back so the bug won't reappear.

Unit test are also a good place of documentation. The little tests show how the class or method is used.
The code documents itself.

So the benefits are :
* better design
* prove of your code
* safe guard during code maintenance (refactoring, extensions)
* documentation
* ...

== Unit Test frameworks ==
When writing unit tests, one will create a lot of similar code. Since unit tests are nothing more then little programs, several tasks will be repeated, setting up the test environment, create your class, call a method, verify it's result, write out an error message when the test fails, preferably specifying what the wrong outcome was, and what the expected result is.
All these repetitive chores are taken care of by the frame work so the developer can focus on the real code of the test.
This document will use a small but very effective framework for the C++ language. It is called UnitTest++. It's homepage is at : [http://unittest-cpp.sourceforge.net/ UnitTest++].
You can download it directly at this [http://sourceforge.net/projects/unittest-cpp/files/UnitTest%2B%2B/1.4/unittest-cpp-1.4.zip/download link]. At the time of writing the latest version is 1.4.

== Setup our environment ==
Let's create a directory on our PC in which we will cary out our experiments. I will refer to this directory from now on as <TestPit>. For my laptop on which I am writing this article, that will be /home/lieven/Projects/UnitTestArticle. Note that everything we will do, works on linux and on windows!
Download the "unittest-cpp-1.4.zip" file from the link specified above. Extract it in the <TestPit> directory. All the files will end up in the <TestPit>/UnitTest++ directory.

== Build UnitTest++ ==
After the extracted the zip archive we have a directory structure like this :
<TestPit>/UnitTest++
|
+docs
|
+src

The files in the UnitTest++ directory are of little use for us, since they bring project files for some bizarre Microsoft IDE ;-) .
We will create our own Code::Blocks project to build the UnitTest++ framework.

Why do we need to build something ? Well as said, the framework will do a lot of chores for us, those chores are implemented by code, that code is framework. We will build to frame work into a static library, and for every unit test (or set of unit tests) we create a little (console/shell) program with the test code we wrote, which will link with the static library to obtain a unit test executable, driven by the framework.

We will put our Code::Blocks project file in a nice structured directory tree, therefor let's create a 'Project' subdirectory in the <TestPit>/UniTest++ directory.

In there create a new file with the name "UnitTest++.cbp".
Give that file the following content :

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="UnitTest++" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option platforms="Windows;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option platforms="Windows;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
<Target title="Debug(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<VirtualTargets>
<Add alias="All" targets="Debug;Release;Debug(linux);Release(linux);" />
</VirtualTargets>
<Unit filename="../src/AssertException.cpp" />
<Unit filename="../src/AssertException.h" />
<Unit filename="../src/CheckMacros.h" />
<Unit filename="../src/Checks.cpp" />
<Unit filename="../src/Checks.h" />
<Unit filename="../src/Config.h" />
<Unit filename="../src/CurrentTest.cpp" />
<Unit filename="../src/CurrentTest.h" />
<Unit filename="../src/DeferredTestReporter.cpp" />
<Unit filename="../src/DeferredTestReporter.h" />
<Unit filename="../src/DeferredTestResult.cpp" />
<Unit filename="../src/DeferredTestResult.h" />
<Unit filename="../src/ExecuteTest.h" />
<Unit filename="../src/MemoryOutStream.cpp" />
<Unit filename="../src/MemoryOutStream.h" />
<Unit filename="../src/Posix/SignalTranslator.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/SignalTranslator.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/ReportAssert.cpp" />
<Unit filename="../src/ReportAssert.h" />
<Unit filename="../src/Test.cpp" />
<Unit filename="../src/Test.h" />
<Unit filename="../src/TestDetails.cpp" />
<Unit filename="../src/TestDetails.h" />
<Unit filename="../src/TestList.cpp" />
<Unit filename="../src/TestList.h" />
<Unit filename="../src/TestMacros.h" />
<Unit filename="../src/TestReporter.cpp" />
<Unit filename="../src/TestReporter.h" />
<Unit filename="../src/TestReporterStdout.cpp" />
<Unit filename="../src/TestReporterStdout.h" />
<Unit filename="../src/TestResults.cpp" />
<Unit filename="../src/TestResults.h" />
<Unit filename="../src/TestRunner.cpp" />
<Unit filename="../src/TestRunner.h" />
<Unit filename="../src/TestSuite.h" />
<Unit filename="../src/TimeConstraint.cpp" />
<Unit filename="../src/TimeConstraint.h" />
<Unit filename="../src/TimeHelpers.h" />
<Unit filename="../src/UnitTest++.h" />
<Unit filename="../src/Win32/TimeHelpers.cpp">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/Win32/TimeHelpers.h">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/XmlTestReporter.cpp" />
<Unit filename="../src/XmlTestReporter.h" />
<Extensions>
<envvars />
<code_completion />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

Some things to note about the content of the project file, the power of Code::Blocks.
* there are 4 targets : Debug/Release for Windows and Debug/Release for linux [yes : 1 project file that allows building on linux and on windows]
* some files are only part of the linux targets, some only for the windows targets

But before we build, let's modify some source files (not really needed, but I prefer to have warning free compilations). These are the changes I carried out :
* ReportAssert.cpp : #include "ReportAssert.h"
* win32/TimeHelpers.cpp : first the m_threadHandle and then the m_startTime in the initializerlist

Next open up this project file in Code::Blocks and build the debug and release target. From now one we will only use the Release target, we go for speed ;-)

The result of the build process will show up in subdirectories of the new 'Deliv' subdirectory of <testPit>/UnitTest++ : '''<testPit>/UnitTest++/Deliv/Release/libUnitTest++.a'''

Alright, we have build the unit test framework in a platform independent way, no silly makefiles, no obscure M$ IDE, good old super Code::Blocks. It is time to write some code so we have something to unit test.

In the first example we will create a simple free function that checks if a a give year is a leap your or not.

The business logic is as follows : a year is a leap year when it can be divided by 4, unless itcan be divided by 100. But in case it can be divided by 400, then again it is a leap year.

In the next section we will first setup a Code::Blocks project containing both the 'functionality files, and the unit test files. Typically one will package several functionality files into a static library and create a unit test project that tests all the class/functionalities in that library package, also called a component. That is we have a component (whose deliverable is the static library, and we have a unit test project that tests the entire component).

== Our first test project environment ==
Let's create a new directory in our <TestPit> : <TestPit>/LeapYear.
For the simplicity we will put the project file and the source file all together in this directory. Normally we would work in a more structured way, but in a demo article we have some artistic freedom ;-)
Next you can create with the Code::Block's wizard a new console project in the LeapYear directory. Or you can create the following 5 files and give the the contents as specified below. Note that this demo works on linux and on windows, everything is still completely platform independent. Long Live Code::Blocks.

The project file : LeapYear.cbp (the one below already contains the 5 source files, in case you use the wizard you have to add the LeapYear.h/cpp and LeapYearTest.cpp files to the project)

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="LeapYear" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option output="Deliv/Debug/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Debug/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option output="Deliv/Release/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Release/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-O2" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<Compiler>
<Add option="-Wall" />
<Add option="-fexceptions" />
</Compiler>
<Unit filename="LeapYear.cpp" />
<Unit filename="LeapYear.h" />
<Unit filename="LeapYearTest.cpp" />
<Unit filename="main.cpp" />
<Extensions>
<envvars />
<code_completion />
<lib_finder disable_auto="1" />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

The main source file : main.cpp
int main()
{
return 0;
}

The header exporting our powerful function : LeapYear.h

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

#endif // LEAPYEAR_H_INCLUDED

And the implementation of the leap year logic : LeapYear.cpp

#include "LeapYear.h"

And finishing with the source file for the tests : LeapYearTest.cpp (currently) empty

We can already build the project, we have a nice little program that does .... nothing.

Time to move to the next section, a little word about Test Driven Development.

== Test Driven Development ==
This is a practice where new code is only added to make a failing test pass. And one only adds the code needed to make that test pass. Once that is done, a new test is added to will check the next functionality to add.
On this really simple example we will more or less practice some TDD.

So get ready, it's time for LeapYear-Step1.

== LeapYear-Step1 ==
We will turn our main.cpp into the guy in charge to carry out the tests, all we need to do is change the contents of main.cpp into this :

<source lang="cpp">
#include "UnitTest++.h"

int main()
{
return UnitTest::RunAllTests();
}

</source>
And add '''../UnitTest++/src''' to the compiler search directories on the project level of our LeapYear project.
And add '''../UnitTest++/Deliv/Release/libUnitTest++.a''' to the link libraries of the project

Why : well we need to link with the framework and we need to include the UnitTest++ header so we can use it's functionalities.

The line '''UnitTest::RunAllTests()''' will make sure all test encountered in our sources will be carried out.
We don't have any tests yet, nor any functionality, but go ahead build the project and run it.
This is the output :

Success: 0 tests passed
Test time: 0.00 seconds.

Great : success, but no tests yet. Well it's a start.
Time to move forward, and write our first test.

== LeapYear-Step2 ==
Test, test, but there's nothing to test. Yes, absolutely. Let's think of a test, a test that will help us in the design. Now that's a good idea. Suppose I would be the user of the uplifting problem solving leap year checking library/component ... hmmm modesty first : leap year checking '''function'''.
How would I like that function to look.
<source lang="cpp">
bool IsLeapYear(int Year);
</source>
Yes that seems acceptable.
So let's write a test that will call that method.
We do that by adding the following code to LeapYearTest.cpp

<source lang="cpp">
#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

}

</source>
Things to note :
* we include the unit test header
* it is good to put the tests in nameless namespace (will be explained later on)
* we use the TEST macro, the argument is the name of the test : OurFirstTest
* we use CHECK_EQUAL to check if the expected result (the first argument) matches the computed result (the second argument)

Time to build. Woooooops errors. The tests fails completely, it does not even build. Time to add the code needed.
In order to compiler the test file, we need to include the LeapYear.h header and have that header export our function.
Our LeapYear header will look like this now (don't forget the include in the test file, it is not shown here) :

<source lang="cpp">
#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

bool IsLeapYear(int Year);

#endif // LEAPYEAR_H_INCLUDED

</source>

At least now it compiles, but it doesn't link yet. Duh, that because we don't have an implementation yet.
Time to provide the bare minimum of code to make the test pass.
So we change the LeapYear.cpp into :

<source lang="cpp">
#include "LeapYear.h"

bool IsLeapYear(int /*Year*/)
{
return true;
}

</source>
Build it, run it. Yes, we have one test passed.
Great. Let's move on.

== LeapYear-Step3 ==
Anyone having the feeling we are cheating. Well the user does not know how we wrote our code on the inside. So just to be sure the user (we) adds the following test, ending up in :

<source lang="cpp">
#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

TEST(OurSecondTest)
{
const bool Result = IsLeapYear(1973);
CHECK_EQUAL(false, Result);
}

}

</source>
Building is already no issue any more, we can run it. Oh boy, a test is failing.
The framework tell us something like this :
<filename>:<Line>: error: Failure in OurSecondTest: Expected 0 but was 1
FAILURE: 1 out of 2 tests failed (1 failures)
Test time: 0.00 seconds.

So we are informed of the line where the failing tests occurs, next to that it tells us what it was expecting and what the actual outcome was. And it presents a resume of the total number of tests, and how many that failed. For you scripting hackers note that FAILURE != SUCCESS.

It seems we should do some more effort and implement some real logic.

== LeapYear-Step4 ==
Let's keep it taking one step at a time. Let's start by implementing the 'divisible by 4' logic. That will already solve our tests.
So our LeapYear.cpp will now look like this :

<source lang="cpp">
#include "LeapYear.h"

namespace
{

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year);
}

</source>
Build, run. All tests pass. Life is great.

But those changing requirements, always the change of the requirements. Years that can be divided by 100 should not be considered as a leap year.

Time for our next step.

== LeapYear-Step5 ==
We add a new test for checking for example the year 1900.

<source lang="cpp">
TEST(DivisableBy100)
{
const bool Result = IsLeapYear(1900);
CHECK_EQUAL(false, Result);
}
</source>

Build and run the tests. It will fail. So time to add the minimum code needed to make this test pass.
This will change our LeapYear.cpp into :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year) && !IsDivisableBy100(Year);
}

</source>

Build and run the tests, yes : success. All 3 tests pass.

It seems life might be great again ...

Wrong, someone just added the following test :

<source lang="cpp">
TEST(DivisableBy400)
{
const bool Result = IsLeapYear(2000);
CHECK_EQUAL(true, Result);
}
</source>

And we once again have a failing test.

Time for the next step.

== LeapYear-Step6 ==
We should add logic to deal with years that can be divided by 400, since those are leap years.
We change our LeapYear.cpp into this :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy400(int Year)
{
return (Year%400) == 0;
}

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
const bool LeapYear = IsDivisableBy400(Year) ||
(IsDivisableBy4(Year) && !IsDivisableBy100(Year));
return LeapYear;
}

</source>

And once again everything works OK.
And it seems all the logical rules have been implemented.
This one is ready for shipping, and till the end of time we have our tests that can be run whenever we want (more on this later, we'd prefer this to be done automatically) to ensure we never break anything.

== Increase the user experience ==
There are a few areas where we can increase the user experience.
When a unit test fails the framework tell use on which line in the the code his happens.
That's excellent.
BUT we see this information in a console/shell windows. So we need to find that window, read the issues, remember them and then go find our test source files and navigate manually to the offending line. This works but is very cumbersome.
We want this to be a no-brainer, and have these steps being carried out for us.

Well, didn't we say life is great, Code::Blocks and UnitTest+= to the rescue. The error/warning output of the framework is in the gcc format. That means Code::Blocks can parse it.
One restriction Code::Blocks can parse it during the 'build process'. But currently the build procss stops after the unit test executable is build, and only then we run the test executable (manually).
Solution have Code::Blocks run the test executable as a post-build step. Pre-build and post-build steps are part of the build process !
Important consequence : if you want to debug something, the debugger will only kick off after Code::Blocks was able to carry out a successful build (including the pre/post builds steps). Therefor it is not wise to have the unit test executable being carried out as a post-bild step of the 'Debug' target. But as a post-build step of the Release target, our goal is met.

Adjust the target settings for the 'Release' target [Build Options -> select Release target -> Pre/Post-build steps -> Post-build steps text field] and add the following '''$exe_output'''. you can tick the 'Always execute' if you want.

Now build your Release target, and look at what shows up in the 'Build Log' tab in Code::Blocks.
This is my output :
<pre>

-------------- Build: Release in LeapYear ---------------

[ 25.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/LeapYear.cpp -o Deliv/Release/LeapYear.o
[ 50.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/LeapYearTest.cpp -o Deliv/Release/LeapYearTest.o
[ 75.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/main.cpp -o Deliv/Release/main.o
[100.0%] g++ -o Deliv/Release/LeapYear Deliv/Release/LeapYear.o Deliv/Release/LeapYearTest.o Deliv/Release/main.o -s ../UnitTest++/Deliv/Release/libUnitTest++.a
Output size is 23.28 KB
[100.0%] Running target post-build steps
Deliv/Release/LeapYear
Success: 4 tests passed.
Test time: 0.00 seconds.
Process terminated with status 0 (0 minutes, 2 seconds)
0 errors, 0 warnings
Build log saved as:
file:///home/lieven/Projects/UnitTestArticle/LeapYear/LeapYear_build_log.html
</pre>

We see that the unit test has been carried out, automatically.

Let's demonstrate that upon a failed test, Code::Blocks will jump to the offending line.
Change the latest test, the one checking on the year 2000 : change 2000 to 2001.
And build : Code::Blocks will jump to the offending line, and shows an entry in the "Build messages" tab (error: Failure in DivisableBy400: Expected 1 but was 0), just like for a regular compiler warning/error.
In the "Build" tab, we now find something like (red colored since it is an error) :
<pre>

-------------- Build: Release in LeapYear ---------------

[ 50.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/LeapYearTest.cpp -o Deliv/Release/LeapYearTest.o
[100.0%] g++ -o Deliv/Release/LeapYear Deliv/Release/LeapYear.o Deliv/Release/LeapYearTest.o Deliv/Release/main.o -s ../UnitTest++/Deliv/Release/libUnitTest++.a
Output size is 23.28 KB
[100.0%] Running target post-build steps
Deliv/Release/LeapYear
/home/lieven/Projects/UnitTestArticle/LeapYear/LeapYearTest.cpp:28: error: Failure in DivisableBy400: Expected 1 but was 0
FAILURE: 1 out of 4 tests failed (1 failures).
Test time: 0.00 seconds.
Process terminated with status 1 (0 minutes, 1 seconds)
1 errors, 0 warnings
Build log saved as:
file:///home/lieven/Projects/UnitTestArticle/LeapYear/LeapYear_build_log.html
</pre>

Voila, we have increased the user experience.
Time to readjust the final test, 2001 becomes 2000 again ;-)

== Further automation ==
You can create a script that calls Code::Blocks on the command line and passes it our LeapYear.cbp project file, and it will build both targets (Debug/Release) and run the test, since it is a post-build step for the 'Release' target.
Bye bye funky makefiles, welcome Code::Blocks as your build system.

UnitTesting

2009-09-09T11:25:24Z

Killerbot: /* Increase the user experience */

This document is under development by killerbot. Starting from 7 September 2009.

== Introduction ==
This document will describe how unit testing can be combined with the Code::Blocks IDE. It will give a hands-on example on a unit testing framework and how it can be used with Code::Blocks.

== What is Unit Testing ==
Simply put Unit Testing is the discipline and best practice of writing and running little test programs that test little units of code.
Such a unit can be :
* a class
* a free function
* an interface
* ...
There are several unit test frameworks available to help you write, deploy, manage your unit tests. The most famous family is the xUnit framework, and some of it's descendants.

== Why Unit Testing ==
Well we write code that implements some functionality. We need a way to check and prove that the implementation is correct. Therefor we need tests. We need tests on the application level, at the integration level of different components, classes, interfaces. But we also need tests for the smallest building blocks, the units.
We also wans these tests to run very quickly. That we we can run the tests often, manually or automated.
These tests will also be our safeguards during refactoring of the code, extending the code or whatever maintenance tasks we carry out on the code.
These tests will also make us think of how our class, method, ... will be used. Since the test can be seen as a user of our code. Thanks do this, thinking about the tests before implementing the functionality can help us in the design : emergent design.
It will help us to avoid creating big classes, complex functions. We will only write the methods that are really needed, and no methods that we think might (n)ever be useful in the future. We are no good future tellers ! Those 'might be needed' methods and their tests are just a waste of time. Extending, refactoring will be done when it is actually needed, and at that time we have our unit tests to ensure we don't break any existing code.

Other times to add new unit tests are typically when a bug is discovered; Write a unit test to reproduces the bug, fix the code, and from now on the new unit test will watch your back so the bug won't reappear.

Unit test are also a good place of documentation. The little tests show how the class or method is used.
The code documents itself.

So the benefits are :
* better design
* prove of your code
* safe guard during code maintenance (refactoring, extensions)
* documentation
* ...

== Unit Test frameworks ==
When writing unit tests, one will create a lot of similar code. Since unit tests are nothing more then little programs, several tasks will be repeated, setting up the test environment, create your class, call a method, verify it's result, write out an error message when the test fails, preferably specifying what the wrong outcome was, and what the expected result is.
All these repetitive chores are taken care of by the frame work so the developer can focus on the real code of the test.
This document will use a small but very effective framework for the C++ language. It is called UnitTest++. It's homepage is at : [http://unittest-cpp.sourceforge.net/ UnitTest++].
You can download it directly at this [http://sourceforge.net/projects/unittest-cpp/files/UnitTest%2B%2B/1.4/unittest-cpp-1.4.zip/download link]. At the time of writing the latest version is 1.4.

== Setup our environment ==
Let's create a directory on our PC in which we will cary out our experiments. I will refer to this directory from now on as <TestPit>. For my laptop on which I am writing this article, that will be /home/lieven/Projects/UnitTestArticle. Note that everything we will do, works on linux and on windows!
Download the "unittest-cpp-1.4.zip" file from the link specified above. Extract it in the <TestPit> directory. All the files will end up in the <TestPit>/UnitTest++ directory.

== Build UnitTest++ ==
After the extracted the zip archive we have a directory structure like this :
<TestPit>/UnitTest++
|
+docs
|
+src

The files in the UnitTest++ directory are of little use for us, since they bring project files for some bizarre Microsoft IDE ;-) .
We will create our own Code::Blocks project to build the UnitTest++ framework.

Why do we need to build something ? Well as said, the framework will do a lot of chores for us, those chores are implemented by code, that code is framework. We will build to frame work into a static library, and for every unit test (or set of unit tests) we create a little (console/shell) program with the test code we wrote, which will link with the static library to obtain a unit test executable, driven by the framework.

We will put our Code::Blocks project file in a nice structured directory tree, therefor let's create a 'Project' subdirectory in the <TestPit>/UniTest++ directory.

In there create a new file with the name "UnitTest++.cbp".
Give that file the following content :

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="UnitTest++" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option platforms="Windows;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option platforms="Windows;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
<Target title="Debug(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<VirtualTargets>
<Add alias="All" targets="Debug;Release;Debug(linux);Release(linux);" />
</VirtualTargets>
<Unit filename="../src/AssertException.cpp" />
<Unit filename="../src/AssertException.h" />
<Unit filename="../src/CheckMacros.h" />
<Unit filename="../src/Checks.cpp" />
<Unit filename="../src/Checks.h" />
<Unit filename="../src/Config.h" />
<Unit filename="../src/CurrentTest.cpp" />
<Unit filename="../src/CurrentTest.h" />
<Unit filename="../src/DeferredTestReporter.cpp" />
<Unit filename="../src/DeferredTestReporter.h" />
<Unit filename="../src/DeferredTestResult.cpp" />
<Unit filename="../src/DeferredTestResult.h" />
<Unit filename="../src/ExecuteTest.h" />
<Unit filename="../src/MemoryOutStream.cpp" />
<Unit filename="../src/MemoryOutStream.h" />
<Unit filename="../src/Posix/SignalTranslator.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/SignalTranslator.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/ReportAssert.cpp" />
<Unit filename="../src/ReportAssert.h" />
<Unit filename="../src/Test.cpp" />
<Unit filename="../src/Test.h" />
<Unit filename="../src/TestDetails.cpp" />
<Unit filename="../src/TestDetails.h" />
<Unit filename="../src/TestList.cpp" />
<Unit filename="../src/TestList.h" />
<Unit filename="../src/TestMacros.h" />
<Unit filename="../src/TestReporter.cpp" />
<Unit filename="../src/TestReporter.h" />
<Unit filename="../src/TestReporterStdout.cpp" />
<Unit filename="../src/TestReporterStdout.h" />
<Unit filename="../src/TestResults.cpp" />
<Unit filename="../src/TestResults.h" />
<Unit filename="../src/TestRunner.cpp" />
<Unit filename="../src/TestRunner.h" />
<Unit filename="../src/TestSuite.h" />
<Unit filename="../src/TimeConstraint.cpp" />
<Unit filename="../src/TimeConstraint.h" />
<Unit filename="../src/TimeHelpers.h" />
<Unit filename="../src/UnitTest++.h" />
<Unit filename="../src/Win32/TimeHelpers.cpp">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/Win32/TimeHelpers.h">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/XmlTestReporter.cpp" />
<Unit filename="../src/XmlTestReporter.h" />
<Extensions>
<envvars />
<code_completion />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

Some things to note about the content of the project file, the power of Code::Blocks.
* there are 4 targets : Debug/Release for Windows and Debug/Release for linux [yes : 1 project file that allows building on linux and on windows]
* some files are only part of the linux targets, some only for the windows targets

But before we build, let's modify some source files (not really needed, but I prefer to have warning free compilations). These are the changes I carried out :
* ReportAssert.cpp : #include "ReportAssert.h"
* win32/TimeHelpers.cpp : first the m_threadHandle and then the m_startTime in the initializerlist

Next open up this project file in Code::Blocks and build the debug and release target. From now one we will only use the Release target, we go for speed ;-)

The result of the build process will show up in subdirectories of the new 'Deliv' subdirectory of <testPit>/UnitTest++ : '''<testPit>/UnitTest++/Deliv/Release/libUnitTest++.a'''

Alright, we have build the unit test framework in a platform independent way, no silly makefiles, no obscure M$ IDE, good old super Code::Blocks. It is time to write some code so we have something to unit test.

In the first example we will create a simple free function that checks if a a give year is a leap your or not.

The business logic is as follows : a year is a leap year when it can be divided by 4, unless itcan be divided by 100. But in case it can be divided by 400, then again it is a leap year.

In the next section we will first setup a Code::Blocks project containing both the 'functionality files, and the unit test files. Typically one will package several functionality files into a static library and create a unit test project that tests all the class/functionalities in that library package, also called a component. That is we have a component (whose deliverable is the static library, and we have a unit test project that tests the entire component).

== Our first test project environment ==
Let's create a new directory in our <TestPit> : <TestPit>/LeapYear.
For the simplicity we will put the project file and the source file all together in this directory. Normally we would work in a more structured way, but in a demo article we have some artistic freedom ;-)
Next you can create with the Code::Block's wizard a new console project in the LeapYear directory. Or you can create the following 5 files and give the the contents as specified below. Note that this demo works on linux and on windows, everything is still completely platform independent. Long Live Code::Blocks.

The project file : LeapYear.cbp (the one below already contains the 5 source files, in case you use the wizard you have to add the LeapYear.h/cpp and LeapYearTest.cpp files to the project)

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="LeapYear" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option output="Deliv/Debug/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Debug/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option output="Deliv/Release/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Release/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-O2" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<Compiler>
<Add option="-Wall" />
<Add option="-fexceptions" />
</Compiler>
<Unit filename="LeapYear.cpp" />
<Unit filename="LeapYear.h" />
<Unit filename="LeapYearTest.cpp" />
<Unit filename="main.cpp" />
<Extensions>
<envvars />
<code_completion />
<lib_finder disable_auto="1" />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

The main source file : main.cpp
int main()
{
return 0;
}

The header exporting our powerful function : LeapYear.h

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

#endif // LEAPYEAR_H_INCLUDED

And the implementation of the leap year logic : LeapYear.cpp

#include "LeapYear.h"

And finishing with the source file for the tests : LeapYearTest.cpp (currently) empty

We can already build the project, we have a nice little program that does .... nothing.

Time to move to the next section, a little word about Test Driven Development.

== Test Driven Development ==
This is a practice where new code is only added to make a failing test pass. And one only adds the code needed to make that test pass. Once that is done, a new test is added to will check the next functionality to add.
On this really simple example we will more or less practice some TDD.

So get ready, it's time for LeapYear-Step1.

== LeapYear-Step1 ==
We will turn our main.cpp into the guy in charge to carry out the tests, all we need to do is change the contents of main.cpp into this :

<source lang="cpp">
#include "UnitTest++.h"

int main()
{
return UnitTest::RunAllTests();
}

</source>
And add '''../UnitTest++/src''' to the compiler search directories on the project level of our LeapYear project.
And add '''../UnitTest++/Deliv/Release/libUnitTest++.a''' to the link libraries of the project

Why : well we need to link with the framework and we need to include the UnitTest++ header so we can use it's functionalities.

The line '''UnitTest::RunAllTests()''' will make sure all test encountered in our sources will be carried out.
We don't have any tests yet, nor any functionality, but go ahead build the project and run it.
This is the output :

Success: 0 tests passed
Test time: 0.00 seconds.

Great : success, but no tests yet. Well it's a start.
Time to move forward, and write our first test.

== LeapYear-Step2 ==
Test, test, but there's nothing to test. Yes, absolutely. Let's think of a test, a test that will help us in the design. Now that's a good idea. Suppose I would be the user of the uplifting problem solving leap year checking library/component ... hmmm modesty first : leap year checking '''function'''.
How would I like that function to look.
<source lang="cpp">
bool IsLeapYear(int Year);
</source>
Yes that seems acceptable.
So let's write a test that will call that method.
We do that by adding the following code to LeapYearTest.cpp

<source lang="cpp">
#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

}

</source>
Things to note :
* we include the unit test header
* it is good to put the tests in nameless namespace (will be explained later on)
* we use the TEST macro, the argument is the name of the test : OurFirstTest
* we use CHECK_EQUAL to check if the expected result (the first argument) matches the computed result (the second argument)

Time to build. Woooooops errors. The tests fails completely, it does not even build. Time to add the code needed.
In order to compiler the test file, we need to include the LeapYear.h header and have that header export our function.
Our LeapYear header will look like this now (don't forget the include in the test file, it is not shown here) :

<source lang="cpp">
#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

bool IsLeapYear(int Year);

#endif // LEAPYEAR_H_INCLUDED

</source>

At least now it compiles, but it doesn't link yet. Duh, that because we don't have an implementation yet.
Time to provide the bare minimum of code to make the test pass.
So we change the LeapYear.cpp into :

<source lang="cpp">
#include "LeapYear.h"

bool IsLeapYear(int /*Year*/)
{
return true;
}

</source>
Build it, run it. Yes, we have one test passed.
Great. Let's move on.

== LeapYear-Step3 ==
Anyone having the feeling we are cheating. Well the user does not know how we wrote our code on the inside. So just to be sure the user (we) adds the following test, ending up in :

<source lang="cpp">
#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

TEST(OurSecondTest)
{
const bool Result = IsLeapYear(1973);
CHECK_EQUAL(false, Result);
}

}

</source>
Building is already no issue any more, we can run it. Oh boy, a test is failing.
The framework tell us something like this :
<filename>:<Line>: error: Failure in OurSecondTest: Expected 0 but was 1
FAILURE: 1 out of 2 tests failed (1 failures)
Test time: 0.00 seconds.

So we are informed of the line where the failing tests occurs, next to that it tells us what it was expecting and what the actual outcome was. And it presents a resume of the total number of tests, and how many that failed. For you scripting hackers note that FAILURE != SUCCESS.

It seems we should do some more effort and implement some real logic.

== LeapYear-Step4 ==
Let's keep it taking one step at a time. Let's start by implementing the 'divisible by 4' logic. That will already solve our tests.
So our LeapYear.cpp will now look like this :

<source lang="cpp">
#include "LeapYear.h"

namespace
{

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year);
}

</source>
Build, run. All tests pass. Life is great.

But those changing requirements, always the change of the requirements. Years that can be divided by 100 should not be considered as a leap year.

Time for our next step.

== LeapYear-Step5 ==
We add a new test for checking for example the year 1900.

<source lang="cpp">
TEST(DivisableBy100)
{
const bool Result = IsLeapYear(1900);
CHECK_EQUAL(false, Result);
}
</source>

Build and run the tests. It will fail. So time to add the minimum code needed to make this test pass.
This will change our LeapYear.cpp into :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year) && !IsDivisableBy100(Year);
}

</source>

Build and run the tests, yes : success. All 3 tests pass.

It seems life might be great again ...

Wrong, someone just added the following test :

<source lang="cpp">
TEST(DivisableBy400)
{
const bool Result = IsLeapYear(2000);
CHECK_EQUAL(true, Result);
}
</source>

And we once again have a failing test.

Time for the next step.

== LeapYear-Step6 ==
We should add logic to deal with years that can be divided by 400, since those are leap years.
We change our LeapYear.cpp into this :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy400(int Year)
{
return (Year%400) == 0;
}

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
const bool LeapYear = IsDivisableBy400(Year) ||
(IsDivisableBy4(Year) && !IsDivisableBy100(Year));
return LeapYear;
}

</source>

And once again everything works OK.
And it seems all the logical rules have been implemented.
This one is ready for shipping, and till the end of time we have our tests that can be run whenever we want (more on this later, we'd prefer this to be done automatically) to ensure we never break anything.

== Increase the user experience ==
There are a few areas where we can increase the user experience.
When a unit test fails the framework tell use on which line in the the code his happens.
That's excellent.
BUT we see this information in a console/shell windows. So we need to find that window, read the issues, remember them and then go find our test source files and navigate manually to the offending line. This works but is very cumbersome.
We want this to be a no-brainer, and have these steps being carried out for us.

Well, didn't we say life is great, Code::Blocks and UnitTest+= to the rescue. The error/warning output of the framework is in the gcc format. That means Code::Blocks can parse it.
One restriction Code::Blocks can parse it during the 'build process'. But currently the build procss stops after the unit test executable is build, and only then we run the test executable (manually).
Solution have Code::Blocks run the test executable as a post-build step. Pre-build and post-build steps are part of the build process !
Important consequence : if you want to debug something, the debugger will only kick off after Code::Blocks was able to carry out a successful build (including the pre/post builds steps). Therefor it is not wise to have the unit test executable being carried out as a post-bild step of the 'Debug' target. But as a post-build step of the Release target, our goal is met.

Adjust the target settings for the 'Release' target [Build Options -> select Release target -> Pre/Post-build steps -> Post-build steps text field] and add the following '''$exe_output'''. you can tick the 'Always execute' if you want.

Now build your Release target, and look at what shows up in the 'Build Log' tab in Code::Blocks.
This is my output :
<pre>

-------------- Build: Release in LeapYear ---------------

[ 25.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/LeapYear.cpp -o Deliv/Release/LeapYear.o
[ 50.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/LeapYearTest.cpp -o Deliv/Release/LeapYearTest.o
[ 75.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/main.cpp -o Deliv/Release/main.o
[100.0%] g++ -o Deliv/Release/LeapYear Deliv/Release/LeapYear.o Deliv/Release/LeapYearTest.o Deliv/Release/main.o -s ../UnitTest++/Deliv/Release/libUnitTest++.a
Output size is 23.28 KB
[100.0%] Running target post-build steps
Deliv/Release/LeapYear
Success: 4 tests passed.
Test time: 0.00 seconds.
Process terminated with status 0 (0 minutes, 2 seconds)
0 errors, 0 warnings
Build log saved as:
file:///home/lieven/Projects/UnitTestArticle/LeapYear/LeapYear_build_log.html
</pre>

We see that the unit test has been carried out, automatically.

Let's demonstrate that upon a failed test, Code::Blocks will jump to the offending line.
Change the latest test, the one checking on the year 2000 : change 2000 to 2001.
And build : Code::Blocks will jump to the offending line, and shows an entry in the "Build messages" tab (error: Failure in DivisableBy400: Expected 1 but was 0), just like for a regular compiler warning/error.
In the "Build" tab, we now find something like (red colored since it is an error) :
<pre>

-------------- Build: Release in LeapYear ---------------

[ 50.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/LeapYearTest.cpp -o Deliv/Release/LeapYearTest.o
[100.0%] g++ -o Deliv/Release/LeapYear Deliv/Release/LeapYear.o Deliv/Release/LeapYearTest.o Deliv/Release/main.o -s ../UnitTest++/Deliv/Release/libUnitTest++.a
Output size is 23.28 KB
[100.0%] Running target post-build steps
Deliv/Release/LeapYear
/home/lieven/Projects/UnitTestArticle/LeapYear/LeapYearTest.cpp:28: error: Failure in DivisableBy400: Expected 1 but was 0
FAILURE: 1 out of 4 tests failed (1 failures).
Test time: 0.00 seconds.
Process terminated with status 1 (0 minutes, 1 seconds)
1 errors, 0 warnings
Build log saved as:
file:///home/lieven/Projects/UnitTestArticle/LeapYear/LeapYear_build_log.html
</pre>

Voila, we have increased the user experience.

== Further automation ==
You can create a script that calls Code::Blocks on the command line and passes it our LeapYear.cbp project file, and it will build both targets (Debug/Release) and run the test, since it is a post-build step for the 'Release' target.
Bye bye funky makefiles, welcome Code::Blocks as your build system.

UnitTesting

2009-09-09T11:18:54Z

Killerbot: /* LeapYear-Step6 */

This document is under development by killerbot. Starting from 7 September 2009.

== Introduction ==
This document will describe how unit testing can be combined with the Code::Blocks IDE. It will give a hands-on example on a unit testing framework and how it can be used with Code::Blocks.

== What is Unit Testing ==
Simply put Unit Testing is the discipline and best practice of writing and running little test programs that test little units of code.
Such a unit can be :
* a class
* a free function
* an interface
* ...
There are several unit test frameworks available to help you write, deploy, manage your unit tests. The most famous family is the xUnit framework, and some of it's descendants.

== Why Unit Testing ==
Well we write code that implements some functionality. We need a way to check and prove that the implementation is correct. Therefor we need tests. We need tests on the application level, at the integration level of different components, classes, interfaces. But we also need tests for the smallest building blocks, the units.
We also wans these tests to run very quickly. That we we can run the tests often, manually or automated.
These tests will also be our safeguards during refactoring of the code, extending the code or whatever maintenance tasks we carry out on the code.
These tests will also make us think of how our class, method, ... will be used. Since the test can be seen as a user of our code. Thanks do this, thinking about the tests before implementing the functionality can help us in the design : emergent design.
It will help us to avoid creating big classes, complex functions. We will only write the methods that are really needed, and no methods that we think might (n)ever be useful in the future. We are no good future tellers ! Those 'might be needed' methods and their tests are just a waste of time. Extending, refactoring will be done when it is actually needed, and at that time we have our unit tests to ensure we don't break any existing code.

Other times to add new unit tests are typically when a bug is discovered; Write a unit test to reproduces the bug, fix the code, and from now on the new unit test will watch your back so the bug won't reappear.

Unit test are also a good place of documentation. The little tests show how the class or method is used.
The code documents itself.

So the benefits are :
* better design
* prove of your code
* safe guard during code maintenance (refactoring, extensions)
* documentation
* ...

== Unit Test frameworks ==
When writing unit tests, one will create a lot of similar code. Since unit tests are nothing more then little programs, several tasks will be repeated, setting up the test environment, create your class, call a method, verify it's result, write out an error message when the test fails, preferably specifying what the wrong outcome was, and what the expected result is.
All these repetitive chores are taken care of by the frame work so the developer can focus on the real code of the test.
This document will use a small but very effective framework for the C++ language. It is called UnitTest++. It's homepage is at : [http://unittest-cpp.sourceforge.net/ UnitTest++].
You can download it directly at this [http://sourceforge.net/projects/unittest-cpp/files/UnitTest%2B%2B/1.4/unittest-cpp-1.4.zip/download link]. At the time of writing the latest version is 1.4.

== Setup our environment ==
Let's create a directory on our PC in which we will cary out our experiments. I will refer to this directory from now on as <TestPit>. For my laptop on which I am writing this article, that will be /home/lieven/Projects/UnitTestArticle. Note that everything we will do, works on linux and on windows!
Download the "unittest-cpp-1.4.zip" file from the link specified above. Extract it in the <TestPit> directory. All the files will end up in the <TestPit>/UnitTest++ directory.

== Build UnitTest++ ==
After the extracted the zip archive we have a directory structure like this :
<TestPit>/UnitTest++
|
+docs
|
+src

The files in the UnitTest++ directory are of little use for us, since they bring project files for some bizarre Microsoft IDE ;-) .
We will create our own Code::Blocks project to build the UnitTest++ framework.

Why do we need to build something ? Well as said, the framework will do a lot of chores for us, those chores are implemented by code, that code is framework. We will build to frame work into a static library, and for every unit test (or set of unit tests) we create a little (console/shell) program with the test code we wrote, which will link with the static library to obtain a unit test executable, driven by the framework.

We will put our Code::Blocks project file in a nice structured directory tree, therefor let's create a 'Project' subdirectory in the <TestPit>/UniTest++ directory.

In there create a new file with the name "UnitTest++.cbp".
Give that file the following content :

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="UnitTest++" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option platforms="Windows;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option platforms="Windows;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
<Target title="Debug(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<VirtualTargets>
<Add alias="All" targets="Debug;Release;Debug(linux);Release(linux);" />
</VirtualTargets>
<Unit filename="../src/AssertException.cpp" />
<Unit filename="../src/AssertException.h" />
<Unit filename="../src/CheckMacros.h" />
<Unit filename="../src/Checks.cpp" />
<Unit filename="../src/Checks.h" />
<Unit filename="../src/Config.h" />
<Unit filename="../src/CurrentTest.cpp" />
<Unit filename="../src/CurrentTest.h" />
<Unit filename="../src/DeferredTestReporter.cpp" />
<Unit filename="../src/DeferredTestReporter.h" />
<Unit filename="../src/DeferredTestResult.cpp" />
<Unit filename="../src/DeferredTestResult.h" />
<Unit filename="../src/ExecuteTest.h" />
<Unit filename="../src/MemoryOutStream.cpp" />
<Unit filename="../src/MemoryOutStream.h" />
<Unit filename="../src/Posix/SignalTranslator.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/SignalTranslator.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/ReportAssert.cpp" />
<Unit filename="../src/ReportAssert.h" />
<Unit filename="../src/Test.cpp" />
<Unit filename="../src/Test.h" />
<Unit filename="../src/TestDetails.cpp" />
<Unit filename="../src/TestDetails.h" />
<Unit filename="../src/TestList.cpp" />
<Unit filename="../src/TestList.h" />
<Unit filename="../src/TestMacros.h" />
<Unit filename="../src/TestReporter.cpp" />
<Unit filename="../src/TestReporter.h" />
<Unit filename="../src/TestReporterStdout.cpp" />
<Unit filename="../src/TestReporterStdout.h" />
<Unit filename="../src/TestResults.cpp" />
<Unit filename="../src/TestResults.h" />
<Unit filename="../src/TestRunner.cpp" />
<Unit filename="../src/TestRunner.h" />
<Unit filename="../src/TestSuite.h" />
<Unit filename="../src/TimeConstraint.cpp" />
<Unit filename="../src/TimeConstraint.h" />
<Unit filename="../src/TimeHelpers.h" />
<Unit filename="../src/UnitTest++.h" />
<Unit filename="../src/Win32/TimeHelpers.cpp">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/Win32/TimeHelpers.h">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/XmlTestReporter.cpp" />
<Unit filename="../src/XmlTestReporter.h" />
<Extensions>
<envvars />
<code_completion />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

Some things to note about the content of the project file, the power of Code::Blocks.
* there are 4 targets : Debug/Release for Windows and Debug/Release for linux [yes : 1 project file that allows building on linux and on windows]
* some files are only part of the linux targets, some only for the windows targets

But before we build, let's modify some source files (not really needed, but I prefer to have warning free compilations). These are the changes I carried out :
* ReportAssert.cpp : #include "ReportAssert.h"
* win32/TimeHelpers.cpp : first the m_threadHandle and then the m_startTime in the initializerlist

Next open up this project file in Code::Blocks and build the debug and release target. From now one we will only use the Release target, we go for speed ;-)

The result of the build process will show up in subdirectories of the new 'Deliv' subdirectory of <testPit>/UnitTest++ : '''<testPit>/UnitTest++/Deliv/Release/libUnitTest++.a'''

Alright, we have build the unit test framework in a platform independent way, no silly makefiles, no obscure M$ IDE, good old super Code::Blocks. It is time to write some code so we have something to unit test.

In the first example we will create a simple free function that checks if a a give year is a leap your or not.

The business logic is as follows : a year is a leap year when it can be divided by 4, unless itcan be divided by 100. But in case it can be divided by 400, then again it is a leap year.

In the next section we will first setup a Code::Blocks project containing both the 'functionality files, and the unit test files. Typically one will package several functionality files into a static library and create a unit test project that tests all the class/functionalities in that library package, also called a component. That is we have a component (whose deliverable is the static library, and we have a unit test project that tests the entire component).

== Our first test project environment ==
Let's create a new directory in our <TestPit> : <TestPit>/LeapYear.
For the simplicity we will put the project file and the source file all together in this directory. Normally we would work in a more structured way, but in a demo article we have some artistic freedom ;-)
Next you can create with the Code::Block's wizard a new console project in the LeapYear directory. Or you can create the following 5 files and give the the contents as specified below. Note that this demo works on linux and on windows, everything is still completely platform independent. Long Live Code::Blocks.

The project file : LeapYear.cbp (the one below already contains the 5 source files, in case you use the wizard you have to add the LeapYear.h/cpp and LeapYearTest.cpp files to the project)

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="LeapYear" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option output="Deliv/Debug/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Debug/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option output="Deliv/Release/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Release/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-O2" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<Compiler>
<Add option="-Wall" />
<Add option="-fexceptions" />
</Compiler>
<Unit filename="LeapYear.cpp" />
<Unit filename="LeapYear.h" />
<Unit filename="LeapYearTest.cpp" />
<Unit filename="main.cpp" />
<Extensions>
<envvars />
<code_completion />
<lib_finder disable_auto="1" />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

The main source file : main.cpp
int main()
{
return 0;
}

The header exporting our powerful function : LeapYear.h

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

#endif // LEAPYEAR_H_INCLUDED

And the implementation of the leap year logic : LeapYear.cpp

#include "LeapYear.h"

And finishing with the source file for the tests : LeapYearTest.cpp (currently) empty

We can already build the project, we have a nice little program that does .... nothing.

Time to move to the next section, a little word about Test Driven Development.

== Test Driven Development ==
This is a practice where new code is only added to make a failing test pass. And one only adds the code needed to make that test pass. Once that is done, a new test is added to will check the next functionality to add.
On this really simple example we will more or less practice some TDD.

So get ready, it's time for LeapYear-Step1.

== LeapYear-Step1 ==
We will turn our main.cpp into the guy in charge to carry out the tests, all we need to do is change the contents of main.cpp into this :

<source lang="cpp">
#include "UnitTest++.h"

int main()
{
return UnitTest::RunAllTests();
}

</source>
And add '''../UnitTest++/src''' to the compiler search directories on the project level of our LeapYear project.
And add '''../UnitTest++/Deliv/Release/libUnitTest++.a''' to the link libraries of the project

Why : well we need to link with the framework and we need to include the UnitTest++ header so we can use it's functionalities.

The line '''UnitTest::RunAllTests()''' will make sure all test encountered in our sources will be carried out.
We don't have any tests yet, nor any functionality, but go ahead build the project and run it.
This is the output :

Success: 0 tests passed
Test time: 0.00 seconds.

Great : success, but no tests yet. Well it's a start.
Time to move forward, and write our first test.

== LeapYear-Step2 ==
Test, test, but there's nothing to test. Yes, absolutely. Let's think of a test, a test that will help us in the design. Now that's a good idea. Suppose I would be the user of the uplifting problem solving leap year checking library/component ... hmmm modesty first : leap year checking '''function'''.
How would I like that function to look.
<source lang="cpp">
bool IsLeapYear(int Year);
</source>
Yes that seems acceptable.
So let's write a test that will call that method.
We do that by adding the following code to LeapYearTest.cpp

<source lang="cpp">
#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

}

</source>
Things to note :
* we include the unit test header
* it is good to put the tests in nameless namespace (will be explained later on)
* we use the TEST macro, the argument is the name of the test : OurFirstTest
* we use CHECK_EQUAL to check if the expected result (the first argument) matches the computed result (the second argument)

Time to build. Woooooops errors. The tests fails completely, it does not even build. Time to add the code needed.
In order to compiler the test file, we need to include the LeapYear.h header and have that header export our function.
Our LeapYear header will look like this now (don't forget the include in the test file, it is not shown here) :

<source lang="cpp">
#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

bool IsLeapYear(int Year);

#endif // LEAPYEAR_H_INCLUDED

</source>

At least now it compiles, but it doesn't link yet. Duh, that because we don't have an implementation yet.
Time to provide the bare minimum of code to make the test pass.
So we change the LeapYear.cpp into :

<source lang="cpp">
#include "LeapYear.h"

bool IsLeapYear(int /*Year*/)
{
return true;
}

</source>
Build it, run it. Yes, we have one test passed.
Great. Let's move on.

== LeapYear-Step3 ==
Anyone having the feeling we are cheating. Well the user does not know how we wrote our code on the inside. So just to be sure the user (we) adds the following test, ending up in :

<source lang="cpp">
#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

TEST(OurSecondTest)
{
const bool Result = IsLeapYear(1973);
CHECK_EQUAL(false, Result);
}

}

</source>
Building is already no issue any more, we can run it. Oh boy, a test is failing.
The framework tell us something like this :
<filename>:<Line>: error: Failure in OurSecondTest: Expected 0 but was 1
FAILURE: 1 out of 2 tests failed (1 failures)
Test time: 0.00 seconds.

So we are informed of the line where the failing tests occurs, next to that it tells us what it was expecting and what the actual outcome was. And it presents a resume of the total number of tests, and how many that failed. For you scripting hackers note that FAILURE != SUCCESS.

It seems we should do some more effort and implement some real logic.

== LeapYear-Step4 ==
Let's keep it taking one step at a time. Let's start by implementing the 'divisible by 4' logic. That will already solve our tests.
So our LeapYear.cpp will now look like this :

<source lang="cpp">
#include "LeapYear.h"

namespace
{

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year);
}

</source>
Build, run. All tests pass. Life is great.

But those changing requirements, always the change of the requirements. Years that can be divided by 100 should not be considered as a leap year.

Time for our next step.

== LeapYear-Step5 ==
We add a new test for checking for example the year 1900.

<source lang="cpp">
TEST(DivisableBy100)
{
const bool Result = IsLeapYear(1900);
CHECK_EQUAL(false, Result);
}
</source>

Build and run the tests. It will fail. So time to add the minimum code needed to make this test pass.
This will change our LeapYear.cpp into :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year) && !IsDivisableBy100(Year);
}

</source>

Build and run the tests, yes : success. All 3 tests pass.

It seems life might be great again ...

Wrong, someone just added the following test :

<source lang="cpp">
TEST(DivisableBy400)
{
const bool Result = IsLeapYear(2000);
CHECK_EQUAL(true, Result);
}
</source>

And we once again have a failing test.

Time for the next step.

== LeapYear-Step6 ==
We should add logic to deal with years that can be divided by 400, since those are leap years.
We change our LeapYear.cpp into this :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy400(int Year)
{
return (Year%400) == 0;
}

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
const bool LeapYear = IsDivisableBy400(Year) ||
(IsDivisableBy4(Year) && !IsDivisableBy100(Year));
return LeapYear;
}

</source>

And once again everything works OK.
And it seems all the logical rules have been implemented.
This one is ready for shipping, and till the end of time we have our tests that can be run whenever we want (more on this later, we'd prefer this to be done automatically) to ensure we never break anything.

== Increase the user experience ==
There are a few areas where we can increase the user experience.
When a unit test fails the framework tell use on which line in the the code his happens.
That's excellent.
BUT we see this information in a console/shell windows. So we need to find that window, read the issues, remember them and then go find our test source files and navigate manually to the offending line. This works but is very cumbersome.
We want this to be a no-brainer, and have these steps being carried out for us.

Well, didn't we say life is great, Code::Blocks and UnitTest+= to the rescue. The error/warning output of the framework is in the gcc format. That means Code::Blocks can parse it.
One restriction Code::Blocks can parse it during the 'build process'. But currently the build procss stops after the unit test executable is build, and only then we run the test executable (manually).
Solution have Code::Blocks run the test executable as a post-build step. Pre-build and post-build steps are part of the build process !
Important consequence : if you want to debug something, the debugger will only kick off after Code::Blocks was able to carry out a successful build (including the pre/post builds steps). Therefor it is not wise to have the unit test executable being carried out as a post-bild step of the 'Debug' target. But as a post-build step of the Release target, our goal is met.

Adjust the target settings for the 'Release' target [Build Options -> select Release target -> Pre/Post-build steps -> Post-build steps text field] and add the following '''$exe_output'''. you can tick the 'Always execute' if you want.

Now build your Release target, and look at what shows up in the 'Build Log' tab in Code::Blocks.
This is my output :
<pre>

-------------- Build: Release in LeapYear ---------------

[ 25.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/LeapYear.cpp -o Deliv/Release/LeapYear.o
[ 50.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/LeapYearTest.cpp -o Deliv/Release/LeapYearTest.o
[ 75.0%] g++ -Wall -fexceptions -O2 -Wshadow -Winit-self -Wmissing-declarations -Wmissing-include-dirs -Wswitch-default -Wmain -Wextra -Wall -I../UnitTest++/src -c /home/lieven/Projects/UnitTestArticle/LeapYear/main.cpp -o Deliv/Release/main.o
[100.0%] g++ -o Deliv/Release/LeapYear Deliv/Release/LeapYear.o Deliv/Release/LeapYearTest.o Deliv/Release/main.o -s ../UnitTest++/Deliv/Release/libUnitTest++.a
Output size is 23.28 KB
[100.0%] Running target post-build steps
Deliv/Release/LeapYear
Success: 4 tests passed.
Test time: 0.00 seconds.
Process terminated with status 0 (0 minutes, 2 seconds)
0 errors, 0 warnings
Build log saved as:
file:///home/lieven/Projects/UnitTestArticle/LeapYear/LeapYear_build_log.html
</pre>

We see that the unit test has been carried out, automatically.

UnitTesting

2009-09-09T11:04:42Z

Killerbot: /* LeapYear-Step4 */

This document is under development by killerbot. Starting from 7 September 2009.

== Introduction ==
This document will describe how unit testing can be combined with the Code::Blocks IDE. It will give a hands-on example on a unit testing framework and how it can be used with Code::Blocks.

== What is Unit Testing ==
Simply put Unit Testing is the discipline and best practice of writing and running little test programs that test little units of code.
Such a unit can be :
* a class
* a free function
* an interface
* ...
There are several unit test frameworks available to help you write, deploy, manage your unit tests. The most famous family is the xUnit framework, and some of it's descendants.

== Why Unit Testing ==
Well we write code that implements some functionality. We need a way to check and prove that the implementation is correct. Therefor we need tests. We need tests on the application level, at the integration level of different components, classes, interfaces. But we also need tests for the smallest building blocks, the units.
We also wans these tests to run very quickly. That we we can run the tests often, manually or automated.
These tests will also be our safeguards during refactoring of the code, extending the code or whatever maintenance tasks we carry out on the code.
These tests will also make us think of how our class, method, ... will be used. Since the test can be seen as a user of our code. Thanks do this, thinking about the tests before implementing the functionality can help us in the design : emergent design.
It will help us to avoid creating big classes, complex functions. We will only write the methods that are really needed, and no methods that we think might (n)ever be useful in the future. We are no good future tellers ! Those 'might be needed' methods and their tests are just a waste of time. Extending, refactoring will be done when it is actually needed, and at that time we have our unit tests to ensure we don't break any existing code.

Other times to add new unit tests are typically when a bug is discovered; Write a unit test to reproduces the bug, fix the code, and from now on the new unit test will watch your back so the bug won't reappear.

Unit test are also a good place of documentation. The little tests show how the class or method is used.
The code documents itself.

So the benefits are :
* better design
* prove of your code
* safe guard during code maintenance (refactoring, extensions)
* documentation
* ...

== Unit Test frameworks ==
When writing unit tests, one will create a lot of similar code. Since unit tests are nothing more then little programs, several tasks will be repeated, setting up the test environment, create your class, call a method, verify it's result, write out an error message when the test fails, preferably specifying what the wrong outcome was, and what the expected result is.
All these repetitive chores are taken care of by the frame work so the developer can focus on the real code of the test.
This document will use a small but very effective framework for the C++ language. It is called UnitTest++. It's homepage is at : [http://unittest-cpp.sourceforge.net/ UnitTest++].
You can download it directly at this [http://sourceforge.net/projects/unittest-cpp/files/UnitTest%2B%2B/1.4/unittest-cpp-1.4.zip/download link]. At the time of writing the latest version is 1.4.

== Setup our environment ==
Let's create a directory on our PC in which we will cary out our experiments. I will refer to this directory from now on as <TestPit>. For my laptop on which I am writing this article, that will be /home/lieven/Projects/UnitTestArticle. Note that everything we will do, works on linux and on windows!
Download the "unittest-cpp-1.4.zip" file from the link specified above. Extract it in the <TestPit> directory. All the files will end up in the <TestPit>/UnitTest++ directory.

== Build UnitTest++ ==
After the extracted the zip archive we have a directory structure like this :
<TestPit>/UnitTest++
|
+docs
|
+src

The files in the UnitTest++ directory are of little use for us, since they bring project files for some bizarre Microsoft IDE ;-) .
We will create our own Code::Blocks project to build the UnitTest++ framework.

Why do we need to build something ? Well as said, the framework will do a lot of chores for us, those chores are implemented by code, that code is framework. We will build to frame work into a static library, and for every unit test (or set of unit tests) we create a little (console/shell) program with the test code we wrote, which will link with the static library to obtain a unit test executable, driven by the framework.

We will put our Code::Blocks project file in a nice structured directory tree, therefor let's create a 'Project' subdirectory in the <TestPit>/UniTest++ directory.

In there create a new file with the name "UnitTest++.cbp".
Give that file the following content :

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="UnitTest++" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option platforms="Windows;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option platforms="Windows;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
<Target title="Debug(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<VirtualTargets>
<Add alias="All" targets="Debug;Release;Debug(linux);Release(linux);" />
</VirtualTargets>
<Unit filename="../src/AssertException.cpp" />
<Unit filename="../src/AssertException.h" />
<Unit filename="../src/CheckMacros.h" />
<Unit filename="../src/Checks.cpp" />
<Unit filename="../src/Checks.h" />
<Unit filename="../src/Config.h" />
<Unit filename="../src/CurrentTest.cpp" />
<Unit filename="../src/CurrentTest.h" />
<Unit filename="../src/DeferredTestReporter.cpp" />
<Unit filename="../src/DeferredTestReporter.h" />
<Unit filename="../src/DeferredTestResult.cpp" />
<Unit filename="../src/DeferredTestResult.h" />
<Unit filename="../src/ExecuteTest.h" />
<Unit filename="../src/MemoryOutStream.cpp" />
<Unit filename="../src/MemoryOutStream.h" />
<Unit filename="../src/Posix/SignalTranslator.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/SignalTranslator.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/ReportAssert.cpp" />
<Unit filename="../src/ReportAssert.h" />
<Unit filename="../src/Test.cpp" />
<Unit filename="../src/Test.h" />
<Unit filename="../src/TestDetails.cpp" />
<Unit filename="../src/TestDetails.h" />
<Unit filename="../src/TestList.cpp" />
<Unit filename="../src/TestList.h" />
<Unit filename="../src/TestMacros.h" />
<Unit filename="../src/TestReporter.cpp" />
<Unit filename="../src/TestReporter.h" />
<Unit filename="../src/TestReporterStdout.cpp" />
<Unit filename="../src/TestReporterStdout.h" />
<Unit filename="../src/TestResults.cpp" />
<Unit filename="../src/TestResults.h" />
<Unit filename="../src/TestRunner.cpp" />
<Unit filename="../src/TestRunner.h" />
<Unit filename="../src/TestSuite.h" />
<Unit filename="../src/TimeConstraint.cpp" />
<Unit filename="../src/TimeConstraint.h" />
<Unit filename="../src/TimeHelpers.h" />
<Unit filename="../src/UnitTest++.h" />
<Unit filename="../src/Win32/TimeHelpers.cpp">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/Win32/TimeHelpers.h">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/XmlTestReporter.cpp" />
<Unit filename="../src/XmlTestReporter.h" />
<Extensions>
<envvars />
<code_completion />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

Some things to note about the content of the project file, the power of Code::Blocks.
* there are 4 targets : Debug/Release for Windows and Debug/Release for linux [yes : 1 project file that allows building on linux and on windows]
* some files are only part of the linux targets, some only for the windows targets

But before we build, let's modify some source files (not really needed, but I prefer to have warning free compilations). These are the changes I carried out :
* ReportAssert.cpp : #include "ReportAssert.h"
* win32/TimeHelpers.cpp : first the m_threadHandle and then the m_startTime in the initializerlist

Next open up this project file in Code::Blocks and build the debug and release target. From now one we will only use the Release target, we go for speed ;-)

The result of the build process will show up in subdirectories of the new 'Deliv' subdirectory of <testPit>/UnitTest++ : '''<testPit>/UnitTest++/Deliv/Release/libUnitTest++.a'''

Alright, we have build the unit test framework in a platform independent way, no silly makefiles, no obscure M$ IDE, good old super Code::Blocks. It is time to write some code so we have something to unit test.

In the first example we will create a simple free function that checks if a a give year is a leap your or not.

The business logic is as follows : a year is a leap year when it can be divided by 4, unless itcan be divided by 100. But in case it can be divided by 400, then again it is a leap year.

In the next section we will first setup a Code::Blocks project containing both the 'functionality files, and the unit test files. Typically one will package several functionality files into a static library and create a unit test project that tests all the class/functionalities in that library package, also called a component. That is we have a component (whose deliverable is the static library, and we have a unit test project that tests the entire component).

== Our first test project environment ==
Let's create a new directory in our <TestPit> : <TestPit>/LeapYear.
For the simplicity we will put the project file and the source file all together in this directory. Normally we would work in a more structured way, but in a demo article we have some artistic freedom ;-)
Next you can create with the Code::Block's wizard a new console project in the LeapYear directory. Or you can create the following 5 files and give the the contents as specified below. Note that this demo works on linux and on windows, everything is still completely platform independent. Long Live Code::Blocks.

The project file : LeapYear.cbp (the one below already contains the 5 source files, in case you use the wizard you have to add the LeapYear.h/cpp and LeapYearTest.cpp files to the project)

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="LeapYear" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option output="Deliv/Debug/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Debug/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option output="Deliv/Release/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Release/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-O2" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<Compiler>
<Add option="-Wall" />
<Add option="-fexceptions" />
</Compiler>
<Unit filename="LeapYear.cpp" />
<Unit filename="LeapYear.h" />
<Unit filename="LeapYearTest.cpp" />
<Unit filename="main.cpp" />
<Extensions>
<envvars />
<code_completion />
<lib_finder disable_auto="1" />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

The main source file : main.cpp
int main()
{
return 0;
}

The header exporting our powerful function : LeapYear.h

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

#endif // LEAPYEAR_H_INCLUDED

And the implementation of the leap year logic : LeapYear.cpp

#include "LeapYear.h"

And finishing with the source file for the tests : LeapYearTest.cpp (currently) empty

We can already build the project, we have a nice little program that does .... nothing.

Time to move to the next section, a little word about Test Driven Development.

== Test Driven Development ==
This is a practice where new code is only added to make a failing test pass. And one only adds the code needed to make that test pass. Once that is done, a new test is added to will check the next functionality to add.
On this really simple example we will more or less practice some TDD.

So get ready, it's time for LeapYear-Step1.

== LeapYear-Step1 ==
We will turn our main.cpp into the guy in charge to carry out the tests, all we need to do is change the contents of main.cpp into this :

<source lang="cpp">
#include "UnitTest++.h"

int main()
{
return UnitTest::RunAllTests();
}

</source>
And add '''../UnitTest++/src''' to the compiler search directories on the project level of our LeapYear project.
And add '''../UnitTest++/Deliv/Release/libUnitTest++.a''' to the link libraries of the project

Why : well we need to link with the framework and we need to include the UnitTest++ header so we can use it's functionalities.

The line '''UnitTest::RunAllTests()''' will make sure all test encountered in our sources will be carried out.
We don't have any tests yet, nor any functionality, but go ahead build the project and run it.
This is the output :

Success: 0 tests passed
Test time: 0.00 seconds.

Great : success, but no tests yet. Well it's a start.
Time to move forward, and write our first test.

== LeapYear-Step2 ==
Test, test, but there's nothing to test. Yes, absolutely. Let's think of a test, a test that will help us in the design. Now that's a good idea. Suppose I would be the user of the uplifting problem solving leap year checking library/component ... hmmm modesty first : leap year checking '''function'''.
How would I like that function to look.
<source lang="cpp">
bool IsLeapYear(int Year);
</source>
Yes that seems acceptable.
So let's write a test that will call that method.
We do that by adding the following code to LeapYearTest.cpp

<source lang="cpp">
#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

}

</source>
Things to note :
* we include the unit test header
* it is good to put the tests in nameless namespace (will be explained later on)
* we use the TEST macro, the argument is the name of the test : OurFirstTest
* we use CHECK_EQUAL to check if the expected result (the first argument) matches the computed result (the second argument)

Time to build. Woooooops errors. The tests fails completely, it does not even build. Time to add the code needed.
In order to compiler the test file, we need to include the LeapYear.h header and have that header export our function.
Our LeapYear header will look like this now (don't forget the include in the test file, it is not shown here) :

<source lang="cpp">
#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

bool IsLeapYear(int Year);

#endif // LEAPYEAR_H_INCLUDED

</source>

At least now it compiles, but it doesn't link yet. Duh, that because we don't have an implementation yet.
Time to provide the bare minimum of code to make the test pass.
So we change the LeapYear.cpp into :

<source lang="cpp">
#include "LeapYear.h"

bool IsLeapYear(int /*Year*/)
{
return true;
}

</source>
Build it, run it. Yes, we have one test passed.
Great. Let's move on.

== LeapYear-Step3 ==
Anyone having the feeling we are cheating. Well the user does not know how we wrote our code on the inside. So just to be sure the user (we) adds the following test, ending up in :

<source lang="cpp">
#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

TEST(OurSecondTest)
{
const bool Result = IsLeapYear(1973);
CHECK_EQUAL(false, Result);
}

}

</source>
Building is already no issue any more, we can run it. Oh boy, a test is failing.
The framework tell us something like this :
<filename>:<Line>: error: Failure in OurSecondTest: Expected 0 but was 1
FAILURE: 1 out of 2 tests failed (1 failures)
Test time: 0.00 seconds.

So we are informed of the line where the failing tests occurs, next to that it tells us what it was expecting and what the actual outcome was. And it presents a resume of the total number of tests, and how many that failed. For you scripting hackers note that FAILURE != SUCCESS.

It seems we should do some more effort and implement some real logic.

== LeapYear-Step4 ==
Let's keep it taking one step at a time. Let's start by implementing the 'divisible by 4' logic. That will already solve our tests.
So our LeapYear.cpp will now look like this :

<source lang="cpp">
#include "LeapYear.h"

namespace
{

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year);
}

</source>
Build, run. All tests pass. Life is great.

But those changing requirements, always the change of the requirements. Years that can be divided by 100 should not be considered as a leap year.

Time for our next step.

== LeapYear-Step5 ==
We add a new test for checking for example the year 1900.

<source lang="cpp">
TEST(DivisableBy100)
{
const bool Result = IsLeapYear(1900);
CHECK_EQUAL(false, Result);
}
</source>

Build and run the tests. It will fail. So time to add the minimum code needed to make this test pass.
This will change our LeapYear.cpp into :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year) && !IsDivisableBy100(Year);
}

</source>

Build and run the tests, yes : success. All 3 tests pass.

It seems life might be great again ...

Wrong, someone just added the following test :

<source lang="cpp">
TEST(DivisableBy400)
{
const bool Result = IsLeapYear(2000);
CHECK_EQUAL(true, Result);
}
</source>

And we once again have a failing test.

Time for the next step.

== LeapYear-Step6 ==
We should add logic to deal with years that can be divided by 400, since those are leap years.
We change our LeapYear.cpp into this :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy400(int Year)
{
return (Year%400) == 0;
}

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
const bool LeapYear = IsDivisableBy400(Year) ||
(IsDivisableBy4(Year) && !IsDivisableBy100(Year));
return LeapYear;
}

</source>

And once again everything works OK.
And it seems all the logical rules have been implemented.
This one is ready for shipping, and till the end of time we have our tests that can be run whenever we want (more on this later, we'd prefer this to be done automatically) to ensure we never break anything.

UnitTesting

2009-09-09T11:04:22Z

Killerbot: /* LeapYear-Step5 */

This document is under development by killerbot. Starting from 7 September 2009.

== Introduction ==
This document will describe how unit testing can be combined with the Code::Blocks IDE. It will give a hands-on example on a unit testing framework and how it can be used with Code::Blocks.

== What is Unit Testing ==
Simply put Unit Testing is the discipline and best practice of writing and running little test programs that test little units of code.
Such a unit can be :
* a class
* a free function
* an interface
* ...
There are several unit test frameworks available to help you write, deploy, manage your unit tests. The most famous family is the xUnit framework, and some of it's descendants.

== Why Unit Testing ==
Well we write code that implements some functionality. We need a way to check and prove that the implementation is correct. Therefor we need tests. We need tests on the application level, at the integration level of different components, classes, interfaces. But we also need tests for the smallest building blocks, the units.
We also wans these tests to run very quickly. That we we can run the tests often, manually or automated.
These tests will also be our safeguards during refactoring of the code, extending the code or whatever maintenance tasks we carry out on the code.
These tests will also make us think of how our class, method, ... will be used. Since the test can be seen as a user of our code. Thanks do this, thinking about the tests before implementing the functionality can help us in the design : emergent design.
It will help us to avoid creating big classes, complex functions. We will only write the methods that are really needed, and no methods that we think might (n)ever be useful in the future. We are no good future tellers ! Those 'might be needed' methods and their tests are just a waste of time. Extending, refactoring will be done when it is actually needed, and at that time we have our unit tests to ensure we don't break any existing code.

Other times to add new unit tests are typically when a bug is discovered; Write a unit test to reproduces the bug, fix the code, and from now on the new unit test will watch your back so the bug won't reappear.

Unit test are also a good place of documentation. The little tests show how the class or method is used.
The code documents itself.

So the benefits are :
* better design
* prove of your code
* safe guard during code maintenance (refactoring, extensions)
* documentation
* ...

== Unit Test frameworks ==
When writing unit tests, one will create a lot of similar code. Since unit tests are nothing more then little programs, several tasks will be repeated, setting up the test environment, create your class, call a method, verify it's result, write out an error message when the test fails, preferably specifying what the wrong outcome was, and what the expected result is.
All these repetitive chores are taken care of by the frame work so the developer can focus on the real code of the test.
This document will use a small but very effective framework for the C++ language. It is called UnitTest++. It's homepage is at : [http://unittest-cpp.sourceforge.net/ UnitTest++].
You can download it directly at this [http://sourceforge.net/projects/unittest-cpp/files/UnitTest%2B%2B/1.4/unittest-cpp-1.4.zip/download link]. At the time of writing the latest version is 1.4.

== Setup our environment ==
Let's create a directory on our PC in which we will cary out our experiments. I will refer to this directory from now on as <TestPit>. For my laptop on which I am writing this article, that will be /home/lieven/Projects/UnitTestArticle. Note that everything we will do, works on linux and on windows!
Download the "unittest-cpp-1.4.zip" file from the link specified above. Extract it in the <TestPit> directory. All the files will end up in the <TestPit>/UnitTest++ directory.

== Build UnitTest++ ==
After the extracted the zip archive we have a directory structure like this :
<TestPit>/UnitTest++
|
+docs
|
+src

The files in the UnitTest++ directory are of little use for us, since they bring project files for some bizarre Microsoft IDE ;-) .
We will create our own Code::Blocks project to build the UnitTest++ framework.

Why do we need to build something ? Well as said, the framework will do a lot of chores for us, those chores are implemented by code, that code is framework. We will build to frame work into a static library, and for every unit test (or set of unit tests) we create a little (console/shell) program with the test code we wrote, which will link with the static library to obtain a unit test executable, driven by the framework.

We will put our Code::Blocks project file in a nice structured directory tree, therefor let's create a 'Project' subdirectory in the <TestPit>/UniTest++ directory.

In there create a new file with the name "UnitTest++.cbp".
Give that file the following content :

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="UnitTest++" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option platforms="Windows;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option platforms="Windows;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
<Target title="Debug(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<VirtualTargets>
<Add alias="All" targets="Debug;Release;Debug(linux);Release(linux);" />
</VirtualTargets>
<Unit filename="../src/AssertException.cpp" />
<Unit filename="../src/AssertException.h" />
<Unit filename="../src/CheckMacros.h" />
<Unit filename="../src/Checks.cpp" />
<Unit filename="../src/Checks.h" />
<Unit filename="../src/Config.h" />
<Unit filename="../src/CurrentTest.cpp" />
<Unit filename="../src/CurrentTest.h" />
<Unit filename="../src/DeferredTestReporter.cpp" />
<Unit filename="../src/DeferredTestReporter.h" />
<Unit filename="../src/DeferredTestResult.cpp" />
<Unit filename="../src/DeferredTestResult.h" />
<Unit filename="../src/ExecuteTest.h" />
<Unit filename="../src/MemoryOutStream.cpp" />
<Unit filename="../src/MemoryOutStream.h" />
<Unit filename="../src/Posix/SignalTranslator.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/SignalTranslator.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/ReportAssert.cpp" />
<Unit filename="../src/ReportAssert.h" />
<Unit filename="../src/Test.cpp" />
<Unit filename="../src/Test.h" />
<Unit filename="../src/TestDetails.cpp" />
<Unit filename="../src/TestDetails.h" />
<Unit filename="../src/TestList.cpp" />
<Unit filename="../src/TestList.h" />
<Unit filename="../src/TestMacros.h" />
<Unit filename="../src/TestReporter.cpp" />
<Unit filename="../src/TestReporter.h" />
<Unit filename="../src/TestReporterStdout.cpp" />
<Unit filename="../src/TestReporterStdout.h" />
<Unit filename="../src/TestResults.cpp" />
<Unit filename="../src/TestResults.h" />
<Unit filename="../src/TestRunner.cpp" />
<Unit filename="../src/TestRunner.h" />
<Unit filename="../src/TestSuite.h" />
<Unit filename="../src/TimeConstraint.cpp" />
<Unit filename="../src/TimeConstraint.h" />
<Unit filename="../src/TimeHelpers.h" />
<Unit filename="../src/UnitTest++.h" />
<Unit filename="../src/Win32/TimeHelpers.cpp">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/Win32/TimeHelpers.h">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/XmlTestReporter.cpp" />
<Unit filename="../src/XmlTestReporter.h" />
<Extensions>
<envvars />
<code_completion />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

Some things to note about the content of the project file, the power of Code::Blocks.
* there are 4 targets : Debug/Release for Windows and Debug/Release for linux [yes : 1 project file that allows building on linux and on windows]
* some files are only part of the linux targets, some only for the windows targets

But before we build, let's modify some source files (not really needed, but I prefer to have warning free compilations). These are the changes I carried out :
* ReportAssert.cpp : #include "ReportAssert.h"
* win32/TimeHelpers.cpp : first the m_threadHandle and then the m_startTime in the initializerlist

Next open up this project file in Code::Blocks and build the debug and release target. From now one we will only use the Release target, we go for speed ;-)

The result of the build process will show up in subdirectories of the new 'Deliv' subdirectory of <testPit>/UnitTest++ : '''<testPit>/UnitTest++/Deliv/Release/libUnitTest++.a'''

Alright, we have build the unit test framework in a platform independent way, no silly makefiles, no obscure M$ IDE, good old super Code::Blocks. It is time to write some code so we have something to unit test.

In the first example we will create a simple free function that checks if a a give year is a leap your or not.

The business logic is as follows : a year is a leap year when it can be divided by 4, unless itcan be divided by 100. But in case it can be divided by 400, then again it is a leap year.

In the next section we will first setup a Code::Blocks project containing both the 'functionality files, and the unit test files. Typically one will package several functionality files into a static library and create a unit test project that tests all the class/functionalities in that library package, also called a component. That is we have a component (whose deliverable is the static library, and we have a unit test project that tests the entire component).

== Our first test project environment ==
Let's create a new directory in our <TestPit> : <TestPit>/LeapYear.
For the simplicity we will put the project file and the source file all together in this directory. Normally we would work in a more structured way, but in a demo article we have some artistic freedom ;-)
Next you can create with the Code::Block's wizard a new console project in the LeapYear directory. Or you can create the following 5 files and give the the contents as specified below. Note that this demo works on linux and on windows, everything is still completely platform independent. Long Live Code::Blocks.

The project file : LeapYear.cbp (the one below already contains the 5 source files, in case you use the wizard you have to add the LeapYear.h/cpp and LeapYearTest.cpp files to the project)

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="LeapYear" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option output="Deliv/Debug/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Debug/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option output="Deliv/Release/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Release/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-O2" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<Compiler>
<Add option="-Wall" />
<Add option="-fexceptions" />
</Compiler>
<Unit filename="LeapYear.cpp" />
<Unit filename="LeapYear.h" />
<Unit filename="LeapYearTest.cpp" />
<Unit filename="main.cpp" />
<Extensions>
<envvars />
<code_completion />
<lib_finder disable_auto="1" />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

The main source file : main.cpp
int main()
{
return 0;
}

The header exporting our powerful function : LeapYear.h

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

#endif // LEAPYEAR_H_INCLUDED

And the implementation of the leap year logic : LeapYear.cpp

#include "LeapYear.h"

And finishing with the source file for the tests : LeapYearTest.cpp (currently) empty

We can already build the project, we have a nice little program that does .... nothing.

Time to move to the next section, a little word about Test Driven Development.

== Test Driven Development ==
This is a practice where new code is only added to make a failing test pass. And one only adds the code needed to make that test pass. Once that is done, a new test is added to will check the next functionality to add.
On this really simple example we will more or less practice some TDD.

So get ready, it's time for LeapYear-Step1.

== LeapYear-Step1 ==
We will turn our main.cpp into the guy in charge to carry out the tests, all we need to do is change the contents of main.cpp into this :

<source lang="cpp">
#include "UnitTest++.h"

int main()
{
return UnitTest::RunAllTests();
}

</source>
And add '''../UnitTest++/src''' to the compiler search directories on the project level of our LeapYear project.
And add '''../UnitTest++/Deliv/Release/libUnitTest++.a''' to the link libraries of the project

Why : well we need to link with the framework and we need to include the UnitTest++ header so we can use it's functionalities.

The line '''UnitTest::RunAllTests()''' will make sure all test encountered in our sources will be carried out.
We don't have any tests yet, nor any functionality, but go ahead build the project and run it.
This is the output :

Success: 0 tests passed
Test time: 0.00 seconds.

Great : success, but no tests yet. Well it's a start.
Time to move forward, and write our first test.

== LeapYear-Step2 ==
Test, test, but there's nothing to test. Yes, absolutely. Let's think of a test, a test that will help us in the design. Now that's a good idea. Suppose I would be the user of the uplifting problem solving leap year checking library/component ... hmmm modesty first : leap year checking '''function'''.
How would I like that function to look.
<source lang="cpp">
bool IsLeapYear(int Year);
</source>
Yes that seems acceptable.
So let's write a test that will call that method.
We do that by adding the following code to LeapYearTest.cpp

<source lang="cpp">
#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

}

</source>
Things to note :
* we include the unit test header
* it is good to put the tests in nameless namespace (will be explained later on)
* we use the TEST macro, the argument is the name of the test : OurFirstTest
* we use CHECK_EQUAL to check if the expected result (the first argument) matches the computed result (the second argument)

Time to build. Woooooops errors. The tests fails completely, it does not even build. Time to add the code needed.
In order to compiler the test file, we need to include the LeapYear.h header and have that header export our function.
Our LeapYear header will look like this now (don't forget the include in the test file, it is not shown here) :

<source lang="cpp">
#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

bool IsLeapYear(int Year);

#endif // LEAPYEAR_H_INCLUDED

</source>

At least now it compiles, but it doesn't link yet. Duh, that because we don't have an implementation yet.
Time to provide the bare minimum of code to make the test pass.
So we change the LeapYear.cpp into :

<source lang="cpp">
#include "LeapYear.h"

bool IsLeapYear(int /*Year*/)
{
return true;
}

</source>
Build it, run it. Yes, we have one test passed.
Great. Let's move on.

== LeapYear-Step3 ==
Anyone having the feeling we are cheating. Well the user does not know how we wrote our code on the inside. So just to be sure the user (we) adds the following test, ending up in :

<source lang="cpp">
#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

TEST(OurSecondTest)
{
const bool Result = IsLeapYear(1973);
CHECK_EQUAL(false, Result);
}

}

</source>
Building is already no issue any more, we can run it. Oh boy, a test is failing.
The framework tell us something like this :
<filename>:<Line>: error: Failure in OurSecondTest: Expected 0 but was 1
FAILURE: 1 out of 2 tests failed (1 failures)
Test time: 0.00 seconds.

So we are informed of the line where the failing tests occurs, next to that it tells us what it was expecting and what the actual outcome was. And it presents a resume of the total number of tests, and how many that failed. For you scripting hackers note that FAILURE != SUCCESS.

It seems we should do some more effort and implement some real logic.

== LeapYear-Step4 ==
Let's keep it taking one step at a time. Let's start by implementing the 'divisible by 4' logic. That will already solve our tests.
So our LeapYear.cpp will now look like this :

<source lang="cpp">
#include "LeapYear.h"

namespace
{

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year);
}

}

</source>
Build, run. All tests pass. Life is great.

But those changing requirements, always the change of the requirements. Years that can be divided by 100 should not be considered as a leap year.

Time for our next step.

== LeapYear-Step5 ==
We add a new test for checking for example the year 1900.

<source lang="cpp">
TEST(DivisableBy100)
{
const bool Result = IsLeapYear(1900);
CHECK_EQUAL(false, Result);
}
</source>

Build and run the tests. It will fail. So time to add the minimum code needed to make this test pass.
This will change our LeapYear.cpp into :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year) && !IsDivisableBy100(Year);
}

</source>

Build and run the tests, yes : success. All 3 tests pass.

It seems life might be great again ...

Wrong, someone just added the following test :

<source lang="cpp">
TEST(DivisableBy400)
{
const bool Result = IsLeapYear(2000);
CHECK_EQUAL(true, Result);
}
</source>

And we once again have a failing test.

Time for the next step.

== LeapYear-Step6 ==
We should add logic to deal with years that can be divided by 400, since those are leap years.
We change our LeapYear.cpp into this :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy400(int Year)
{
return (Year%400) == 0;
}

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
const bool LeapYear = IsDivisableBy400(Year) ||
(IsDivisableBy4(Year) && !IsDivisableBy100(Year));
return LeapYear;
}

</source>

And once again everything works OK.
And it seems all the logical rules have been implemented.
This one is ready for shipping, and till the end of time we have our tests that can be run whenever we want (more on this later, we'd prefer this to be done automatically) to ensure we never break anything.

UnitTesting

2009-09-09T11:03:53Z

Killerbot: /* LeapYear-Step5 */

This document is under development by killerbot. Starting from 7 September 2009.

== Introduction ==
This document will describe how unit testing can be combined with the Code::Blocks IDE. It will give a hands-on example on a unit testing framework and how it can be used with Code::Blocks.

== What is Unit Testing ==
Simply put Unit Testing is the discipline and best practice of writing and running little test programs that test little units of code.
Such a unit can be :
* a class
* a free function
* an interface
* ...
There are several unit test frameworks available to help you write, deploy, manage your unit tests. The most famous family is the xUnit framework, and some of it's descendants.

== Why Unit Testing ==
Well we write code that implements some functionality. We need a way to check and prove that the implementation is correct. Therefor we need tests. We need tests on the application level, at the integration level of different components, classes, interfaces. But we also need tests for the smallest building blocks, the units.
We also wans these tests to run very quickly. That we we can run the tests often, manually or automated.
These tests will also be our safeguards during refactoring of the code, extending the code or whatever maintenance tasks we carry out on the code.
These tests will also make us think of how our class, method, ... will be used. Since the test can be seen as a user of our code. Thanks do this, thinking about the tests before implementing the functionality can help us in the design : emergent design.
It will help us to avoid creating big classes, complex functions. We will only write the methods that are really needed, and no methods that we think might (n)ever be useful in the future. We are no good future tellers ! Those 'might be needed' methods and their tests are just a waste of time. Extending, refactoring will be done when it is actually needed, and at that time we have our unit tests to ensure we don't break any existing code.

Other times to add new unit tests are typically when a bug is discovered; Write a unit test to reproduces the bug, fix the code, and from now on the new unit test will watch your back so the bug won't reappear.

Unit test are also a good place of documentation. The little tests show how the class or method is used.
The code documents itself.

So the benefits are :
* better design
* prove of your code
* safe guard during code maintenance (refactoring, extensions)
* documentation
* ...

== Unit Test frameworks ==
When writing unit tests, one will create a lot of similar code. Since unit tests are nothing more then little programs, several tasks will be repeated, setting up the test environment, create your class, call a method, verify it's result, write out an error message when the test fails, preferably specifying what the wrong outcome was, and what the expected result is.
All these repetitive chores are taken care of by the frame work so the developer can focus on the real code of the test.
This document will use a small but very effective framework for the C++ language. It is called UnitTest++. It's homepage is at : [http://unittest-cpp.sourceforge.net/ UnitTest++].
You can download it directly at this [http://sourceforge.net/projects/unittest-cpp/files/UnitTest%2B%2B/1.4/unittest-cpp-1.4.zip/download link]. At the time of writing the latest version is 1.4.

== Setup our environment ==
Let's create a directory on our PC in which we will cary out our experiments. I will refer to this directory from now on as <TestPit>. For my laptop on which I am writing this article, that will be /home/lieven/Projects/UnitTestArticle. Note that everything we will do, works on linux and on windows!
Download the "unittest-cpp-1.4.zip" file from the link specified above. Extract it in the <TestPit> directory. All the files will end up in the <TestPit>/UnitTest++ directory.

== Build UnitTest++ ==
After the extracted the zip archive we have a directory structure like this :
<TestPit>/UnitTest++
|
+docs
|
+src

The files in the UnitTest++ directory are of little use for us, since they bring project files for some bizarre Microsoft IDE ;-) .
We will create our own Code::Blocks project to build the UnitTest++ framework.

Why do we need to build something ? Well as said, the framework will do a lot of chores for us, those chores are implemented by code, that code is framework. We will build to frame work into a static library, and for every unit test (or set of unit tests) we create a little (console/shell) program with the test code we wrote, which will link with the static library to obtain a unit test executable, driven by the framework.

We will put our Code::Blocks project file in a nice structured directory tree, therefor let's create a 'Project' subdirectory in the <TestPit>/UniTest++ directory.

In there create a new file with the name "UnitTest++.cbp".
Give that file the following content :

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="UnitTest++" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option platforms="Windows;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option platforms="Windows;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
<Target title="Debug(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<VirtualTargets>
<Add alias="All" targets="Debug;Release;Debug(linux);Release(linux);" />
</VirtualTargets>
<Unit filename="../src/AssertException.cpp" />
<Unit filename="../src/AssertException.h" />
<Unit filename="../src/CheckMacros.h" />
<Unit filename="../src/Checks.cpp" />
<Unit filename="../src/Checks.h" />
<Unit filename="../src/Config.h" />
<Unit filename="../src/CurrentTest.cpp" />
<Unit filename="../src/CurrentTest.h" />
<Unit filename="../src/DeferredTestReporter.cpp" />
<Unit filename="../src/DeferredTestReporter.h" />
<Unit filename="../src/DeferredTestResult.cpp" />
<Unit filename="../src/DeferredTestResult.h" />
<Unit filename="../src/ExecuteTest.h" />
<Unit filename="../src/MemoryOutStream.cpp" />
<Unit filename="../src/MemoryOutStream.h" />
<Unit filename="../src/Posix/SignalTranslator.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/SignalTranslator.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/ReportAssert.cpp" />
<Unit filename="../src/ReportAssert.h" />
<Unit filename="../src/Test.cpp" />
<Unit filename="../src/Test.h" />
<Unit filename="../src/TestDetails.cpp" />
<Unit filename="../src/TestDetails.h" />
<Unit filename="../src/TestList.cpp" />
<Unit filename="../src/TestList.h" />
<Unit filename="../src/TestMacros.h" />
<Unit filename="../src/TestReporter.cpp" />
<Unit filename="../src/TestReporter.h" />
<Unit filename="../src/TestReporterStdout.cpp" />
<Unit filename="../src/TestReporterStdout.h" />
<Unit filename="../src/TestResults.cpp" />
<Unit filename="../src/TestResults.h" />
<Unit filename="../src/TestRunner.cpp" />
<Unit filename="../src/TestRunner.h" />
<Unit filename="../src/TestSuite.h" />
<Unit filename="../src/TimeConstraint.cpp" />
<Unit filename="../src/TimeConstraint.h" />
<Unit filename="../src/TimeHelpers.h" />
<Unit filename="../src/UnitTest++.h" />
<Unit filename="../src/Win32/TimeHelpers.cpp">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/Win32/TimeHelpers.h">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/XmlTestReporter.cpp" />
<Unit filename="../src/XmlTestReporter.h" />
<Extensions>
<envvars />
<code_completion />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

Some things to note about the content of the project file, the power of Code::Blocks.
* there are 4 targets : Debug/Release for Windows and Debug/Release for linux [yes : 1 project file that allows building on linux and on windows]
* some files are only part of the linux targets, some only for the windows targets

But before we build, let's modify some source files (not really needed, but I prefer to have warning free compilations). These are the changes I carried out :
* ReportAssert.cpp : #include "ReportAssert.h"
* win32/TimeHelpers.cpp : first the m_threadHandle and then the m_startTime in the initializerlist

Next open up this project file in Code::Blocks and build the debug and release target. From now one we will only use the Release target, we go for speed ;-)

The result of the build process will show up in subdirectories of the new 'Deliv' subdirectory of <testPit>/UnitTest++ : '''<testPit>/UnitTest++/Deliv/Release/libUnitTest++.a'''

Alright, we have build the unit test framework in a platform independent way, no silly makefiles, no obscure M$ IDE, good old super Code::Blocks. It is time to write some code so we have something to unit test.

In the first example we will create a simple free function that checks if a a give year is a leap your or not.

The business logic is as follows : a year is a leap year when it can be divided by 4, unless itcan be divided by 100. But in case it can be divided by 400, then again it is a leap year.

In the next section we will first setup a Code::Blocks project containing both the 'functionality files, and the unit test files. Typically one will package several functionality files into a static library and create a unit test project that tests all the class/functionalities in that library package, also called a component. That is we have a component (whose deliverable is the static library, and we have a unit test project that tests the entire component).

== Our first test project environment ==
Let's create a new directory in our <TestPit> : <TestPit>/LeapYear.
For the simplicity we will put the project file and the source file all together in this directory. Normally we would work in a more structured way, but in a demo article we have some artistic freedom ;-)
Next you can create with the Code::Block's wizard a new console project in the LeapYear directory. Or you can create the following 5 files and give the the contents as specified below. Note that this demo works on linux and on windows, everything is still completely platform independent. Long Live Code::Blocks.

The project file : LeapYear.cbp (the one below already contains the 5 source files, in case you use the wizard you have to add the LeapYear.h/cpp and LeapYearTest.cpp files to the project)

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="LeapYear" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option output="Deliv/Debug/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Debug/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option output="Deliv/Release/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Release/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-O2" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<Compiler>
<Add option="-Wall" />
<Add option="-fexceptions" />
</Compiler>
<Unit filename="LeapYear.cpp" />
<Unit filename="LeapYear.h" />
<Unit filename="LeapYearTest.cpp" />
<Unit filename="main.cpp" />
<Extensions>
<envvars />
<code_completion />
<lib_finder disable_auto="1" />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

The main source file : main.cpp
int main()
{
return 0;
}

The header exporting our powerful function : LeapYear.h

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

#endif // LEAPYEAR_H_INCLUDED

And the implementation of the leap year logic : LeapYear.cpp

#include "LeapYear.h"

And finishing with the source file for the tests : LeapYearTest.cpp (currently) empty

We can already build the project, we have a nice little program that does .... nothing.

Time to move to the next section, a little word about Test Driven Development.

== Test Driven Development ==
This is a practice where new code is only added to make a failing test pass. And one only adds the code needed to make that test pass. Once that is done, a new test is added to will check the next functionality to add.
On this really simple example we will more or less practice some TDD.

So get ready, it's time for LeapYear-Step1.

== LeapYear-Step1 ==
We will turn our main.cpp into the guy in charge to carry out the tests, all we need to do is change the contents of main.cpp into this :

<source lang="cpp">
#include "UnitTest++.h"

int main()
{
return UnitTest::RunAllTests();
}

</source>
And add '''../UnitTest++/src''' to the compiler search directories on the project level of our LeapYear project.
And add '''../UnitTest++/Deliv/Release/libUnitTest++.a''' to the link libraries of the project

Why : well we need to link with the framework and we need to include the UnitTest++ header so we can use it's functionalities.

The line '''UnitTest::RunAllTests()''' will make sure all test encountered in our sources will be carried out.
We don't have any tests yet, nor any functionality, but go ahead build the project and run it.
This is the output :

Success: 0 tests passed
Test time: 0.00 seconds.

Great : success, but no tests yet. Well it's a start.
Time to move forward, and write our first test.

== LeapYear-Step2 ==
Test, test, but there's nothing to test. Yes, absolutely. Let's think of a test, a test that will help us in the design. Now that's a good idea. Suppose I would be the user of the uplifting problem solving leap year checking library/component ... hmmm modesty first : leap year checking '''function'''.
How would I like that function to look.
<source lang="cpp">
bool IsLeapYear(int Year);
</source>
Yes that seems acceptable.
So let's write a test that will call that method.
We do that by adding the following code to LeapYearTest.cpp

<source lang="cpp">
#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

}

</source>
Things to note :
* we include the unit test header
* it is good to put the tests in nameless namespace (will be explained later on)
* we use the TEST macro, the argument is the name of the test : OurFirstTest
* we use CHECK_EQUAL to check if the expected result (the first argument) matches the computed result (the second argument)

Time to build. Woooooops errors. The tests fails completely, it does not even build. Time to add the code needed.
In order to compiler the test file, we need to include the LeapYear.h header and have that header export our function.
Our LeapYear header will look like this now (don't forget the include in the test file, it is not shown here) :

<source lang="cpp">
#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

bool IsLeapYear(int Year);

#endif // LEAPYEAR_H_INCLUDED

</source>

At least now it compiles, but it doesn't link yet. Duh, that because we don't have an implementation yet.
Time to provide the bare minimum of code to make the test pass.
So we change the LeapYear.cpp into :

<source lang="cpp">
#include "LeapYear.h"

bool IsLeapYear(int /*Year*/)
{
return true;
}

</source>
Build it, run it. Yes, we have one test passed.
Great. Let's move on.

== LeapYear-Step3 ==
Anyone having the feeling we are cheating. Well the user does not know how we wrote our code on the inside. So just to be sure the user (we) adds the following test, ending up in :

<source lang="cpp">
#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

TEST(OurSecondTest)
{
const bool Result = IsLeapYear(1973);
CHECK_EQUAL(false, Result);
}

}

</source>
Building is already no issue any more, we can run it. Oh boy, a test is failing.
The framework tell us something like this :
<filename>:<Line>: error: Failure in OurSecondTest: Expected 0 but was 1
FAILURE: 1 out of 2 tests failed (1 failures)
Test time: 0.00 seconds.

So we are informed of the line where the failing tests occurs, next to that it tells us what it was expecting and what the actual outcome was. And it presents a resume of the total number of tests, and how many that failed. For you scripting hackers note that FAILURE != SUCCESS.

It seems we should do some more effort and implement some real logic.

== LeapYear-Step4 ==
Let's keep it taking one step at a time. Let's start by implementing the 'divisible by 4' logic. That will already solve our tests.
So our LeapYear.cpp will now look like this :

<source lang="cpp">
#include "LeapYear.h"

namespace
{

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year);
}

}

</source>
Build, run. All tests pass. Life is great.

But those changing requirements, always the change of the requirements. Years that can be divided by 100 should not be considered as a leap year.

Time for our next step.

== LeapYear-Step5 ==
We add a new test for checking for example the year 1900.

<source lang="cpp">
TEST(DivisableBy100)
{
const bool Result = IsLeapYear(1900);
CHECK_EQUAL(false, Result);
}
</source>

Build and run the tests. It will fail. So time to add the minimum code needed to make this test pass.
This will change our LeapYear.cpp into :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year) && !IsDivisableBy100(Year);
}

}
</source>

Build and run the tests, yes : success. All 3 tests pass.

It seems life might be great again ...

Wrong, someone just added the following test :

<source lang="cpp">
TEST(DivisableBy400)
{
const bool Result = IsLeapYear(2000);
CHECK_EQUAL(true, Result);
}
</source>

And we once again have a failing test.

Time for the next step.

== LeapYear-Step6 ==
We should add logic to deal with years that can be divided by 400, since those are leap years.
We change our LeapYear.cpp into this :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy400(int Year)
{
return (Year%400) == 0;
}

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
const bool LeapYear = IsDivisableBy400(Year) ||
(IsDivisableBy4(Year) && !IsDivisableBy100(Year));
return LeapYear;
}

</source>

And once again everything works OK.
And it seems all the logical rules have been implemented.
This one is ready for shipping, and till the end of time we have our tests that can be run whenever we want (more on this later, we'd prefer this to be done automatically) to ensure we never break anything.

UnitTesting

2009-09-09T11:02:44Z

Killerbot: /* LeapYear-Step4 */

This document is under development by killerbot. Starting from 7 September 2009.

== Introduction ==
This document will describe how unit testing can be combined with the Code::Blocks IDE. It will give a hands-on example on a unit testing framework and how it can be used with Code::Blocks.

== What is Unit Testing ==
Simply put Unit Testing is the discipline and best practice of writing and running little test programs that test little units of code.
Such a unit can be :
* a class
* a free function
* an interface
* ...
There are several unit test frameworks available to help you write, deploy, manage your unit tests. The most famous family is the xUnit framework, and some of it's descendants.

== Why Unit Testing ==
Well we write code that implements some functionality. We need a way to check and prove that the implementation is correct. Therefor we need tests. We need tests on the application level, at the integration level of different components, classes, interfaces. But we also need tests for the smallest building blocks, the units.
We also wans these tests to run very quickly. That we we can run the tests often, manually or automated.
These tests will also be our safeguards during refactoring of the code, extending the code or whatever maintenance tasks we carry out on the code.
These tests will also make us think of how our class, method, ... will be used. Since the test can be seen as a user of our code. Thanks do this, thinking about the tests before implementing the functionality can help us in the design : emergent design.
It will help us to avoid creating big classes, complex functions. We will only write the methods that are really needed, and no methods that we think might (n)ever be useful in the future. We are no good future tellers ! Those 'might be needed' methods and their tests are just a waste of time. Extending, refactoring will be done when it is actually needed, and at that time we have our unit tests to ensure we don't break any existing code.

Other times to add new unit tests are typically when a bug is discovered; Write a unit test to reproduces the bug, fix the code, and from now on the new unit test will watch your back so the bug won't reappear.

Unit test are also a good place of documentation. The little tests show how the class or method is used.
The code documents itself.

So the benefits are :
* better design
* prove of your code
* safe guard during code maintenance (refactoring, extensions)
* documentation
* ...

== Unit Test frameworks ==
When writing unit tests, one will create a lot of similar code. Since unit tests are nothing more then little programs, several tasks will be repeated, setting up the test environment, create your class, call a method, verify it's result, write out an error message when the test fails, preferably specifying what the wrong outcome was, and what the expected result is.
All these repetitive chores are taken care of by the frame work so the developer can focus on the real code of the test.
This document will use a small but very effective framework for the C++ language. It is called UnitTest++. It's homepage is at : [http://unittest-cpp.sourceforge.net/ UnitTest++].
You can download it directly at this [http://sourceforge.net/projects/unittest-cpp/files/UnitTest%2B%2B/1.4/unittest-cpp-1.4.zip/download link]. At the time of writing the latest version is 1.4.

== Setup our environment ==
Let's create a directory on our PC in which we will cary out our experiments. I will refer to this directory from now on as <TestPit>. For my laptop on which I am writing this article, that will be /home/lieven/Projects/UnitTestArticle. Note that everything we will do, works on linux and on windows!
Download the "unittest-cpp-1.4.zip" file from the link specified above. Extract it in the <TestPit> directory. All the files will end up in the <TestPit>/UnitTest++ directory.

== Build UnitTest++ ==
After the extracted the zip archive we have a directory structure like this :
<TestPit>/UnitTest++
|
+docs
|
+src

The files in the UnitTest++ directory are of little use for us, since they bring project files for some bizarre Microsoft IDE ;-) .
We will create our own Code::Blocks project to build the UnitTest++ framework.

Why do we need to build something ? Well as said, the framework will do a lot of chores for us, those chores are implemented by code, that code is framework. We will build to frame work into a static library, and for every unit test (or set of unit tests) we create a little (console/shell) program with the test code we wrote, which will link with the static library to obtain a unit test executable, driven by the framework.

We will put our Code::Blocks project file in a nice structured directory tree, therefor let's create a 'Project' subdirectory in the <TestPit>/UniTest++ directory.

In there create a new file with the name "UnitTest++.cbp".
Give that file the following content :

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="UnitTest++" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option platforms="Windows;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option platforms="Windows;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
<Target title="Debug(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<VirtualTargets>
<Add alias="All" targets="Debug;Release;Debug(linux);Release(linux);" />
</VirtualTargets>
<Unit filename="../src/AssertException.cpp" />
<Unit filename="../src/AssertException.h" />
<Unit filename="../src/CheckMacros.h" />
<Unit filename="../src/Checks.cpp" />
<Unit filename="../src/Checks.h" />
<Unit filename="../src/Config.h" />
<Unit filename="../src/CurrentTest.cpp" />
<Unit filename="../src/CurrentTest.h" />
<Unit filename="../src/DeferredTestReporter.cpp" />
<Unit filename="../src/DeferredTestReporter.h" />
<Unit filename="../src/DeferredTestResult.cpp" />
<Unit filename="../src/DeferredTestResult.h" />
<Unit filename="../src/ExecuteTest.h" />
<Unit filename="../src/MemoryOutStream.cpp" />
<Unit filename="../src/MemoryOutStream.h" />
<Unit filename="../src/Posix/SignalTranslator.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/SignalTranslator.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/ReportAssert.cpp" />
<Unit filename="../src/ReportAssert.h" />
<Unit filename="../src/Test.cpp" />
<Unit filename="../src/Test.h" />
<Unit filename="../src/TestDetails.cpp" />
<Unit filename="../src/TestDetails.h" />
<Unit filename="../src/TestList.cpp" />
<Unit filename="../src/TestList.h" />
<Unit filename="../src/TestMacros.h" />
<Unit filename="../src/TestReporter.cpp" />
<Unit filename="../src/TestReporter.h" />
<Unit filename="../src/TestReporterStdout.cpp" />
<Unit filename="../src/TestReporterStdout.h" />
<Unit filename="../src/TestResults.cpp" />
<Unit filename="../src/TestResults.h" />
<Unit filename="../src/TestRunner.cpp" />
<Unit filename="../src/TestRunner.h" />
<Unit filename="../src/TestSuite.h" />
<Unit filename="../src/TimeConstraint.cpp" />
<Unit filename="../src/TimeConstraint.h" />
<Unit filename="../src/TimeHelpers.h" />
<Unit filename="../src/UnitTest++.h" />
<Unit filename="../src/Win32/TimeHelpers.cpp">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/Win32/TimeHelpers.h">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/XmlTestReporter.cpp" />
<Unit filename="../src/XmlTestReporter.h" />
<Extensions>
<envvars />
<code_completion />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

Some things to note about the content of the project file, the power of Code::Blocks.
* there are 4 targets : Debug/Release for Windows and Debug/Release for linux [yes : 1 project file that allows building on linux and on windows]
* some files are only part of the linux targets, some only for the windows targets

But before we build, let's modify some source files (not really needed, but I prefer to have warning free compilations). These are the changes I carried out :
* ReportAssert.cpp : #include "ReportAssert.h"
* win32/TimeHelpers.cpp : first the m_threadHandle and then the m_startTime in the initializerlist

Next open up this project file in Code::Blocks and build the debug and release target. From now one we will only use the Release target, we go for speed ;-)

The result of the build process will show up in subdirectories of the new 'Deliv' subdirectory of <testPit>/UnitTest++ : '''<testPit>/UnitTest++/Deliv/Release/libUnitTest++.a'''

Alright, we have build the unit test framework in a platform independent way, no silly makefiles, no obscure M$ IDE, good old super Code::Blocks. It is time to write some code so we have something to unit test.

In the first example we will create a simple free function that checks if a a give year is a leap your or not.

The business logic is as follows : a year is a leap year when it can be divided by 4, unless itcan be divided by 100. But in case it can be divided by 400, then again it is a leap year.

In the next section we will first setup a Code::Blocks project containing both the 'functionality files, and the unit test files. Typically one will package several functionality files into a static library and create a unit test project that tests all the class/functionalities in that library package, also called a component. That is we have a component (whose deliverable is the static library, and we have a unit test project that tests the entire component).

== Our first test project environment ==
Let's create a new directory in our <TestPit> : <TestPit>/LeapYear.
For the simplicity we will put the project file and the source file all together in this directory. Normally we would work in a more structured way, but in a demo article we have some artistic freedom ;-)
Next you can create with the Code::Block's wizard a new console project in the LeapYear directory. Or you can create the following 5 files and give the the contents as specified below. Note that this demo works on linux and on windows, everything is still completely platform independent. Long Live Code::Blocks.

The project file : LeapYear.cbp (the one below already contains the 5 source files, in case you use the wizard you have to add the LeapYear.h/cpp and LeapYearTest.cpp files to the project)

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="LeapYear" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option output="Deliv/Debug/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Debug/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option output="Deliv/Release/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Release/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-O2" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<Compiler>
<Add option="-Wall" />
<Add option="-fexceptions" />
</Compiler>
<Unit filename="LeapYear.cpp" />
<Unit filename="LeapYear.h" />
<Unit filename="LeapYearTest.cpp" />
<Unit filename="main.cpp" />
<Extensions>
<envvars />
<code_completion />
<lib_finder disable_auto="1" />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

The main source file : main.cpp
int main()
{
return 0;
}

The header exporting our powerful function : LeapYear.h

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

#endif // LEAPYEAR_H_INCLUDED

And the implementation of the leap year logic : LeapYear.cpp

#include "LeapYear.h"

And finishing with the source file for the tests : LeapYearTest.cpp (currently) empty

We can already build the project, we have a nice little program that does .... nothing.

Time to move to the next section, a little word about Test Driven Development.

== Test Driven Development ==
This is a practice where new code is only added to make a failing test pass. And one only adds the code needed to make that test pass. Once that is done, a new test is added to will check the next functionality to add.
On this really simple example we will more or less practice some TDD.

So get ready, it's time for LeapYear-Step1.

== LeapYear-Step1 ==
We will turn our main.cpp into the guy in charge to carry out the tests, all we need to do is change the contents of main.cpp into this :

<source lang="cpp">
#include "UnitTest++.h"

int main()
{
return UnitTest::RunAllTests();
}

</source>
And add '''../UnitTest++/src''' to the compiler search directories on the project level of our LeapYear project.
And add '''../UnitTest++/Deliv/Release/libUnitTest++.a''' to the link libraries of the project

Why : well we need to link with the framework and we need to include the UnitTest++ header so we can use it's functionalities.

The line '''UnitTest::RunAllTests()''' will make sure all test encountered in our sources will be carried out.
We don't have any tests yet, nor any functionality, but go ahead build the project and run it.
This is the output :

Success: 0 tests passed
Test time: 0.00 seconds.

Great : success, but no tests yet. Well it's a start.
Time to move forward, and write our first test.

== LeapYear-Step2 ==
Test, test, but there's nothing to test. Yes, absolutely. Let's think of a test, a test that will help us in the design. Now that's a good idea. Suppose I would be the user of the uplifting problem solving leap year checking library/component ... hmmm modesty first : leap year checking '''function'''.
How would I like that function to look.
<source lang="cpp">
bool IsLeapYear(int Year);
</source>
Yes that seems acceptable.
So let's write a test that will call that method.
We do that by adding the following code to LeapYearTest.cpp

<source lang="cpp">
#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

}

</source>
Things to note :
* we include the unit test header
* it is good to put the tests in nameless namespace (will be explained later on)
* we use the TEST macro, the argument is the name of the test : OurFirstTest
* we use CHECK_EQUAL to check if the expected result (the first argument) matches the computed result (the second argument)

Time to build. Woooooops errors. The tests fails completely, it does not even build. Time to add the code needed.
In order to compiler the test file, we need to include the LeapYear.h header and have that header export our function.
Our LeapYear header will look like this now (don't forget the include in the test file, it is not shown here) :

<source lang="cpp">
#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

bool IsLeapYear(int Year);

#endif // LEAPYEAR_H_INCLUDED

</source>

At least now it compiles, but it doesn't link yet. Duh, that because we don't have an implementation yet.
Time to provide the bare minimum of code to make the test pass.
So we change the LeapYear.cpp into :

<source lang="cpp">
#include "LeapYear.h"

bool IsLeapYear(int /*Year*/)
{
return true;
}

</source>
Build it, run it. Yes, we have one test passed.
Great. Let's move on.

== LeapYear-Step3 ==
Anyone having the feeling we are cheating. Well the user does not know how we wrote our code on the inside. So just to be sure the user (we) adds the following test, ending up in :

<source lang="cpp">
#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

TEST(OurSecondTest)
{
const bool Result = IsLeapYear(1973);
CHECK_EQUAL(false, Result);
}

}

</source>
Building is already no issue any more, we can run it. Oh boy, a test is failing.
The framework tell us something like this :
<filename>:<Line>: error: Failure in OurSecondTest: Expected 0 but was 1
FAILURE: 1 out of 2 tests failed (1 failures)
Test time: 0.00 seconds.

So we are informed of the line where the failing tests occurs, next to that it tells us what it was expecting and what the actual outcome was. And it presents a resume of the total number of tests, and how many that failed. For you scripting hackers note that FAILURE != SUCCESS.

It seems we should do some more effort and implement some real logic.

== LeapYear-Step4 ==
Let's keep it taking one step at a time. Let's start by implementing the 'divisible by 4' logic. That will already solve our tests.
So our LeapYear.cpp will now look like this :

<source lang="cpp">
#include "LeapYear.h"

namespace
{

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year);
}

}

</source>
Build, run. All tests pass. Life is great.

But those changing requirements, always the change of the requirements. Years that can be divided by 100 should not be considered as a leap year.

Time for our next step.

== LeapYear-Step5 ==
We add a new test for checking for example the year 1900.

<source lang="cpp">
TEST(DivisableBy100)
{
const bool Result = IsLeapYear(1900);
CHECK_EQUAL(false, Result);
}
</source>

Build and run the tests. It will fail. So time to add the minimum code needed to make this test pass.
This will change our LeapYear.cpp into :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year) && !IsDivisableBy100(Year);
}
</source>

Build and run the tests, yes : success. All 3 tests pass.

It seems life might be great again ...

Wrong, someone just added the following test :

<source lang="cpp">
TEST(DivisableBy400)
{
const bool Result = IsLeapYear(2000);
CHECK_EQUAL(true, Result);
}
</source>

And we once again have a failing test.

Time for the next step.

== LeapYear-Step6 ==
We should add logic to deal with years that can be divided by 400, since those are leap years.
We change our LeapYear.cpp into this :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy400(int Year)
{
return (Year%400) == 0;
}

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
const bool LeapYear = IsDivisableBy400(Year) ||
(IsDivisableBy4(Year) && !IsDivisableBy100(Year));
return LeapYear;
}

</source>

And once again everything works OK.
And it seems all the logical rules have been implemented.
This one is ready for shipping, and till the end of time we have our tests that can be run whenever we want (more on this later, we'd prefer this to be done automatically) to ensure we never break anything.

UnitTesting

2009-09-09T10:59:45Z

Killerbot: /* LeapYear-Step1 */

This document is under development by killerbot. Starting from 7 September 2009.

== Introduction ==
This document will describe how unit testing can be combined with the Code::Blocks IDE. It will give a hands-on example on a unit testing framework and how it can be used with Code::Blocks.

== What is Unit Testing ==
Simply put Unit Testing is the discipline and best practice of writing and running little test programs that test little units of code.
Such a unit can be :
* a class
* a free function
* an interface
* ...
There are several unit test frameworks available to help you write, deploy, manage your unit tests. The most famous family is the xUnit framework, and some of it's descendants.

== Why Unit Testing ==
Well we write code that implements some functionality. We need a way to check and prove that the implementation is correct. Therefor we need tests. We need tests on the application level, at the integration level of different components, classes, interfaces. But we also need tests for the smallest building blocks, the units.
We also wans these tests to run very quickly. That we we can run the tests often, manually or automated.
These tests will also be our safeguards during refactoring of the code, extending the code or whatever maintenance tasks we carry out on the code.
These tests will also make us think of how our class, method, ... will be used. Since the test can be seen as a user of our code. Thanks do this, thinking about the tests before implementing the functionality can help us in the design : emergent design.
It will help us to avoid creating big classes, complex functions. We will only write the methods that are really needed, and no methods that we think might (n)ever be useful in the future. We are no good future tellers ! Those 'might be needed' methods and their tests are just a waste of time. Extending, refactoring will be done when it is actually needed, and at that time we have our unit tests to ensure we don't break any existing code.

Other times to add new unit tests are typically when a bug is discovered; Write a unit test to reproduces the bug, fix the code, and from now on the new unit test will watch your back so the bug won't reappear.

Unit test are also a good place of documentation. The little tests show how the class or method is used.
The code documents itself.

So the benefits are :
* better design
* prove of your code
* safe guard during code maintenance (refactoring, extensions)
* documentation
* ...

== Unit Test frameworks ==
When writing unit tests, one will create a lot of similar code. Since unit tests are nothing more then little programs, several tasks will be repeated, setting up the test environment, create your class, call a method, verify it's result, write out an error message when the test fails, preferably specifying what the wrong outcome was, and what the expected result is.
All these repetitive chores are taken care of by the frame work so the developer can focus on the real code of the test.
This document will use a small but very effective framework for the C++ language. It is called UnitTest++. It's homepage is at : [http://unittest-cpp.sourceforge.net/ UnitTest++].
You can download it directly at this [http://sourceforge.net/projects/unittest-cpp/files/UnitTest%2B%2B/1.4/unittest-cpp-1.4.zip/download link]. At the time of writing the latest version is 1.4.

== Setup our environment ==
Let's create a directory on our PC in which we will cary out our experiments. I will refer to this directory from now on as <TestPit>. For my laptop on which I am writing this article, that will be /home/lieven/Projects/UnitTestArticle. Note that everything we will do, works on linux and on windows!
Download the "unittest-cpp-1.4.zip" file from the link specified above. Extract it in the <TestPit> directory. All the files will end up in the <TestPit>/UnitTest++ directory.

== Build UnitTest++ ==
After the extracted the zip archive we have a directory structure like this :
<TestPit>/UnitTest++
|
+docs
|
+src

The files in the UnitTest++ directory are of little use for us, since they bring project files for some bizarre Microsoft IDE ;-) .
We will create our own Code::Blocks project to build the UnitTest++ framework.

Why do we need to build something ? Well as said, the framework will do a lot of chores for us, those chores are implemented by code, that code is framework. We will build to frame work into a static library, and for every unit test (or set of unit tests) we create a little (console/shell) program with the test code we wrote, which will link with the static library to obtain a unit test executable, driven by the framework.

We will put our Code::Blocks project file in a nice structured directory tree, therefor let's create a 'Project' subdirectory in the <TestPit>/UniTest++ directory.

In there create a new file with the name "UnitTest++.cbp".
Give that file the following content :

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="UnitTest++" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option platforms="Windows;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option platforms="Windows;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
<Target title="Debug(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<VirtualTargets>
<Add alias="All" targets="Debug;Release;Debug(linux);Release(linux);" />
</VirtualTargets>
<Unit filename="../src/AssertException.cpp" />
<Unit filename="../src/AssertException.h" />
<Unit filename="../src/CheckMacros.h" />
<Unit filename="../src/Checks.cpp" />
<Unit filename="../src/Checks.h" />
<Unit filename="../src/Config.h" />
<Unit filename="../src/CurrentTest.cpp" />
<Unit filename="../src/CurrentTest.h" />
<Unit filename="../src/DeferredTestReporter.cpp" />
<Unit filename="../src/DeferredTestReporter.h" />
<Unit filename="../src/DeferredTestResult.cpp" />
<Unit filename="../src/DeferredTestResult.h" />
<Unit filename="../src/ExecuteTest.h" />
<Unit filename="../src/MemoryOutStream.cpp" />
<Unit filename="../src/MemoryOutStream.h" />
<Unit filename="../src/Posix/SignalTranslator.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/SignalTranslator.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/ReportAssert.cpp" />
<Unit filename="../src/ReportAssert.h" />
<Unit filename="../src/Test.cpp" />
<Unit filename="../src/Test.h" />
<Unit filename="../src/TestDetails.cpp" />
<Unit filename="../src/TestDetails.h" />
<Unit filename="../src/TestList.cpp" />
<Unit filename="../src/TestList.h" />
<Unit filename="../src/TestMacros.h" />
<Unit filename="../src/TestReporter.cpp" />
<Unit filename="../src/TestReporter.h" />
<Unit filename="../src/TestReporterStdout.cpp" />
<Unit filename="../src/TestReporterStdout.h" />
<Unit filename="../src/TestResults.cpp" />
<Unit filename="../src/TestResults.h" />
<Unit filename="../src/TestRunner.cpp" />
<Unit filename="../src/TestRunner.h" />
<Unit filename="../src/TestSuite.h" />
<Unit filename="../src/TimeConstraint.cpp" />
<Unit filename="../src/TimeConstraint.h" />
<Unit filename="../src/TimeHelpers.h" />
<Unit filename="../src/UnitTest++.h" />
<Unit filename="../src/Win32/TimeHelpers.cpp">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/Win32/TimeHelpers.h">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/XmlTestReporter.cpp" />
<Unit filename="../src/XmlTestReporter.h" />
<Extensions>
<envvars />
<code_completion />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

Some things to note about the content of the project file, the power of Code::Blocks.
* there are 4 targets : Debug/Release for Windows and Debug/Release for linux [yes : 1 project file that allows building on linux and on windows]
* some files are only part of the linux targets, some only for the windows targets

But before we build, let's modify some source files (not really needed, but I prefer to have warning free compilations). These are the changes I carried out :
* ReportAssert.cpp : #include "ReportAssert.h"
* win32/TimeHelpers.cpp : first the m_threadHandle and then the m_startTime in the initializerlist

Next open up this project file in Code::Blocks and build the debug and release target. From now one we will only use the Release target, we go for speed ;-)

The result of the build process will show up in subdirectories of the new 'Deliv' subdirectory of <testPit>/UnitTest++ : '''<testPit>/UnitTest++/Deliv/Release/libUnitTest++.a'''

Alright, we have build the unit test framework in a platform independent way, no silly makefiles, no obscure M$ IDE, good old super Code::Blocks. It is time to write some code so we have something to unit test.

In the first example we will create a simple free function that checks if a a give year is a leap your or not.

The business logic is as follows : a year is a leap year when it can be divided by 4, unless itcan be divided by 100. But in case it can be divided by 400, then again it is a leap year.

In the next section we will first setup a Code::Blocks project containing both the 'functionality files, and the unit test files. Typically one will package several functionality files into a static library and create a unit test project that tests all the class/functionalities in that library package, also called a component. That is we have a component (whose deliverable is the static library, and we have a unit test project that tests the entire component).

== Our first test project environment ==
Let's create a new directory in our <TestPit> : <TestPit>/LeapYear.
For the simplicity we will put the project file and the source file all together in this directory. Normally we would work in a more structured way, but in a demo article we have some artistic freedom ;-)
Next you can create with the Code::Block's wizard a new console project in the LeapYear directory. Or you can create the following 5 files and give the the contents as specified below. Note that this demo works on linux and on windows, everything is still completely platform independent. Long Live Code::Blocks.

The project file : LeapYear.cbp (the one below already contains the 5 source files, in case you use the wizard you have to add the LeapYear.h/cpp and LeapYearTest.cpp files to the project)

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="LeapYear" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option output="Deliv/Debug/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Debug/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option output="Deliv/Release/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Release/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-O2" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<Compiler>
<Add option="-Wall" />
<Add option="-fexceptions" />
</Compiler>
<Unit filename="LeapYear.cpp" />
<Unit filename="LeapYear.h" />
<Unit filename="LeapYearTest.cpp" />
<Unit filename="main.cpp" />
<Extensions>
<envvars />
<code_completion />
<lib_finder disable_auto="1" />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

The main source file : main.cpp
int main()
{
return 0;
}

The header exporting our powerful function : LeapYear.h

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

#endif // LEAPYEAR_H_INCLUDED

And the implementation of the leap year logic : LeapYear.cpp

#include "LeapYear.h"

And finishing with the source file for the tests : LeapYearTest.cpp (currently) empty

We can already build the project, we have a nice little program that does .... nothing.

Time to move to the next section, a little word about Test Driven Development.

== Test Driven Development ==
This is a practice where new code is only added to make a failing test pass. And one only adds the code needed to make that test pass. Once that is done, a new test is added to will check the next functionality to add.
On this really simple example we will more or less practice some TDD.

So get ready, it's time for LeapYear-Step1.

== LeapYear-Step1 ==
We will turn our main.cpp into the guy in charge to carry out the tests, all we need to do is change the contents of main.cpp into this :

<source lang="cpp">
#include "UnitTest++.h"

int main()
{
return UnitTest::RunAllTests();
}

</source>
And add '''../UnitTest++/src''' to the compiler search directories on the project level of our LeapYear project.
And add '''../UnitTest++/Deliv/Release/libUnitTest++.a''' to the link libraries of the project

Why : well we need to link with the framework and we need to include the UnitTest++ header so we can use it's functionalities.

The line '''UnitTest::RunAllTests()''' will make sure all test encountered in our sources will be carried out.
We don't have any tests yet, nor any functionality, but go ahead build the project and run it.
This is the output :

Success: 0 tests passed
Test time: 0.00 seconds.

Great : success, but no tests yet. Well it's a start.
Time to move forward, and write our first test.

== LeapYear-Step2 ==
Test, test, but there's nothing to test. Yes, absolutely. Let's think of a test, a test that will help us in the design. Now that's a good idea. Suppose I would be the user of the uplifting problem solving leap year checking library/component ... hmmm modesty first : leap year checking '''function'''.
How would I like that function to look.
<source lang="cpp">
bool IsLeapYear(int Year);
</source>
Yes that seems acceptable.
So let's write a test that will call that method.
We do that by adding the following code to LeapYearTest.cpp

<source lang="cpp">
#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

}

</source>
Things to note :
* we include the unit test header
* it is good to put the tests in nameless namespace (will be explained later on)
* we use the TEST macro, the argument is the name of the test : OurFirstTest
* we use CHECK_EQUAL to check if the expected result (the first argument) matches the computed result (the second argument)

Time to build. Woooooops errors. The tests fails completely, it does not even build. Time to add the code needed.
In order to compiler the test file, we need to include the LeapYear.h header and have that header export our function.
Our LeapYear header will look like this now (don't forget the include in the test file, it is not shown here) :

<source lang="cpp">
#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

bool IsLeapYear(int Year);

#endif // LEAPYEAR_H_INCLUDED

</source>

At least now it compiles, but it doesn't link yet. Duh, that because we don't have an implementation yet.
Time to provide the bare minimum of code to make the test pass.
So we change the LeapYear.cpp into :

<source lang="cpp">
#include "LeapYear.h"

bool IsLeapYear(int /*Year*/)
{
return true;
}

</source>
Build it, run it. Yes, we have one test passed.
Great. Let's move on.

== LeapYear-Step3 ==
Anyone having the feeling we are cheating. Well the user does not know how we wrote our code on the inside. So just to be sure the user (we) adds the following test, ending up in :

<source lang="cpp">
#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

TEST(OurSecondTest)
{
const bool Result = IsLeapYear(1973);
CHECK_EQUAL(false, Result);
}

}

</source>
Building is already no issue any more, we can run it. Oh boy, a test is failing.
The framework tell us something like this :
<filename>:<Line>: error: Failure in OurSecondTest: Expected 0 but was 1
FAILURE: 1 out of 2 tests failed (1 failures)
Test time: 0.00 seconds.

So we are informed of the line where the failing tests occurs, next to that it tells us what it was expecting and what the actual outcome was. And it presents a resume of the total number of tests, and how many that failed. For you scripting hackers note that FAILURE != SUCCESS.

It seems we should do some more effort and implement some real logic.

== LeapYear-Step4 ==
Let's keep it taking one step at a time. Let's start by implementing the 'divisible by 4' logic. That will already solve our tests.
So our LeapYear.cpp will now look like this :

<source lang="cpp">
#include "LeapYear.h"

namespace
{

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year);
}

</source>
Build, run. All tests pass. Life is great.

But those changing requirements, always the change of the requirements. Years that can be divided by 100 should not be considered as a leap year.

Time for our next step.

== LeapYear-Step5 ==
We add a new test for checking for example the year 1900.

<source lang="cpp">
TEST(DivisableBy100)
{
const bool Result = IsLeapYear(1900);
CHECK_EQUAL(false, Result);
}
</source>

Build and run the tests. It will fail. So time to add the minimum code needed to make this test pass.
This will change our LeapYear.cpp into :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year) && !IsDivisableBy100(Year);
}
</source>

Build and run the tests, yes : success. All 3 tests pass.

It seems life might be great again ...

Wrong, someone just added the following test :

<source lang="cpp">
TEST(DivisableBy400)
{
const bool Result = IsLeapYear(2000);
CHECK_EQUAL(true, Result);
}
</source>

And we once again have a failing test.

Time for the next step.

== LeapYear-Step6 ==
We should add logic to deal with years that can be divided by 400, since those are leap years.
We change our LeapYear.cpp into this :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy400(int Year)
{
return (Year%400) == 0;
}

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
const bool LeapYear = IsDivisableBy400(Year) ||
(IsDivisableBy4(Year) && !IsDivisableBy100(Year));
return LeapYear;
}

</source>

And once again everything works OK.
And it seems all the logical rules have been implemented.
This one is ready for shipping, and till the end of time we have our tests that can be run whenever we want (more on this later, we'd prefer this to be done automatically) to ensure we never break anything.

UnitTesting

2009-09-09T10:32:17Z

Killerbot: /* Our first test project environment */

This document is under development by killerbot. Starting from 7 September 2009.

== Introduction ==
This document will describe how unit testing can be combined with the Code::Blocks IDE. It will give a hands-on example on a unit testing framework and how it can be used with Code::Blocks.

== What is Unit Testing ==
Simply put Unit Testing is the discipline and best practice of writing and running little test programs that test little units of code.
Such a unit can be :
* a class
* a free function
* an interface
* ...
There are several unit test frameworks available to help you write, deploy, manage your unit tests. The most famous family is the xUnit framework, and some of it's descendants.

== Why Unit Testing ==
Well we write code that implements some functionality. We need a way to check and prove that the implementation is correct. Therefor we need tests. We need tests on the application level, at the integration level of different components, classes, interfaces. But we also need tests for the smallest building blocks, the units.
We also wans these tests to run very quickly. That we we can run the tests often, manually or automated.
These tests will also be our safeguards during refactoring of the code, extending the code or whatever maintenance tasks we carry out on the code.
These tests will also make us think of how our class, method, ... will be used. Since the test can be seen as a user of our code. Thanks do this, thinking about the tests before implementing the functionality can help us in the design : emergent design.
It will help us to avoid creating big classes, complex functions. We will only write the methods that are really needed, and no methods that we think might (n)ever be useful in the future. We are no good future tellers ! Those 'might be needed' methods and their tests are just a waste of time. Extending, refactoring will be done when it is actually needed, and at that time we have our unit tests to ensure we don't break any existing code.

Other times to add new unit tests are typically when a bug is discovered; Write a unit test to reproduces the bug, fix the code, and from now on the new unit test will watch your back so the bug won't reappear.

Unit test are also a good place of documentation. The little tests show how the class or method is used.
The code documents itself.

So the benefits are :
* better design
* prove of your code
* safe guard during code maintenance (refactoring, extensions)
* documentation
* ...

== Unit Test frameworks ==
When writing unit tests, one will create a lot of similar code. Since unit tests are nothing more then little programs, several tasks will be repeated, setting up the test environment, create your class, call a method, verify it's result, write out an error message when the test fails, preferably specifying what the wrong outcome was, and what the expected result is.
All these repetitive chores are taken care of by the frame work so the developer can focus on the real code of the test.
This document will use a small but very effective framework for the C++ language. It is called UnitTest++. It's homepage is at : [http://unittest-cpp.sourceforge.net/ UnitTest++].
You can download it directly at this [http://sourceforge.net/projects/unittest-cpp/files/UnitTest%2B%2B/1.4/unittest-cpp-1.4.zip/download link]. At the time of writing the latest version is 1.4.

== Setup our environment ==
Let's create a directory on our PC in which we will cary out our experiments. I will refer to this directory from now on as <TestPit>. For my laptop on which I am writing this article, that will be /home/lieven/Projects/UnitTestArticle. Note that everything we will do, works on linux and on windows!
Download the "unittest-cpp-1.4.zip" file from the link specified above. Extract it in the <TestPit> directory. All the files will end up in the <TestPit>/UnitTest++ directory.

== Build UnitTest++ ==
After the extracted the zip archive we have a directory structure like this :
<TestPit>/UnitTest++
|
+docs
|
+src

The files in the UnitTest++ directory are of little use for us, since they bring project files for some bizarre Microsoft IDE ;-) .
We will create our own Code::Blocks project to build the UnitTest++ framework.

Why do we need to build something ? Well as said, the framework will do a lot of chores for us, those chores are implemented by code, that code is framework. We will build to frame work into a static library, and for every unit test (or set of unit tests) we create a little (console/shell) program with the test code we wrote, which will link with the static library to obtain a unit test executable, driven by the framework.

We will put our Code::Blocks project file in a nice structured directory tree, therefor let's create a 'Project' subdirectory in the <TestPit>/UniTest++ directory.

In there create a new file with the name "UnitTest++.cbp".
Give that file the following content :

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="UnitTest++" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option platforms="Windows;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option platforms="Windows;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
<Target title="Debug(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<VirtualTargets>
<Add alias="All" targets="Debug;Release;Debug(linux);Release(linux);" />
</VirtualTargets>
<Unit filename="../src/AssertException.cpp" />
<Unit filename="../src/AssertException.h" />
<Unit filename="../src/CheckMacros.h" />
<Unit filename="../src/Checks.cpp" />
<Unit filename="../src/Checks.h" />
<Unit filename="../src/Config.h" />
<Unit filename="../src/CurrentTest.cpp" />
<Unit filename="../src/CurrentTest.h" />
<Unit filename="../src/DeferredTestReporter.cpp" />
<Unit filename="../src/DeferredTestReporter.h" />
<Unit filename="../src/DeferredTestResult.cpp" />
<Unit filename="../src/DeferredTestResult.h" />
<Unit filename="../src/ExecuteTest.h" />
<Unit filename="../src/MemoryOutStream.cpp" />
<Unit filename="../src/MemoryOutStream.h" />
<Unit filename="../src/Posix/SignalTranslator.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/SignalTranslator.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/ReportAssert.cpp" />
<Unit filename="../src/ReportAssert.h" />
<Unit filename="../src/Test.cpp" />
<Unit filename="../src/Test.h" />
<Unit filename="../src/TestDetails.cpp" />
<Unit filename="../src/TestDetails.h" />
<Unit filename="../src/TestList.cpp" />
<Unit filename="../src/TestList.h" />
<Unit filename="../src/TestMacros.h" />
<Unit filename="../src/TestReporter.cpp" />
<Unit filename="../src/TestReporter.h" />
<Unit filename="../src/TestReporterStdout.cpp" />
<Unit filename="../src/TestReporterStdout.h" />
<Unit filename="../src/TestResults.cpp" />
<Unit filename="../src/TestResults.h" />
<Unit filename="../src/TestRunner.cpp" />
<Unit filename="../src/TestRunner.h" />
<Unit filename="../src/TestSuite.h" />
<Unit filename="../src/TimeConstraint.cpp" />
<Unit filename="../src/TimeConstraint.h" />
<Unit filename="../src/TimeHelpers.h" />
<Unit filename="../src/UnitTest++.h" />
<Unit filename="../src/Win32/TimeHelpers.cpp">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/Win32/TimeHelpers.h">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/XmlTestReporter.cpp" />
<Unit filename="../src/XmlTestReporter.h" />
<Extensions>
<envvars />
<code_completion />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

Some things to note about the content of the project file, the power of Code::Blocks.
* there are 4 targets : Debug/Release for Windows and Debug/Release for linux [yes : 1 project file that allows building on linux and on windows]
* some files are only part of the linux targets, some only for the windows targets

But before we build, let's modify some source files (not really needed, but I prefer to have warning free compilations). These are the changes I carried out :
* ReportAssert.cpp : #include "ReportAssert.h"
* win32/TimeHelpers.cpp : first the m_threadHandle and then the m_startTime in the initializerlist

Next open up this project file in Code::Blocks and build the debug and release target. From now one we will only use the Release target, we go for speed ;-)

The result of the build process will show up in subdirectories of the new 'Deliv' subdirectory of <testPit>/UnitTest++ : '''<testPit>/UnitTest++/Deliv/Release/libUnitTest++.a'''

Alright, we have build the unit test framework in a platform independent way, no silly makefiles, no obscure M$ IDE, good old super Code::Blocks. It is time to write some code so we have something to unit test.

In the first example we will create a simple free function that checks if a a give year is a leap your or not.

The business logic is as follows : a year is a leap year when it can be divided by 4, unless itcan be divided by 100. But in case it can be divided by 400, then again it is a leap year.

In the next section we will first setup a Code::Blocks project containing both the 'functionality files, and the unit test files. Typically one will package several functionality files into a static library and create a unit test project that tests all the class/functionalities in that library package, also called a component. That is we have a component (whose deliverable is the static library, and we have a unit test project that tests the entire component).

== Our first test project environment ==
Let's create a new directory in our <TestPit> : <TestPit>/LeapYear.
For the simplicity we will put the project file and the source file all together in this directory. Normally we would work in a more structured way, but in a demo article we have some artistic freedom ;-)
Next you can create with the Code::Block's wizard a new console project in the LeapYear directory. Or you can create the following 5 files and give the the contents as specified below. Note that this demo works on linux and on windows, everything is still completely platform independent. Long Live Code::Blocks.

The project file : LeapYear.cbp (the one below already contains the 5 source files, in case you use the wizard you have to add the LeapYear.h/cpp and LeapYearTest.cpp files to the project)

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="LeapYear" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option output="Deliv/Debug/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Debug/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option output="Deliv/Release/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Release/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-O2" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<Compiler>
<Add option="-Wall" />
<Add option="-fexceptions" />
</Compiler>
<Unit filename="LeapYear.cpp" />
<Unit filename="LeapYear.h" />
<Unit filename="LeapYearTest.cpp" />
<Unit filename="main.cpp" />
<Extensions>
<envvars />
<code_completion />
<lib_finder disable_auto="1" />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

The main source file : main.cpp
int main()
{
return 0;
}

The header exporting our powerful function : LeapYear.h

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

#endif // LEAPYEAR_H_INCLUDED

And the implementation of the leap year logic : LeapYear.cpp

#include "LeapYear.h"

And finishing with the source file for the tests : LeapYearTest.cpp (currently) empty

We can already build the project, we have a nice little program that does .... nothing.

Time to move to the next section, a little word about Test Driven Development.

== Test Driven Development ==
This is a practice where new code is only added to make a failing test pass. And one only adds the code needed to make that test pass. Once that is done, a new test is added to will check the next functionality to add.
On this really simple example we will more or less practice some TDD.

So get ready, it's time for LeapYear-Step1.

== LeapYear-Step1 ==
We will turn our main.cpp into the guy in charge to carry out the tests, all we need to do is change the contents of main.cpp into this :

#include "UnitTest++.h"

int main()
{
return UnitTest::RunAllTests();
}

And add '''../UnitTest++/src''' to the compiler search directories on the project level of our LeapYear project.
And add '''../UnitTest++/Deliv/Release/libUnitTest++.a''' to the link libraries of the project

Why : well we need to link with the framework and we need to include the UnitTest++ header so we can use it's functionalities.

The line '''UnitTest::RunAllTests()''' will make sure all test encountered in our sources will be carried out.
We don't have any tests yet, nor any functionality, but go ahead build the project and run it.
This is the output :

Success: 0 tests passed
Test time: 0.00 seconds.

Great : success, but no tests yet. Well it's a start.
Time to move forward, and write our first test.

== LeapYear-Step2 ==
Test, test, but there's nothing to test. Yes, absolutely. Let's think of a test, a test that will help us in the design. Now that's a good idea. Suppose I would be the user of the uplifting problem solving leap year checking library/component ... hmmm modesty first : leap year checking '''function'''.
How would I like that function to look.
<source lang="cpp">
bool IsLeapYear(int Year);
</source>
Yes that seems acceptable.
So let's write a test that will call that method.
We do that by adding the following code to LeapYearTest.cpp

<source lang="cpp">
#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

}

</source>
Things to note :
* we include the unit test header
* it is good to put the tests in nameless namespace (will be explained later on)
* we use the TEST macro, the argument is the name of the test : OurFirstTest
* we use CHECK_EQUAL to check if the expected result (the first argument) matches the computed result (the second argument)

Time to build. Woooooops errors. The tests fails completely, it does not even build. Time to add the code needed.
In order to compiler the test file, we need to include the LeapYear.h header and have that header export our function.
Our LeapYear header will look like this now (don't forget the include in the test file, it is not shown here) :

<source lang="cpp">
#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

bool IsLeapYear(int Year);

#endif // LEAPYEAR_H_INCLUDED

</source>

At least now it compiles, but it doesn't link yet. Duh, that because we don't have an implementation yet.
Time to provide the bare minimum of code to make the test pass.
So we change the LeapYear.cpp into :

<source lang="cpp">
#include "LeapYear.h"

bool IsLeapYear(int /*Year*/)
{
return true;
}

</source>
Build it, run it. Yes, we have one test passed.
Great. Let's move on.

== LeapYear-Step3 ==
Anyone having the feeling we are cheating. Well the user does not know how we wrote our code on the inside. So just to be sure the user (we) adds the following test, ending up in :

<source lang="cpp">
#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

TEST(OurSecondTest)
{
const bool Result = IsLeapYear(1973);
CHECK_EQUAL(false, Result);
}

}

</source>
Building is already no issue any more, we can run it. Oh boy, a test is failing.
The framework tell us something like this :
<filename>:<Line>: error: Failure in OurSecondTest: Expected 0 but was 1
FAILURE: 1 out of 2 tests failed (1 failures)
Test time: 0.00 seconds.

So we are informed of the line where the failing tests occurs, next to that it tells us what it was expecting and what the actual outcome was. And it presents a resume of the total number of tests, and how many that failed. For you scripting hackers note that FAILURE != SUCCESS.

It seems we should do some more effort and implement some real logic.

== LeapYear-Step4 ==
Let's keep it taking one step at a time. Let's start by implementing the 'divisible by 4' logic. That will already solve our tests.
So our LeapYear.cpp will now look like this :

<source lang="cpp">
#include "LeapYear.h"

namespace
{

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year);
}

</source>
Build, run. All tests pass. Life is great.

But those changing requirements, always the change of the requirements. Years that can be divided by 100 should not be considered as a leap year.

Time for our next step.

== LeapYear-Step5 ==
We add a new test for checking for example the year 1900.

<source lang="cpp">
TEST(DivisableBy100)
{
const bool Result = IsLeapYear(1900);
CHECK_EQUAL(false, Result);
}
</source>

Build and run the tests. It will fail. So time to add the minimum code needed to make this test pass.
This will change our LeapYear.cpp into :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year) && !IsDivisableBy100(Year);
}
</source>

Build and run the tests, yes : success. All 3 tests pass.

It seems life might be great again ...

Wrong, someone just added the following test :

<source lang="cpp">
TEST(DivisableBy400)
{
const bool Result = IsLeapYear(2000);
CHECK_EQUAL(true, Result);
}
</source>

And we once again have a failing test.

Time for the next step.

== LeapYear-Step6 ==
We should add logic to deal with years that can be divided by 400, since those are leap years.
We change our LeapYear.cpp into this :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy400(int Year)
{
return (Year%400) == 0;
}

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
const bool LeapYear = IsDivisableBy400(Year) ||
(IsDivisableBy4(Year) && !IsDivisableBy100(Year));
return LeapYear;
}

</source>

And once again everything works OK.
And it seems all the logical rules have been implemented.
This one is ready for shipping, and till the end of time we have our tests that can be run whenever we want (more on this later, we'd prefer this to be done automatically) to ensure we never break anything.

UnitTesting

2009-09-09T10:26:36Z

Killerbot: /* LeapYear-Step2 */

This document is under development by killerbot. Starting from 7 September 2009.

== Introduction ==
This document will describe how unit testing can be combined with the Code::Blocks IDE. It will give a hands-on example on a unit testing framework and how it can be used with Code::Blocks.

== What is Unit Testing ==
Simply put Unit Testing is the discipline and best practice of writing and running little test programs that test little units of code.
Such a unit can be :
* a class
* a free function
* an interface
* ...
There are several unit test frameworks available to help you write, deploy, manage your unit tests. The most famous family is the xUnit framework, and some of it's descendants.

== Why Unit Testing ==
Well we write code that implements some functionality. We need a way to check and prove that the implementation is correct. Therefor we need tests. We need tests on the application level, at the integration level of different components, classes, interfaces. But we also need tests for the smallest building blocks, the units.
We also wans these tests to run very quickly. That we we can run the tests often, manually or automated.
These tests will also be our safeguards during refactoring of the code, extending the code or whatever maintenance tasks we carry out on the code.
These tests will also make us think of how our class, method, ... will be used. Since the test can be seen as a user of our code. Thanks do this, thinking about the tests before implementing the functionality can help us in the design : emergent design.
It will help us to avoid creating big classes, complex functions. We will only write the methods that are really needed, and no methods that we think might (n)ever be useful in the future. We are no good future tellers ! Those 'might be needed' methods and their tests are just a waste of time. Extending, refactoring will be done when it is actually needed, and at that time we have our unit tests to ensure we don't break any existing code.

Other times to add new unit tests are typically when a bug is discovered; Write a unit test to reproduces the bug, fix the code, and from now on the new unit test will watch your back so the bug won't reappear.

Unit test are also a good place of documentation. The little tests show how the class or method is used.
The code documents itself.

So the benefits are :
* better design
* prove of your code
* safe guard during code maintenance (refactoring, extensions)
* documentation
* ...

== Unit Test frameworks ==
When writing unit tests, one will create a lot of similar code. Since unit tests are nothing more then little programs, several tasks will be repeated, setting up the test environment, create your class, call a method, verify it's result, write out an error message when the test fails, preferably specifying what the wrong outcome was, and what the expected result is.
All these repetitive chores are taken care of by the frame work so the developer can focus on the real code of the test.
This document will use a small but very effective framework for the C++ language. It is called UnitTest++. It's homepage is at : [http://unittest-cpp.sourceforge.net/ UnitTest++].
You can download it directly at this [http://sourceforge.net/projects/unittest-cpp/files/UnitTest%2B%2B/1.4/unittest-cpp-1.4.zip/download link]. At the time of writing the latest version is 1.4.

== Setup our environment ==
Let's create a directory on our PC in which we will cary out our experiments. I will refer to this directory from now on as <TestPit>. For my laptop on which I am writing this article, that will be /home/lieven/Projects/UnitTestArticle. Note that everything we will do, works on linux and on windows!
Download the "unittest-cpp-1.4.zip" file from the link specified above. Extract it in the <TestPit> directory. All the files will end up in the <TestPit>/UnitTest++ directory.

== Build UnitTest++ ==
After the extracted the zip archive we have a directory structure like this :
<TestPit>/UnitTest++
|
+docs
|
+src

The files in the UnitTest++ directory are of little use for us, since they bring project files for some bizarre Microsoft IDE ;-) .
We will create our own Code::Blocks project to build the UnitTest++ framework.

Why do we need to build something ? Well as said, the framework will do a lot of chores for us, those chores are implemented by code, that code is framework. We will build to frame work into a static library, and for every unit test (or set of unit tests) we create a little (console/shell) program with the test code we wrote, which will link with the static library to obtain a unit test executable, driven by the framework.

We will put our Code::Blocks project file in a nice structured directory tree, therefor let's create a 'Project' subdirectory in the <TestPit>/UniTest++ directory.

In there create a new file with the name "UnitTest++.cbp".
Give that file the following content :

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="UnitTest++" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option platforms="Windows;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option platforms="Windows;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
<Target title="Debug(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<VirtualTargets>
<Add alias="All" targets="Debug;Release;Debug(linux);Release(linux);" />
</VirtualTargets>
<Unit filename="../src/AssertException.cpp" />
<Unit filename="../src/AssertException.h" />
<Unit filename="../src/CheckMacros.h" />
<Unit filename="../src/Checks.cpp" />
<Unit filename="../src/Checks.h" />
<Unit filename="../src/Config.h" />
<Unit filename="../src/CurrentTest.cpp" />
<Unit filename="../src/CurrentTest.h" />
<Unit filename="../src/DeferredTestReporter.cpp" />
<Unit filename="../src/DeferredTestReporter.h" />
<Unit filename="../src/DeferredTestResult.cpp" />
<Unit filename="../src/DeferredTestResult.h" />
<Unit filename="../src/ExecuteTest.h" />
<Unit filename="../src/MemoryOutStream.cpp" />
<Unit filename="../src/MemoryOutStream.h" />
<Unit filename="../src/Posix/SignalTranslator.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/SignalTranslator.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/ReportAssert.cpp" />
<Unit filename="../src/ReportAssert.h" />
<Unit filename="../src/Test.cpp" />
<Unit filename="../src/Test.h" />
<Unit filename="../src/TestDetails.cpp" />
<Unit filename="../src/TestDetails.h" />
<Unit filename="../src/TestList.cpp" />
<Unit filename="../src/TestList.h" />
<Unit filename="../src/TestMacros.h" />
<Unit filename="../src/TestReporter.cpp" />
<Unit filename="../src/TestReporter.h" />
<Unit filename="../src/TestReporterStdout.cpp" />
<Unit filename="../src/TestReporterStdout.h" />
<Unit filename="../src/TestResults.cpp" />
<Unit filename="../src/TestResults.h" />
<Unit filename="../src/TestRunner.cpp" />
<Unit filename="../src/TestRunner.h" />
<Unit filename="../src/TestSuite.h" />
<Unit filename="../src/TimeConstraint.cpp" />
<Unit filename="../src/TimeConstraint.h" />
<Unit filename="../src/TimeHelpers.h" />
<Unit filename="../src/UnitTest++.h" />
<Unit filename="../src/Win32/TimeHelpers.cpp">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/Win32/TimeHelpers.h">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/XmlTestReporter.cpp" />
<Unit filename="../src/XmlTestReporter.h" />
<Extensions>
<envvars />
<code_completion />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

Some things to note about the content of the project file, the power of Code::Blocks.
* there are 4 targets : Debug/Release for Windows and Debug/Release for linux [yes : 1 project file that allows building on linux and on windows]
* some files are only part of the linux targets, some only for the windows targets

But before we build, let's modify some source files (not really needed, but I prefer to have warning free compilations). These are the changes I carried out :
* ReportAssert.cpp : #include "ReportAssert.h"
* win32/TimeHelpers.cpp : first the m_threadHandle and then the m_startTime in the initializerlist

Next open up this project file in Code::Blocks and build the debug and release target. From now one we will only use the Release target, we go for speed ;-)

The result of the build process will show up in subdirectories of the new 'Deliv' subdirectory of <testPit>/UnitTest++ : '''<testPit>/UnitTest++/Deliv/Release/libUnitTest++.a'''

Alright, we have build the unit test framework in a platform independent way, no silly makefiles, no obscure M$ IDE, good old super Code::Blocks. It is time to write some code so we have something to unit test.

In the first example we will create a simple free function that checks if a a give year is a leap your or not.

The business logic is as follows : a year is a leap year when it can be divided by 4, unless itcan be divided by 100. But in case it can be divided by 400, then again it is a leap year.

In the next section we will first setup a Code::Blocks project containing both the 'functionality files, and the unit test files. Typically one will package several functionality files into a static library and create a unit test project that tests all the class/functionalities in that library package, also called a component. That is we have a component (whose deliverable is the static library, and we have a unit test project that tests the entire component).

== Our first test project environment ==
Let's create a new directory in our <TestPit> : <TestPit>/LeapYear.
For the simplicity we will put the project file and the source file all together in this directory. Normally we would work in a more structured way, but in a demo article we have some artistic freedom ;-)
Next you can create with the Code::Block's wizard a new console project in the LeapYear directory. Or you can create the following 4 files and give the the contents as specified below. Note that this demo works on linux and on windows, everything is still completely platform independent. Long Live Code::Blocks.

The project file : LeapYear.cbp (the one below already contains the 3 source files, in case you use the wizard you have to add the LeapYear.h/cpp files to the project)

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="LeapYear" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option output="Deliv/Debug/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Debug/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option output="Deliv/Release/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Release/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-O2" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<Compiler>
<Add option="-Wall" />
<Add option="-fexceptions" />
</Compiler>
<Unit filename="LeapYear.cpp" />
<Unit filename="LeapYear.h" />
<Unit filename="main.cpp" />
<Extensions>
<envvars />
<code_completion />
<lib_finder disable_auto="1" />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

The main source file : main.cpp
int main()
{
return 0;
}

The header exporting our powerful function : LeapYear.h

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

#endif // LEAPYEAR_H_INCLUDED

And the implementation of the leap year logic : LeapYear.cpp

#include "LeapYear.h"

And finishing with the source file for the tests : LeapYearTest.cpp (currently) empty

We can already build the project, we have a nice little program that does .... nothing.

Time to move to the next section, a little word about Test Driven Development.

== Test Driven Development ==
This is a practice where new code is only added to make a failing test pass. And one only adds the code needed to make that test pass. Once that is done, a new test is added to will check the next functionality to add.
On this really simple example we will more or less practice some TDD.

So get ready, it's time for LeapYear-Step1.

== LeapYear-Step1 ==
We will turn our main.cpp into the guy in charge to carry out the tests, all we need to do is change the contents of main.cpp into this :

#include "UnitTest++.h"

int main()
{
return UnitTest::RunAllTests();
}

And add '''../UnitTest++/src''' to the compiler search directories on the project level of our LeapYear project.
And add '''../UnitTest++/Deliv/Release/libUnitTest++.a''' to the link libraries of the project

Why : well we need to link with the framework and we need to include the UnitTest++ header so we can use it's functionalities.

The line '''UnitTest::RunAllTests()''' will make sure all test encountered in our sources will be carried out.
We don't have any tests yet, nor any functionality, but go ahead build the project and run it.
This is the output :

Success: 0 tests passed
Test time: 0.00 seconds.

Great : success, but no tests yet. Well it's a start.
Time to move forward, and write our first test.

== LeapYear-Step2 ==
Test, test, but there's nothing to test. Yes, absolutely. Let's think of a test, a test that will help us in the design. Now that's a good idea. Suppose I would be the user of the uplifting problem solving leap year checking library/component ... hmmm modesty first : leap year checking '''function'''.
How would I like that function to look.
<source lang="cpp">
bool IsLeapYear(int Year);
</source>
Yes that seems acceptable.
So let's write a test that will call that method.
We do that by adding the following code to LeapYearTest.cpp

<source lang="cpp">
#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

}

</source>
Things to note :
* we include the unit test header
* it is good to put the tests in nameless namespace (will be explained later on)
* we use the TEST macro, the argument is the name of the test : OurFirstTest
* we use CHECK_EQUAL to check if the expected result (the first argument) matches the computed result (the second argument)

Time to build. Woooooops errors. The tests fails completely, it does not even build. Time to add the code needed.
In order to compiler the test file, we need to include the LeapYear.h header and have that header export our function.
Our LeapYear header will look like this now (don't forget the include in the test file, it is not shown here) :

<source lang="cpp">
#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

bool IsLeapYear(int Year);

#endif // LEAPYEAR_H_INCLUDED

</source>

At least now it compiles, but it doesn't link yet. Duh, that because we don't have an implementation yet.
Time to provide the bare minimum of code to make the test pass.
So we change the LeapYear.cpp into :

<source lang="cpp">
#include "LeapYear.h"

bool IsLeapYear(int /*Year*/)
{
return true;
}

</source>
Build it, run it. Yes, we have one test passed.
Great. Let's move on.

== LeapYear-Step3 ==
Anyone having the feeling we are cheating. Well the user does not know how we wrote our code on the inside. So just to be sure the user (we) adds the following test, ending up in :

<source lang="cpp">
#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

TEST(OurSecondTest)
{
const bool Result = IsLeapYear(1973);
CHECK_EQUAL(false, Result);
}

}

</source>
Building is already no issue any more, we can run it. Oh boy, a test is failing.
The framework tell us something like this :
<filename>:<Line>: error: Failure in OurSecondTest: Expected 0 but was 1
FAILURE: 1 out of 2 tests failed (1 failures)
Test time: 0.00 seconds.

So we are informed of the line where the failing tests occurs, next to that it tells us what it was expecting and what the actual outcome was. And it presents a resume of the total number of tests, and how many that failed. For you scripting hackers note that FAILURE != SUCCESS.

It seems we should do some more effort and implement some real logic.

== LeapYear-Step4 ==
Let's keep it taking one step at a time. Let's start by implementing the 'divisible by 4' logic. That will already solve our tests.
So our LeapYear.cpp will now look like this :

<source lang="cpp">
#include "LeapYear.h"

namespace
{

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year);
}

</source>
Build, run. All tests pass. Life is great.

But those changing requirements, always the change of the requirements. Years that can be divided by 100 should not be considered as a leap year.

Time for our next step.

== LeapYear-Step5 ==
We add a new test for checking for example the year 1900.

<source lang="cpp">
TEST(DivisableBy100)
{
const bool Result = IsLeapYear(1900);
CHECK_EQUAL(false, Result);
}
</source>

Build and run the tests. It will fail. So time to add the minimum code needed to make this test pass.
This will change our LeapYear.cpp into :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year) && !IsDivisableBy100(Year);
}
</source>

Build and run the tests, yes : success. All 3 tests pass.

It seems life might be great again ...

Wrong, someone just added the following test :

<source lang="cpp">
TEST(DivisableBy400)
{
const bool Result = IsLeapYear(2000);
CHECK_EQUAL(true, Result);
}
</source>

And we once again have a failing test.

Time for the next step.

== LeapYear-Step6 ==
We should add logic to deal with years that can be divided by 400, since those are leap years.
We change our LeapYear.cpp into this :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy400(int Year)
{
return (Year%400) == 0;
}

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
const bool LeapYear = IsDivisableBy400(Year) ||
(IsDivisableBy4(Year) && !IsDivisableBy100(Year));
return LeapYear;
}

</source>

And once again everything works OK.
And it seems all the logical rules have been implemented.
This one is ready for shipping, and till the end of time we have our tests that can be run whenever we want (more on this later, we'd prefer this to be done automatically) to ensure we never break anything.

UnitTesting

2009-09-09T10:25:31Z

Killerbot: /* LeapYear-Step3 */

This document is under development by killerbot. Starting from 7 September 2009.

== Introduction ==
This document will describe how unit testing can be combined with the Code::Blocks IDE. It will give a hands-on example on a unit testing framework and how it can be used with Code::Blocks.

== What is Unit Testing ==
Simply put Unit Testing is the discipline and best practice of writing and running little test programs that test little units of code.
Such a unit can be :
* a class
* a free function
* an interface
* ...
There are several unit test frameworks available to help you write, deploy, manage your unit tests. The most famous family is the xUnit framework, and some of it's descendants.

== Why Unit Testing ==
Well we write code that implements some functionality. We need a way to check and prove that the implementation is correct. Therefor we need tests. We need tests on the application level, at the integration level of different components, classes, interfaces. But we also need tests for the smallest building blocks, the units.
We also wans these tests to run very quickly. That we we can run the tests often, manually or automated.
These tests will also be our safeguards during refactoring of the code, extending the code or whatever maintenance tasks we carry out on the code.
These tests will also make us think of how our class, method, ... will be used. Since the test can be seen as a user of our code. Thanks do this, thinking about the tests before implementing the functionality can help us in the design : emergent design.
It will help us to avoid creating big classes, complex functions. We will only write the methods that are really needed, and no methods that we think might (n)ever be useful in the future. We are no good future tellers ! Those 'might be needed' methods and their tests are just a waste of time. Extending, refactoring will be done when it is actually needed, and at that time we have our unit tests to ensure we don't break any existing code.

Other times to add new unit tests are typically when a bug is discovered; Write a unit test to reproduces the bug, fix the code, and from now on the new unit test will watch your back so the bug won't reappear.

Unit test are also a good place of documentation. The little tests show how the class or method is used.
The code documents itself.

So the benefits are :
* better design
* prove of your code
* safe guard during code maintenance (refactoring, extensions)
* documentation
* ...

== Unit Test frameworks ==
When writing unit tests, one will create a lot of similar code. Since unit tests are nothing more then little programs, several tasks will be repeated, setting up the test environment, create your class, call a method, verify it's result, write out an error message when the test fails, preferably specifying what the wrong outcome was, and what the expected result is.
All these repetitive chores are taken care of by the frame work so the developer can focus on the real code of the test.
This document will use a small but very effective framework for the C++ language. It is called UnitTest++. It's homepage is at : [http://unittest-cpp.sourceforge.net/ UnitTest++].
You can download it directly at this [http://sourceforge.net/projects/unittest-cpp/files/UnitTest%2B%2B/1.4/unittest-cpp-1.4.zip/download link]. At the time of writing the latest version is 1.4.

== Setup our environment ==
Let's create a directory on our PC in which we will cary out our experiments. I will refer to this directory from now on as <TestPit>. For my laptop on which I am writing this article, that will be /home/lieven/Projects/UnitTestArticle. Note that everything we will do, works on linux and on windows!
Download the "unittest-cpp-1.4.zip" file from the link specified above. Extract it in the <TestPit> directory. All the files will end up in the <TestPit>/UnitTest++ directory.

== Build UnitTest++ ==
After the extracted the zip archive we have a directory structure like this :
<TestPit>/UnitTest++
|
+docs
|
+src

The files in the UnitTest++ directory are of little use for us, since they bring project files for some bizarre Microsoft IDE ;-) .
We will create our own Code::Blocks project to build the UnitTest++ framework.

Why do we need to build something ? Well as said, the framework will do a lot of chores for us, those chores are implemented by code, that code is framework. We will build to frame work into a static library, and for every unit test (or set of unit tests) we create a little (console/shell) program with the test code we wrote, which will link with the static library to obtain a unit test executable, driven by the framework.

We will put our Code::Blocks project file in a nice structured directory tree, therefor let's create a 'Project' subdirectory in the <TestPit>/UniTest++ directory.

In there create a new file with the name "UnitTest++.cbp".
Give that file the following content :

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="UnitTest++" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option platforms="Windows;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option platforms="Windows;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
<Target title="Debug(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<VirtualTargets>
<Add alias="All" targets="Debug;Release;Debug(linux);Release(linux);" />
</VirtualTargets>
<Unit filename="../src/AssertException.cpp" />
<Unit filename="../src/AssertException.h" />
<Unit filename="../src/CheckMacros.h" />
<Unit filename="../src/Checks.cpp" />
<Unit filename="../src/Checks.h" />
<Unit filename="../src/Config.h" />
<Unit filename="../src/CurrentTest.cpp" />
<Unit filename="../src/CurrentTest.h" />
<Unit filename="../src/DeferredTestReporter.cpp" />
<Unit filename="../src/DeferredTestReporter.h" />
<Unit filename="../src/DeferredTestResult.cpp" />
<Unit filename="../src/DeferredTestResult.h" />
<Unit filename="../src/ExecuteTest.h" />
<Unit filename="../src/MemoryOutStream.cpp" />
<Unit filename="../src/MemoryOutStream.h" />
<Unit filename="../src/Posix/SignalTranslator.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/SignalTranslator.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/ReportAssert.cpp" />
<Unit filename="../src/ReportAssert.h" />
<Unit filename="../src/Test.cpp" />
<Unit filename="../src/Test.h" />
<Unit filename="../src/TestDetails.cpp" />
<Unit filename="../src/TestDetails.h" />
<Unit filename="../src/TestList.cpp" />
<Unit filename="../src/TestList.h" />
<Unit filename="../src/TestMacros.h" />
<Unit filename="../src/TestReporter.cpp" />
<Unit filename="../src/TestReporter.h" />
<Unit filename="../src/TestReporterStdout.cpp" />
<Unit filename="../src/TestReporterStdout.h" />
<Unit filename="../src/TestResults.cpp" />
<Unit filename="../src/TestResults.h" />
<Unit filename="../src/TestRunner.cpp" />
<Unit filename="../src/TestRunner.h" />
<Unit filename="../src/TestSuite.h" />
<Unit filename="../src/TimeConstraint.cpp" />
<Unit filename="../src/TimeConstraint.h" />
<Unit filename="../src/TimeHelpers.h" />
<Unit filename="../src/UnitTest++.h" />
<Unit filename="../src/Win32/TimeHelpers.cpp">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/Win32/TimeHelpers.h">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/XmlTestReporter.cpp" />
<Unit filename="../src/XmlTestReporter.h" />
<Extensions>
<envvars />
<code_completion />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

Some things to note about the content of the project file, the power of Code::Blocks.
* there are 4 targets : Debug/Release for Windows and Debug/Release for linux [yes : 1 project file that allows building on linux and on windows]
* some files are only part of the linux targets, some only for the windows targets

But before we build, let's modify some source files (not really needed, but I prefer to have warning free compilations). These are the changes I carried out :
* ReportAssert.cpp : #include "ReportAssert.h"
* win32/TimeHelpers.cpp : first the m_threadHandle and then the m_startTime in the initializerlist

Next open up this project file in Code::Blocks and build the debug and release target. From now one we will only use the Release target, we go for speed ;-)

The result of the build process will show up in subdirectories of the new 'Deliv' subdirectory of <testPit>/UnitTest++ : '''<testPit>/UnitTest++/Deliv/Release/libUnitTest++.a'''

Alright, we have build the unit test framework in a platform independent way, no silly makefiles, no obscure M$ IDE, good old super Code::Blocks. It is time to write some code so we have something to unit test.

In the first example we will create a simple free function that checks if a a give year is a leap your or not.

The business logic is as follows : a year is a leap year when it can be divided by 4, unless itcan be divided by 100. But in case it can be divided by 400, then again it is a leap year.

In the next section we will first setup a Code::Blocks project containing both the 'functionality files, and the unit test files. Typically one will package several functionality files into a static library and create a unit test project that tests all the class/functionalities in that library package, also called a component. That is we have a component (whose deliverable is the static library, and we have a unit test project that tests the entire component).

== Our first test project environment ==
Let's create a new directory in our <TestPit> : <TestPit>/LeapYear.
For the simplicity we will put the project file and the source file all together in this directory. Normally we would work in a more structured way, but in a demo article we have some artistic freedom ;-)
Next you can create with the Code::Block's wizard a new console project in the LeapYear directory. Or you can create the following 4 files and give the the contents as specified below. Note that this demo works on linux and on windows, everything is still completely platform independent. Long Live Code::Blocks.

The project file : LeapYear.cbp (the one below already contains the 3 source files, in case you use the wizard you have to add the LeapYear.h/cpp files to the project)

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="LeapYear" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option output="Deliv/Debug/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Debug/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option output="Deliv/Release/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Release/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-O2" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<Compiler>
<Add option="-Wall" />
<Add option="-fexceptions" />
</Compiler>
<Unit filename="LeapYear.cpp" />
<Unit filename="LeapYear.h" />
<Unit filename="main.cpp" />
<Extensions>
<envvars />
<code_completion />
<lib_finder disable_auto="1" />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

The main source file : main.cpp
int main()
{
return 0;
}

The header exporting our powerful function : LeapYear.h

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

#endif // LEAPYEAR_H_INCLUDED

And the implementation of the leap year logic : LeapYear.cpp

#include "LeapYear.h"

And finishing with the source file for the tests : LeapYearTest.cpp (currently) empty

We can already build the project, we have a nice little program that does .... nothing.

Time to move to the next section, a little word about Test Driven Development.

== Test Driven Development ==
This is a practice where new code is only added to make a failing test pass. And one only adds the code needed to make that test pass. Once that is done, a new test is added to will check the next functionality to add.
On this really simple example we will more or less practice some TDD.

So get ready, it's time for LeapYear-Step1.

== LeapYear-Step1 ==
We will turn our main.cpp into the guy in charge to carry out the tests, all we need to do is change the contents of main.cpp into this :

#include "UnitTest++.h"

int main()
{
return UnitTest::RunAllTests();
}

And add '''../UnitTest++/src''' to the compiler search directories on the project level of our LeapYear project.
And add '''../UnitTest++/Deliv/Release/libUnitTest++.a''' to the link libraries of the project

Why : well we need to link with the framework and we need to include the UnitTest++ header so we can use it's functionalities.

The line '''UnitTest::RunAllTests()''' will make sure all test encountered in our sources will be carried out.
We don't have any tests yet, nor any functionality, but go ahead build the project and run it.
This is the output :

Success: 0 tests passed
Test time: 0.00 seconds.

Great : success, but no tests yet. Well it's a start.
Time to move forward, and write our first test.

== LeapYear-Step2 ==
Test, test, but there's nothing to test. Yes, absolutely. Let's think of a test, a test that will help us in the design. Now that's a good idea. Suppose I would be the user of the uplifting problem solving leap year checking library/component ... hmmm modesty first : leap year checking '''function'''.
How would I like that function to look.
bool IsLeapYear(int Year);

Yes that seems acceptable.
So let's write a test that will call that method.
We do that by adding the following code to LeapYearTest.cpp

#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

}

Things to note :
* we include the unit test header
* it is good to put the tests in nameless namespace (will be explained later on)
* we use the TEST macro, the argument is the name of the test : OurFirstTest
* we use CHECK_EQUAL to check if the expected result (the first argument) matches the computed result (the second argument)

Time to build. Woooooops errors. The tests fails completely, it does not even build. Time to add the code needed.
In order to compiler the test file, we need to include the LeapYear.h header and have that header export our function.
Our LeapYear header will look like this now (don't forget the include in the test file, it is not shown here) :

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

bool IsLeapYear(int Year);

#endif // LEAPYEAR_H_INCLUDED

At least now it compiles, but it doesn't link yet. Duh, that because we don't have an implementation yet.
Time to provide the bare minimum of code to make the test pass.
So we change the LeapYear.cpp into :

#include "LeapYear.h"

bool IsLeapYear(int /*Year*/)
{
return true;
}

Build it, run it. Yes, we have one test passed.
Great. Let's move on.

== LeapYear-Step3 ==
Anyone having the feeling we are cheating. Well the user does not know how we wrote our code on the inside. So just to be sure the user (we) adds the following test, ending up in :

<source lang="cpp">
#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

TEST(OurSecondTest)
{
const bool Result = IsLeapYear(1973);
CHECK_EQUAL(false, Result);
}

}

</source>
Building is already no issue any more, we can run it. Oh boy, a test is failing.
The framework tell us something like this :
<filename>:<Line>: error: Failure in OurSecondTest: Expected 0 but was 1
FAILURE: 1 out of 2 tests failed (1 failures)
Test time: 0.00 seconds.

So we are informed of the line where the failing tests occurs, next to that it tells us what it was expecting and what the actual outcome was. And it presents a resume of the total number of tests, and how many that failed. For you scripting hackers note that FAILURE != SUCCESS.

It seems we should do some more effort and implement some real logic.

== LeapYear-Step4 ==
Let's keep it taking one step at a time. Let's start by implementing the 'divisible by 4' logic. That will already solve our tests.
So our LeapYear.cpp will now look like this :

<source lang="cpp">
#include "LeapYear.h"

namespace
{

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year);
}

</source>
Build, run. All tests pass. Life is great.

But those changing requirements, always the change of the requirements. Years that can be divided by 100 should not be considered as a leap year.

Time for our next step.

== LeapYear-Step5 ==
We add a new test for checking for example the year 1900.

<source lang="cpp">
TEST(DivisableBy100)
{
const bool Result = IsLeapYear(1900);
CHECK_EQUAL(false, Result);
}
</source>

Build and run the tests. It will fail. So time to add the minimum code needed to make this test pass.
This will change our LeapYear.cpp into :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year) && !IsDivisableBy100(Year);
}
</source>

Build and run the tests, yes : success. All 3 tests pass.

It seems life might be great again ...

Wrong, someone just added the following test :

<source lang="cpp">
TEST(DivisableBy400)
{
const bool Result = IsLeapYear(2000);
CHECK_EQUAL(true, Result);
}
</source>

And we once again have a failing test.

Time for the next step.

== LeapYear-Step6 ==
We should add logic to deal with years that can be divided by 400, since those are leap years.
We change our LeapYear.cpp into this :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy400(int Year)
{
return (Year%400) == 0;
}

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
const bool LeapYear = IsDivisableBy400(Year) ||
(IsDivisableBy4(Year) && !IsDivisableBy100(Year));
return LeapYear;
}

</source>

And once again everything works OK.
And it seems all the logical rules have been implemented.
This one is ready for shipping, and till the end of time we have our tests that can be run whenever we want (more on this later, we'd prefer this to be done automatically) to ensure we never break anything.

UnitTesting

2009-09-09T10:24:57Z

Killerbot: /* LeapYear-Step6 */

This document is under development by killerbot. Starting from 7 September 2009.

== Introduction ==
This document will describe how unit testing can be combined with the Code::Blocks IDE. It will give a hands-on example on a unit testing framework and how it can be used with Code::Blocks.

== What is Unit Testing ==
Simply put Unit Testing is the discipline and best practice of writing and running little test programs that test little units of code.
Such a unit can be :
* a class
* a free function
* an interface
* ...
There are several unit test frameworks available to help you write, deploy, manage your unit tests. The most famous family is the xUnit framework, and some of it's descendants.

== Why Unit Testing ==
Well we write code that implements some functionality. We need a way to check and prove that the implementation is correct. Therefor we need tests. We need tests on the application level, at the integration level of different components, classes, interfaces. But we also need tests for the smallest building blocks, the units.
We also wans these tests to run very quickly. That we we can run the tests often, manually or automated.
These tests will also be our safeguards during refactoring of the code, extending the code or whatever maintenance tasks we carry out on the code.
These tests will also make us think of how our class, method, ... will be used. Since the test can be seen as a user of our code. Thanks do this, thinking about the tests before implementing the functionality can help us in the design : emergent design.
It will help us to avoid creating big classes, complex functions. We will only write the methods that are really needed, and no methods that we think might (n)ever be useful in the future. We are no good future tellers ! Those 'might be needed' methods and their tests are just a waste of time. Extending, refactoring will be done when it is actually needed, and at that time we have our unit tests to ensure we don't break any existing code.

Other times to add new unit tests are typically when a bug is discovered; Write a unit test to reproduces the bug, fix the code, and from now on the new unit test will watch your back so the bug won't reappear.

Unit test are also a good place of documentation. The little tests show how the class or method is used.
The code documents itself.

So the benefits are :
* better design
* prove of your code
* safe guard during code maintenance (refactoring, extensions)
* documentation
* ...

== Unit Test frameworks ==
When writing unit tests, one will create a lot of similar code. Since unit tests are nothing more then little programs, several tasks will be repeated, setting up the test environment, create your class, call a method, verify it's result, write out an error message when the test fails, preferably specifying what the wrong outcome was, and what the expected result is.
All these repetitive chores are taken care of by the frame work so the developer can focus on the real code of the test.
This document will use a small but very effective framework for the C++ language. It is called UnitTest++. It's homepage is at : [http://unittest-cpp.sourceforge.net/ UnitTest++].
You can download it directly at this [http://sourceforge.net/projects/unittest-cpp/files/UnitTest%2B%2B/1.4/unittest-cpp-1.4.zip/download link]. At the time of writing the latest version is 1.4.

== Setup our environment ==
Let's create a directory on our PC in which we will cary out our experiments. I will refer to this directory from now on as <TestPit>. For my laptop on which I am writing this article, that will be /home/lieven/Projects/UnitTestArticle. Note that everything we will do, works on linux and on windows!
Download the "unittest-cpp-1.4.zip" file from the link specified above. Extract it in the <TestPit> directory. All the files will end up in the <TestPit>/UnitTest++ directory.

== Build UnitTest++ ==
After the extracted the zip archive we have a directory structure like this :
<TestPit>/UnitTest++
|
+docs
|
+src

The files in the UnitTest++ directory are of little use for us, since they bring project files for some bizarre Microsoft IDE ;-) .
We will create our own Code::Blocks project to build the UnitTest++ framework.

Why do we need to build something ? Well as said, the framework will do a lot of chores for us, those chores are implemented by code, that code is framework. We will build to frame work into a static library, and for every unit test (or set of unit tests) we create a little (console/shell) program with the test code we wrote, which will link with the static library to obtain a unit test executable, driven by the framework.

We will put our Code::Blocks project file in a nice structured directory tree, therefor let's create a 'Project' subdirectory in the <TestPit>/UniTest++ directory.

In there create a new file with the name "UnitTest++.cbp".
Give that file the following content :

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="UnitTest++" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option platforms="Windows;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option platforms="Windows;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
<Target title="Debug(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<VirtualTargets>
<Add alias="All" targets="Debug;Release;Debug(linux);Release(linux);" />
</VirtualTargets>
<Unit filename="../src/AssertException.cpp" />
<Unit filename="../src/AssertException.h" />
<Unit filename="../src/CheckMacros.h" />
<Unit filename="../src/Checks.cpp" />
<Unit filename="../src/Checks.h" />
<Unit filename="../src/Config.h" />
<Unit filename="../src/CurrentTest.cpp" />
<Unit filename="../src/CurrentTest.h" />
<Unit filename="../src/DeferredTestReporter.cpp" />
<Unit filename="../src/DeferredTestReporter.h" />
<Unit filename="../src/DeferredTestResult.cpp" />
<Unit filename="../src/DeferredTestResult.h" />
<Unit filename="../src/ExecuteTest.h" />
<Unit filename="../src/MemoryOutStream.cpp" />
<Unit filename="../src/MemoryOutStream.h" />
<Unit filename="../src/Posix/SignalTranslator.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/SignalTranslator.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/ReportAssert.cpp" />
<Unit filename="../src/ReportAssert.h" />
<Unit filename="../src/Test.cpp" />
<Unit filename="../src/Test.h" />
<Unit filename="../src/TestDetails.cpp" />
<Unit filename="../src/TestDetails.h" />
<Unit filename="../src/TestList.cpp" />
<Unit filename="../src/TestList.h" />
<Unit filename="../src/TestMacros.h" />
<Unit filename="../src/TestReporter.cpp" />
<Unit filename="../src/TestReporter.h" />
<Unit filename="../src/TestReporterStdout.cpp" />
<Unit filename="../src/TestReporterStdout.h" />
<Unit filename="../src/TestResults.cpp" />
<Unit filename="../src/TestResults.h" />
<Unit filename="../src/TestRunner.cpp" />
<Unit filename="../src/TestRunner.h" />
<Unit filename="../src/TestSuite.h" />
<Unit filename="../src/TimeConstraint.cpp" />
<Unit filename="../src/TimeConstraint.h" />
<Unit filename="../src/TimeHelpers.h" />
<Unit filename="../src/UnitTest++.h" />
<Unit filename="../src/Win32/TimeHelpers.cpp">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/Win32/TimeHelpers.h">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/XmlTestReporter.cpp" />
<Unit filename="../src/XmlTestReporter.h" />
<Extensions>
<envvars />
<code_completion />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

Some things to note about the content of the project file, the power of Code::Blocks.
* there are 4 targets : Debug/Release for Windows and Debug/Release for linux [yes : 1 project file that allows building on linux and on windows]
* some files are only part of the linux targets, some only for the windows targets

But before we build, let's modify some source files (not really needed, but I prefer to have warning free compilations). These are the changes I carried out :
* ReportAssert.cpp : #include "ReportAssert.h"
* win32/TimeHelpers.cpp : first the m_threadHandle and then the m_startTime in the initializerlist

Next open up this project file in Code::Blocks and build the debug and release target. From now one we will only use the Release target, we go for speed ;-)

The result of the build process will show up in subdirectories of the new 'Deliv' subdirectory of <testPit>/UnitTest++ : '''<testPit>/UnitTest++/Deliv/Release/libUnitTest++.a'''

Alright, we have build the unit test framework in a platform independent way, no silly makefiles, no obscure M$ IDE, good old super Code::Blocks. It is time to write some code so we have something to unit test.

In the first example we will create a simple free function that checks if a a give year is a leap your or not.

The business logic is as follows : a year is a leap year when it can be divided by 4, unless itcan be divided by 100. But in case it can be divided by 400, then again it is a leap year.

In the next section we will first setup a Code::Blocks project containing both the 'functionality files, and the unit test files. Typically one will package several functionality files into a static library and create a unit test project that tests all the class/functionalities in that library package, also called a component. That is we have a component (whose deliverable is the static library, and we have a unit test project that tests the entire component).

== Our first test project environment ==
Let's create a new directory in our <TestPit> : <TestPit>/LeapYear.
For the simplicity we will put the project file and the source file all together in this directory. Normally we would work in a more structured way, but in a demo article we have some artistic freedom ;-)
Next you can create with the Code::Block's wizard a new console project in the LeapYear directory. Or you can create the following 4 files and give the the contents as specified below. Note that this demo works on linux and on windows, everything is still completely platform independent. Long Live Code::Blocks.

The project file : LeapYear.cbp (the one below already contains the 3 source files, in case you use the wizard you have to add the LeapYear.h/cpp files to the project)

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="LeapYear" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option output="Deliv/Debug/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Debug/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option output="Deliv/Release/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Release/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-O2" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<Compiler>
<Add option="-Wall" />
<Add option="-fexceptions" />
</Compiler>
<Unit filename="LeapYear.cpp" />
<Unit filename="LeapYear.h" />
<Unit filename="main.cpp" />
<Extensions>
<envvars />
<code_completion />
<lib_finder disable_auto="1" />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

The main source file : main.cpp
int main()
{
return 0;
}

The header exporting our powerful function : LeapYear.h

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

#endif // LEAPYEAR_H_INCLUDED

And the implementation of the leap year logic : LeapYear.cpp

#include "LeapYear.h"

And finishing with the source file for the tests : LeapYearTest.cpp (currently) empty

We can already build the project, we have a nice little program that does .... nothing.

Time to move to the next section, a little word about Test Driven Development.

== Test Driven Development ==
This is a practice where new code is only added to make a failing test pass. And one only adds the code needed to make that test pass. Once that is done, a new test is added to will check the next functionality to add.
On this really simple example we will more or less practice some TDD.

So get ready, it's time for LeapYear-Step1.

== LeapYear-Step1 ==
We will turn our main.cpp into the guy in charge to carry out the tests, all we need to do is change the contents of main.cpp into this :

#include "UnitTest++.h"

int main()
{
return UnitTest::RunAllTests();
}

And add '''../UnitTest++/src''' to the compiler search directories on the project level of our LeapYear project.
And add '''../UnitTest++/Deliv/Release/libUnitTest++.a''' to the link libraries of the project

Why : well we need to link with the framework and we need to include the UnitTest++ header so we can use it's functionalities.

The line '''UnitTest::RunAllTests()''' will make sure all test encountered in our sources will be carried out.
We don't have any tests yet, nor any functionality, but go ahead build the project and run it.
This is the output :

Success: 0 tests passed
Test time: 0.00 seconds.

Great : success, but no tests yet. Well it's a start.
Time to move forward, and write our first test.

== LeapYear-Step2 ==
Test, test, but there's nothing to test. Yes, absolutely. Let's think of a test, a test that will help us in the design. Now that's a good idea. Suppose I would be the user of the uplifting problem solving leap year checking library/component ... hmmm modesty first : leap year checking '''function'''.
How would I like that function to look.
bool IsLeapYear(int Year);

Yes that seems acceptable.
So let's write a test that will call that method.
We do that by adding the following code to LeapYearTest.cpp

#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

}

Things to note :
* we include the unit test header
* it is good to put the tests in nameless namespace (will be explained later on)
* we use the TEST macro, the argument is the name of the test : OurFirstTest
* we use CHECK_EQUAL to check if the expected result (the first argument) matches the computed result (the second argument)

Time to build. Woooooops errors. The tests fails completely, it does not even build. Time to add the code needed.
In order to compiler the test file, we need to include the LeapYear.h header and have that header export our function.
Our LeapYear header will look like this now (don't forget the include in the test file, it is not shown here) :

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

bool IsLeapYear(int Year);

#endif // LEAPYEAR_H_INCLUDED

At least now it compiles, but it doesn't link yet. Duh, that because we don't have an implementation yet.
Time to provide the bare minimum of code to make the test pass.
So we change the LeapYear.cpp into :

#include "LeapYear.h"

bool IsLeapYear(int /*Year*/)
{
return true;
}

Build it, run it. Yes, we have one test passed.
Great. Let's move on.

== LeapYear-Step3 ==
Anyone having the feeling we are cheating. Well the user does not know how we wrote our code on the inside. So just to be sure the user (we) adds the following test, ending up in :

#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

TEST(OurSecondTest)
{
const bool Result = IsLeapYear(1973);
CHECK_EQUAL(false, Result);
}

}

Building is already no issue any more, we can run it. Oh boy, a test is failing.
The framework tell us something like this :
<filename>:<Line>: error: Failure in OurSecondTest: Expected 0 but was 1
FAILURE: 1 out of 2 tests failed (1 failures)
Test time: 0.00 seconds.

So we are informed of the line where the failing tests occurs, next to that it tells us what it was expecting and what the actual outcome was. And it presents a resume of the total number of tests, and how many that failed. For you scripting hackers note that FAILURE != SUCCESS.

It seems we should do some more effort and implement some real logic.

== LeapYear-Step4 ==
Let's keep it taking one step at a time. Let's start by implementing the 'divisible by 4' logic. That will already solve our tests.
So our LeapYear.cpp will now look like this :

<source lang="cpp">
#include "LeapYear.h"

namespace
{

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year);
}

</source>
Build, run. All tests pass. Life is great.

But those changing requirements, always the change of the requirements. Years that can be divided by 100 should not be considered as a leap year.

Time for our next step.

== LeapYear-Step5 ==
We add a new test for checking for example the year 1900.

<source lang="cpp">
TEST(DivisableBy100)
{
const bool Result = IsLeapYear(1900);
CHECK_EQUAL(false, Result);
}
</source>

Build and run the tests. It will fail. So time to add the minimum code needed to make this test pass.
This will change our LeapYear.cpp into :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year) && !IsDivisableBy100(Year);
}
</source>

Build and run the tests, yes : success. All 3 tests pass.

It seems life might be great again ...

Wrong, someone just added the following test :

<source lang="cpp">
TEST(DivisableBy400)
{
const bool Result = IsLeapYear(2000);
CHECK_EQUAL(true, Result);
}
</source>

And we once again have a failing test.

Time for the next step.

== LeapYear-Step6 ==
We should add logic to deal with years that can be divided by 400, since those are leap years.
We change our LeapYear.cpp into this :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy400(int Year)
{
return (Year%400) == 0;
}

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
const bool LeapYear = IsDivisableBy400(Year) ||
(IsDivisableBy4(Year) && !IsDivisableBy100(Year));
return LeapYear;
}

</source>

And once again everything works OK.
And it seems all the logical rules have been implemented.
This one is ready for shipping, and till the end of time we have our tests that can be run whenever we want (more on this later, we'd prefer this to be done automatically) to ensure we never break anything.

UnitTesting

2009-09-09T10:23:32Z

Killerbot: /* LeapYear-Step6 */

This document is under development by killerbot. Starting from 7 September 2009.

== Introduction ==
This document will describe how unit testing can be combined with the Code::Blocks IDE. It will give a hands-on example on a unit testing framework and how it can be used with Code::Blocks.

== What is Unit Testing ==
Simply put Unit Testing is the discipline and best practice of writing and running little test programs that test little units of code.
Such a unit can be :
* a class
* a free function
* an interface
* ...
There are several unit test frameworks available to help you write, deploy, manage your unit tests. The most famous family is the xUnit framework, and some of it's descendants.

== Why Unit Testing ==
Well we write code that implements some functionality. We need a way to check and prove that the implementation is correct. Therefor we need tests. We need tests on the application level, at the integration level of different components, classes, interfaces. But we also need tests for the smallest building blocks, the units.
We also wans these tests to run very quickly. That we we can run the tests often, manually or automated.
These tests will also be our safeguards during refactoring of the code, extending the code or whatever maintenance tasks we carry out on the code.
These tests will also make us think of how our class, method, ... will be used. Since the test can be seen as a user of our code. Thanks do this, thinking about the tests before implementing the functionality can help us in the design : emergent design.
It will help us to avoid creating big classes, complex functions. We will only write the methods that are really needed, and no methods that we think might (n)ever be useful in the future. We are no good future tellers ! Those 'might be needed' methods and their tests are just a waste of time. Extending, refactoring will be done when it is actually needed, and at that time we have our unit tests to ensure we don't break any existing code.

Other times to add new unit tests are typically when a bug is discovered; Write a unit test to reproduces the bug, fix the code, and from now on the new unit test will watch your back so the bug won't reappear.

Unit test are also a good place of documentation. The little tests show how the class or method is used.
The code documents itself.

So the benefits are :
* better design
* prove of your code
* safe guard during code maintenance (refactoring, extensions)
* documentation
* ...

== Unit Test frameworks ==
When writing unit tests, one will create a lot of similar code. Since unit tests are nothing more then little programs, several tasks will be repeated, setting up the test environment, create your class, call a method, verify it's result, write out an error message when the test fails, preferably specifying what the wrong outcome was, and what the expected result is.
All these repetitive chores are taken care of by the frame work so the developer can focus on the real code of the test.
This document will use a small but very effective framework for the C++ language. It is called UnitTest++. It's homepage is at : [http://unittest-cpp.sourceforge.net/ UnitTest++].
You can download it directly at this [http://sourceforge.net/projects/unittest-cpp/files/UnitTest%2B%2B/1.4/unittest-cpp-1.4.zip/download link]. At the time of writing the latest version is 1.4.

== Setup our environment ==
Let's create a directory on our PC in which we will cary out our experiments. I will refer to this directory from now on as <TestPit>. For my laptop on which I am writing this article, that will be /home/lieven/Projects/UnitTestArticle. Note that everything we will do, works on linux and on windows!
Download the "unittest-cpp-1.4.zip" file from the link specified above. Extract it in the <TestPit> directory. All the files will end up in the <TestPit>/UnitTest++ directory.

== Build UnitTest++ ==
After the extracted the zip archive we have a directory structure like this :
<TestPit>/UnitTest++
|
+docs
|
+src

The files in the UnitTest++ directory are of little use for us, since they bring project files for some bizarre Microsoft IDE ;-) .
We will create our own Code::Blocks project to build the UnitTest++ framework.

Why do we need to build something ? Well as said, the framework will do a lot of chores for us, those chores are implemented by code, that code is framework. We will build to frame work into a static library, and for every unit test (or set of unit tests) we create a little (console/shell) program with the test code we wrote, which will link with the static library to obtain a unit test executable, driven by the framework.

We will put our Code::Blocks project file in a nice structured directory tree, therefor let's create a 'Project' subdirectory in the <TestPit>/UniTest++ directory.

In there create a new file with the name "UnitTest++.cbp".
Give that file the following content :

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="UnitTest++" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option platforms="Windows;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option platforms="Windows;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
<Target title="Debug(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<VirtualTargets>
<Add alias="All" targets="Debug;Release;Debug(linux);Release(linux);" />
</VirtualTargets>
<Unit filename="../src/AssertException.cpp" />
<Unit filename="../src/AssertException.h" />
<Unit filename="../src/CheckMacros.h" />
<Unit filename="../src/Checks.cpp" />
<Unit filename="../src/Checks.h" />
<Unit filename="../src/Config.h" />
<Unit filename="../src/CurrentTest.cpp" />
<Unit filename="../src/CurrentTest.h" />
<Unit filename="../src/DeferredTestReporter.cpp" />
<Unit filename="../src/DeferredTestReporter.h" />
<Unit filename="../src/DeferredTestResult.cpp" />
<Unit filename="../src/DeferredTestResult.h" />
<Unit filename="../src/ExecuteTest.h" />
<Unit filename="../src/MemoryOutStream.cpp" />
<Unit filename="../src/MemoryOutStream.h" />
<Unit filename="../src/Posix/SignalTranslator.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/SignalTranslator.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/ReportAssert.cpp" />
<Unit filename="../src/ReportAssert.h" />
<Unit filename="../src/Test.cpp" />
<Unit filename="../src/Test.h" />
<Unit filename="../src/TestDetails.cpp" />
<Unit filename="../src/TestDetails.h" />
<Unit filename="../src/TestList.cpp" />
<Unit filename="../src/TestList.h" />
<Unit filename="../src/TestMacros.h" />
<Unit filename="../src/TestReporter.cpp" />
<Unit filename="../src/TestReporter.h" />
<Unit filename="../src/TestReporterStdout.cpp" />
<Unit filename="../src/TestReporterStdout.h" />
<Unit filename="../src/TestResults.cpp" />
<Unit filename="../src/TestResults.h" />
<Unit filename="../src/TestRunner.cpp" />
<Unit filename="../src/TestRunner.h" />
<Unit filename="../src/TestSuite.h" />
<Unit filename="../src/TimeConstraint.cpp" />
<Unit filename="../src/TimeConstraint.h" />
<Unit filename="../src/TimeHelpers.h" />
<Unit filename="../src/UnitTest++.h" />
<Unit filename="../src/Win32/TimeHelpers.cpp">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/Win32/TimeHelpers.h">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/XmlTestReporter.cpp" />
<Unit filename="../src/XmlTestReporter.h" />
<Extensions>
<envvars />
<code_completion />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

Some things to note about the content of the project file, the power of Code::Blocks.
* there are 4 targets : Debug/Release for Windows and Debug/Release for linux [yes : 1 project file that allows building on linux and on windows]
* some files are only part of the linux targets, some only for the windows targets

But before we build, let's modify some source files (not really needed, but I prefer to have warning free compilations). These are the changes I carried out :
* ReportAssert.cpp : #include "ReportAssert.h"
* win32/TimeHelpers.cpp : first the m_threadHandle and then the m_startTime in the initializerlist

Next open up this project file in Code::Blocks and build the debug and release target. From now one we will only use the Release target, we go for speed ;-)

The result of the build process will show up in subdirectories of the new 'Deliv' subdirectory of <testPit>/UnitTest++ : '''<testPit>/UnitTest++/Deliv/Release/libUnitTest++.a'''

Alright, we have build the unit test framework in a platform independent way, no silly makefiles, no obscure M$ IDE, good old super Code::Blocks. It is time to write some code so we have something to unit test.

In the first example we will create a simple free function that checks if a a give year is a leap your or not.

The business logic is as follows : a year is a leap year when it can be divided by 4, unless itcan be divided by 100. But in case it can be divided by 400, then again it is a leap year.

In the next section we will first setup a Code::Blocks project containing both the 'functionality files, and the unit test files. Typically one will package several functionality files into a static library and create a unit test project that tests all the class/functionalities in that library package, also called a component. That is we have a component (whose deliverable is the static library, and we have a unit test project that tests the entire component).

== Our first test project environment ==
Let's create a new directory in our <TestPit> : <TestPit>/LeapYear.
For the simplicity we will put the project file and the source file all together in this directory. Normally we would work in a more structured way, but in a demo article we have some artistic freedom ;-)
Next you can create with the Code::Block's wizard a new console project in the LeapYear directory. Or you can create the following 4 files and give the the contents as specified below. Note that this demo works on linux and on windows, everything is still completely platform independent. Long Live Code::Blocks.

The project file : LeapYear.cbp (the one below already contains the 3 source files, in case you use the wizard you have to add the LeapYear.h/cpp files to the project)

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="LeapYear" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option output="Deliv/Debug/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Debug/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option output="Deliv/Release/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Release/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-O2" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<Compiler>
<Add option="-Wall" />
<Add option="-fexceptions" />
</Compiler>
<Unit filename="LeapYear.cpp" />
<Unit filename="LeapYear.h" />
<Unit filename="main.cpp" />
<Extensions>
<envvars />
<code_completion />
<lib_finder disable_auto="1" />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

The main source file : main.cpp
int main()
{
return 0;
}

The header exporting our powerful function : LeapYear.h

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

#endif // LEAPYEAR_H_INCLUDED

And the implementation of the leap year logic : LeapYear.cpp

#include "LeapYear.h"

And finishing with the source file for the tests : LeapYearTest.cpp (currently) empty

We can already build the project, we have a nice little program that does .... nothing.

Time to move to the next section, a little word about Test Driven Development.

== Test Driven Development ==
This is a practice where new code is only added to make a failing test pass. And one only adds the code needed to make that test pass. Once that is done, a new test is added to will check the next functionality to add.
On this really simple example we will more or less practice some TDD.

So get ready, it's time for LeapYear-Step1.

== LeapYear-Step1 ==
We will turn our main.cpp into the guy in charge to carry out the tests, all we need to do is change the contents of main.cpp into this :

#include "UnitTest++.h"

int main()
{
return UnitTest::RunAllTests();
}

And add '''../UnitTest++/src''' to the compiler search directories on the project level of our LeapYear project.
And add '''../UnitTest++/Deliv/Release/libUnitTest++.a''' to the link libraries of the project

Why : well we need to link with the framework and we need to include the UnitTest++ header so we can use it's functionalities.

The line '''UnitTest::RunAllTests()''' will make sure all test encountered in our sources will be carried out.
We don't have any tests yet, nor any functionality, but go ahead build the project and run it.
This is the output :

Success: 0 tests passed
Test time: 0.00 seconds.

Great : success, but no tests yet. Well it's a start.
Time to move forward, and write our first test.

== LeapYear-Step2 ==
Test, test, but there's nothing to test. Yes, absolutely. Let's think of a test, a test that will help us in the design. Now that's a good idea. Suppose I would be the user of the uplifting problem solving leap year checking library/component ... hmmm modesty first : leap year checking '''function'''.
How would I like that function to look.
bool IsLeapYear(int Year);

Yes that seems acceptable.
So let's write a test that will call that method.
We do that by adding the following code to LeapYearTest.cpp

#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

}

Things to note :
* we include the unit test header
* it is good to put the tests in nameless namespace (will be explained later on)
* we use the TEST macro, the argument is the name of the test : OurFirstTest
* we use CHECK_EQUAL to check if the expected result (the first argument) matches the computed result (the second argument)

Time to build. Woooooops errors. The tests fails completely, it does not even build. Time to add the code needed.
In order to compiler the test file, we need to include the LeapYear.h header and have that header export our function.
Our LeapYear header will look like this now (don't forget the include in the test file, it is not shown here) :

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

bool IsLeapYear(int Year);

#endif // LEAPYEAR_H_INCLUDED

At least now it compiles, but it doesn't link yet. Duh, that because we don't have an implementation yet.
Time to provide the bare minimum of code to make the test pass.
So we change the LeapYear.cpp into :

#include "LeapYear.h"

bool IsLeapYear(int /*Year*/)
{
return true;
}

Build it, run it. Yes, we have one test passed.
Great. Let's move on.

== LeapYear-Step3 ==
Anyone having the feeling we are cheating. Well the user does not know how we wrote our code on the inside. So just to be sure the user (we) adds the following test, ending up in :

#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

TEST(OurSecondTest)
{
const bool Result = IsLeapYear(1973);
CHECK_EQUAL(false, Result);
}

}

Building is already no issue any more, we can run it. Oh boy, a test is failing.
The framework tell us something like this :
<filename>:<Line>: error: Failure in OurSecondTest: Expected 0 but was 1
FAILURE: 1 out of 2 tests failed (1 failures)
Test time: 0.00 seconds.

So we are informed of the line where the failing tests occurs, next to that it tells us what it was expecting and what the actual outcome was. And it presents a resume of the total number of tests, and how many that failed. For you scripting hackers note that FAILURE != SUCCESS.

It seems we should do some more effort and implement some real logic.

== LeapYear-Step4 ==
Let's keep it taking one step at a time. Let's start by implementing the 'divisible by 4' logic. That will already solve our tests.
So our LeapYear.cpp will now look like this :

<source lang="cpp">
#include "LeapYear.h"

namespace
{

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year);
}

</source>
Build, run. All tests pass. Life is great.

But those changing requirements, always the change of the requirements. Years that can be divided by 100 should not be considered as a leap year.

Time for our next step.

== LeapYear-Step5 ==
We add a new test for checking for example the year 1900.

<source lang="cpp">
TEST(DivisableBy100)
{
const bool Result = IsLeapYear(1900);
CHECK_EQUAL(false, Result);
}
</source>

Build and run the tests. It will fail. So time to add the minimum code needed to make this test pass.
This will change our LeapYear.cpp into :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year) && !IsDivisableBy100(Year);
}
</source>

Build and run the tests, yes : success. All 3 tests pass.

It seems life might be great again ...

Wrong, someone just added the following test :

<source lang="cpp">
TEST(DivisableBy400)
{
const bool Result = IsLeapYear(2000);
CHECK_EQUAL(true, Result);
}
</source>

And we once again have a failing test.

Time for the next step.

== LeapYear-Step6 ==
We should add logic to deal with years that can be divided by 400, since those are leap years.
We change our LeapYear.cpp into this :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy400(int Year)
{
return (Year%400) == 0;
}

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
const bool LeapYear = IsDivisableBy400(Year) ||
(IsDivisableBy4(Year) && !IsDivisableBy100(Year));
return LeapYear;
}

</source>

And once again everything works OK.
And it seems all the logical rules have been implemented.
This one is ready for shipping, and till the end of time we have our tests that can be run whenever we want (more on this later, we'd prefer this to be done automatically) to ensure we never break anything.

UnitTesting

2009-09-09T10:22:56Z

Killerbot: /* LeapYear-Step5 */

This document is under development by killerbot. Starting from 7 September 2009.

== Introduction ==
This document will describe how unit testing can be combined with the Code::Blocks IDE. It will give a hands-on example on a unit testing framework and how it can be used with Code::Blocks.

== What is Unit Testing ==
Simply put Unit Testing is the discipline and best practice of writing and running little test programs that test little units of code.
Such a unit can be :
* a class
* a free function
* an interface
* ...
There are several unit test frameworks available to help you write, deploy, manage your unit tests. The most famous family is the xUnit framework, and some of it's descendants.

== Why Unit Testing ==
Well we write code that implements some functionality. We need a way to check and prove that the implementation is correct. Therefor we need tests. We need tests on the application level, at the integration level of different components, classes, interfaces. But we also need tests for the smallest building blocks, the units.
We also wans these tests to run very quickly. That we we can run the tests often, manually or automated.
These tests will also be our safeguards during refactoring of the code, extending the code or whatever maintenance tasks we carry out on the code.
These tests will also make us think of how our class, method, ... will be used. Since the test can be seen as a user of our code. Thanks do this, thinking about the tests before implementing the functionality can help us in the design : emergent design.
It will help us to avoid creating big classes, complex functions. We will only write the methods that are really needed, and no methods that we think might (n)ever be useful in the future. We are no good future tellers ! Those 'might be needed' methods and their tests are just a waste of time. Extending, refactoring will be done when it is actually needed, and at that time we have our unit tests to ensure we don't break any existing code.

Other times to add new unit tests are typically when a bug is discovered; Write a unit test to reproduces the bug, fix the code, and from now on the new unit test will watch your back so the bug won't reappear.

Unit test are also a good place of documentation. The little tests show how the class or method is used.
The code documents itself.

So the benefits are :
* better design
* prove of your code
* safe guard during code maintenance (refactoring, extensions)
* documentation
* ...

== Unit Test frameworks ==
When writing unit tests, one will create a lot of similar code. Since unit tests are nothing more then little programs, several tasks will be repeated, setting up the test environment, create your class, call a method, verify it's result, write out an error message when the test fails, preferably specifying what the wrong outcome was, and what the expected result is.
All these repetitive chores are taken care of by the frame work so the developer can focus on the real code of the test.
This document will use a small but very effective framework for the C++ language. It is called UnitTest++. It's homepage is at : [http://unittest-cpp.sourceforge.net/ UnitTest++].
You can download it directly at this [http://sourceforge.net/projects/unittest-cpp/files/UnitTest%2B%2B/1.4/unittest-cpp-1.4.zip/download link]. At the time of writing the latest version is 1.4.

== Setup our environment ==
Let's create a directory on our PC in which we will cary out our experiments. I will refer to this directory from now on as <TestPit>. For my laptop on which I am writing this article, that will be /home/lieven/Projects/UnitTestArticle. Note that everything we will do, works on linux and on windows!
Download the "unittest-cpp-1.4.zip" file from the link specified above. Extract it in the <TestPit> directory. All the files will end up in the <TestPit>/UnitTest++ directory.

== Build UnitTest++ ==
After the extracted the zip archive we have a directory structure like this :
<TestPit>/UnitTest++
|
+docs
|
+src

The files in the UnitTest++ directory are of little use for us, since they bring project files for some bizarre Microsoft IDE ;-) .
We will create our own Code::Blocks project to build the UnitTest++ framework.

Why do we need to build something ? Well as said, the framework will do a lot of chores for us, those chores are implemented by code, that code is framework. We will build to frame work into a static library, and for every unit test (or set of unit tests) we create a little (console/shell) program with the test code we wrote, which will link with the static library to obtain a unit test executable, driven by the framework.

We will put our Code::Blocks project file in a nice structured directory tree, therefor let's create a 'Project' subdirectory in the <TestPit>/UniTest++ directory.

In there create a new file with the name "UnitTest++.cbp".
Give that file the following content :

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="UnitTest++" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option platforms="Windows;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option platforms="Windows;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
<Target title="Debug(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<VirtualTargets>
<Add alias="All" targets="Debug;Release;Debug(linux);Release(linux);" />
</VirtualTargets>
<Unit filename="../src/AssertException.cpp" />
<Unit filename="../src/AssertException.h" />
<Unit filename="../src/CheckMacros.h" />
<Unit filename="../src/Checks.cpp" />
<Unit filename="../src/Checks.h" />
<Unit filename="../src/Config.h" />
<Unit filename="../src/CurrentTest.cpp" />
<Unit filename="../src/CurrentTest.h" />
<Unit filename="../src/DeferredTestReporter.cpp" />
<Unit filename="../src/DeferredTestReporter.h" />
<Unit filename="../src/DeferredTestResult.cpp" />
<Unit filename="../src/DeferredTestResult.h" />
<Unit filename="../src/ExecuteTest.h" />
<Unit filename="../src/MemoryOutStream.cpp" />
<Unit filename="../src/MemoryOutStream.h" />
<Unit filename="../src/Posix/SignalTranslator.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/SignalTranslator.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/ReportAssert.cpp" />
<Unit filename="../src/ReportAssert.h" />
<Unit filename="../src/Test.cpp" />
<Unit filename="../src/Test.h" />
<Unit filename="../src/TestDetails.cpp" />
<Unit filename="../src/TestDetails.h" />
<Unit filename="../src/TestList.cpp" />
<Unit filename="../src/TestList.h" />
<Unit filename="../src/TestMacros.h" />
<Unit filename="../src/TestReporter.cpp" />
<Unit filename="../src/TestReporter.h" />
<Unit filename="../src/TestReporterStdout.cpp" />
<Unit filename="../src/TestReporterStdout.h" />
<Unit filename="../src/TestResults.cpp" />
<Unit filename="../src/TestResults.h" />
<Unit filename="../src/TestRunner.cpp" />
<Unit filename="../src/TestRunner.h" />
<Unit filename="../src/TestSuite.h" />
<Unit filename="../src/TimeConstraint.cpp" />
<Unit filename="../src/TimeConstraint.h" />
<Unit filename="../src/TimeHelpers.h" />
<Unit filename="../src/UnitTest++.h" />
<Unit filename="../src/Win32/TimeHelpers.cpp">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/Win32/TimeHelpers.h">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/XmlTestReporter.cpp" />
<Unit filename="../src/XmlTestReporter.h" />
<Extensions>
<envvars />
<code_completion />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

Some things to note about the content of the project file, the power of Code::Blocks.
* there are 4 targets : Debug/Release for Windows and Debug/Release for linux [yes : 1 project file that allows building on linux and on windows]
* some files are only part of the linux targets, some only for the windows targets

But before we build, let's modify some source files (not really needed, but I prefer to have warning free compilations). These are the changes I carried out :
* ReportAssert.cpp : #include "ReportAssert.h"
* win32/TimeHelpers.cpp : first the m_threadHandle and then the m_startTime in the initializerlist

Next open up this project file in Code::Blocks and build the debug and release target. From now one we will only use the Release target, we go for speed ;-)

The result of the build process will show up in subdirectories of the new 'Deliv' subdirectory of <testPit>/UnitTest++ : '''<testPit>/UnitTest++/Deliv/Release/libUnitTest++.a'''

Alright, we have build the unit test framework in a platform independent way, no silly makefiles, no obscure M$ IDE, good old super Code::Blocks. It is time to write some code so we have something to unit test.

In the first example we will create a simple free function that checks if a a give year is a leap your or not.

The business logic is as follows : a year is a leap year when it can be divided by 4, unless itcan be divided by 100. But in case it can be divided by 400, then again it is a leap year.

In the next section we will first setup a Code::Blocks project containing both the 'functionality files, and the unit test files. Typically one will package several functionality files into a static library and create a unit test project that tests all the class/functionalities in that library package, also called a component. That is we have a component (whose deliverable is the static library, and we have a unit test project that tests the entire component).

== Our first test project environment ==
Let's create a new directory in our <TestPit> : <TestPit>/LeapYear.
For the simplicity we will put the project file and the source file all together in this directory. Normally we would work in a more structured way, but in a demo article we have some artistic freedom ;-)
Next you can create with the Code::Block's wizard a new console project in the LeapYear directory. Or you can create the following 4 files and give the the contents as specified below. Note that this demo works on linux and on windows, everything is still completely platform independent. Long Live Code::Blocks.

The project file : LeapYear.cbp (the one below already contains the 3 source files, in case you use the wizard you have to add the LeapYear.h/cpp files to the project)

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="LeapYear" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option output="Deliv/Debug/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Debug/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option output="Deliv/Release/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Release/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-O2" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<Compiler>
<Add option="-Wall" />
<Add option="-fexceptions" />
</Compiler>
<Unit filename="LeapYear.cpp" />
<Unit filename="LeapYear.h" />
<Unit filename="main.cpp" />
<Extensions>
<envvars />
<code_completion />
<lib_finder disable_auto="1" />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

The main source file : main.cpp
int main()
{
return 0;
}

The header exporting our powerful function : LeapYear.h

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

#endif // LEAPYEAR_H_INCLUDED

And the implementation of the leap year logic : LeapYear.cpp

#include "LeapYear.h"

And finishing with the source file for the tests : LeapYearTest.cpp (currently) empty

We can already build the project, we have a nice little program that does .... nothing.

Time to move to the next section, a little word about Test Driven Development.

== Test Driven Development ==
This is a practice where new code is only added to make a failing test pass. And one only adds the code needed to make that test pass. Once that is done, a new test is added to will check the next functionality to add.
On this really simple example we will more or less practice some TDD.

So get ready, it's time for LeapYear-Step1.

== LeapYear-Step1 ==
We will turn our main.cpp into the guy in charge to carry out the tests, all we need to do is change the contents of main.cpp into this :

#include "UnitTest++.h"

int main()
{
return UnitTest::RunAllTests();
}

And add '''../UnitTest++/src''' to the compiler search directories on the project level of our LeapYear project.
And add '''../UnitTest++/Deliv/Release/libUnitTest++.a''' to the link libraries of the project

Why : well we need to link with the framework and we need to include the UnitTest++ header so we can use it's functionalities.

The line '''UnitTest::RunAllTests()''' will make sure all test encountered in our sources will be carried out.
We don't have any tests yet, nor any functionality, but go ahead build the project and run it.
This is the output :

Success: 0 tests passed
Test time: 0.00 seconds.

Great : success, but no tests yet. Well it's a start.
Time to move forward, and write our first test.

== LeapYear-Step2 ==
Test, test, but there's nothing to test. Yes, absolutely. Let's think of a test, a test that will help us in the design. Now that's a good idea. Suppose I would be the user of the uplifting problem solving leap year checking library/component ... hmmm modesty first : leap year checking '''function'''.
How would I like that function to look.
bool IsLeapYear(int Year);

Yes that seems acceptable.
So let's write a test that will call that method.
We do that by adding the following code to LeapYearTest.cpp

#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

}

Things to note :
* we include the unit test header
* it is good to put the tests in nameless namespace (will be explained later on)
* we use the TEST macro, the argument is the name of the test : OurFirstTest
* we use CHECK_EQUAL to check if the expected result (the first argument) matches the computed result (the second argument)

Time to build. Woooooops errors. The tests fails completely, it does not even build. Time to add the code needed.
In order to compiler the test file, we need to include the LeapYear.h header and have that header export our function.
Our LeapYear header will look like this now (don't forget the include in the test file, it is not shown here) :

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

bool IsLeapYear(int Year);

#endif // LEAPYEAR_H_INCLUDED

At least now it compiles, but it doesn't link yet. Duh, that because we don't have an implementation yet.
Time to provide the bare minimum of code to make the test pass.
So we change the LeapYear.cpp into :

#include "LeapYear.h"

bool IsLeapYear(int /*Year*/)
{
return true;
}

Build it, run it. Yes, we have one test passed.
Great. Let's move on.

== LeapYear-Step3 ==
Anyone having the feeling we are cheating. Well the user does not know how we wrote our code on the inside. So just to be sure the user (we) adds the following test, ending up in :

#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

TEST(OurSecondTest)
{
const bool Result = IsLeapYear(1973);
CHECK_EQUAL(false, Result);
}

}

Building is already no issue any more, we can run it. Oh boy, a test is failing.
The framework tell us something like this :
<filename>:<Line>: error: Failure in OurSecondTest: Expected 0 but was 1
FAILURE: 1 out of 2 tests failed (1 failures)
Test time: 0.00 seconds.

So we are informed of the line where the failing tests occurs, next to that it tells us what it was expecting and what the actual outcome was. And it presents a resume of the total number of tests, and how many that failed. For you scripting hackers note that FAILURE != SUCCESS.

It seems we should do some more effort and implement some real logic.

== LeapYear-Step4 ==
Let's keep it taking one step at a time. Let's start by implementing the 'divisible by 4' logic. That will already solve our tests.
So our LeapYear.cpp will now look like this :

<source lang="cpp">
#include "LeapYear.h"

namespace
{

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year);
}

</source>
Build, run. All tests pass. Life is great.

But those changing requirements, always the change of the requirements. Years that can be divided by 100 should not be considered as a leap year.

Time for our next step.

== LeapYear-Step5 ==
We add a new test for checking for example the year 1900.

<source lang="cpp">
TEST(DivisableBy100)
{
const bool Result = IsLeapYear(1900);
CHECK_EQUAL(false, Result);
}
</source>

Build and run the tests. It will fail. So time to add the minimum code needed to make this test pass.
This will change our LeapYear.cpp into :

<source lang="cpp">

#include "LeapYear.h"

namespace
{

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year) && !IsDivisableBy100(Year);
}
</source>

Build and run the tests, yes : success. All 3 tests pass.

It seems life might be great again ...

Wrong, someone just added the following test :

<source lang="cpp">
TEST(DivisableBy400)
{
const bool Result = IsLeapYear(2000);
CHECK_EQUAL(true, Result);
}
</source>

And we once again have a failing test.

Time for the next step.

== LeapYear-Step6 ==
We should add logic to deal with years that can be divided by 400, since those are leap years.
We change our LeapYear.cpp into this :

<pre>
#include "LeapYear.h"

namespace
{

bool IsDivisableBy400(int Year)
{
return (Year%400) == 0;
}

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
const bool LeapYear = IsDivisableBy400(Year) ||
(IsDivisableBy4(Year) && !IsDivisableBy100(Year));
return LeapYear;
}

</pre>

And once again everything works OK.
And it seems all the logical rules have been implemented.
This one is ready for shipping, and till the end of time we have our tests that can be run whenever we want (more on this later, we'd prefer this to be done automatically) to ensure we never break anything.

UnitTesting

2009-09-09T10:21:53Z

Killerbot: /* LeapYear-Step4 */

This document is under development by killerbot. Starting from 7 September 2009.

== Introduction ==
This document will describe how unit testing can be combined with the Code::Blocks IDE. It will give a hands-on example on a unit testing framework and how it can be used with Code::Blocks.

== What is Unit Testing ==
Simply put Unit Testing is the discipline and best practice of writing and running little test programs that test little units of code.
Such a unit can be :
* a class
* a free function
* an interface
* ...
There are several unit test frameworks available to help you write, deploy, manage your unit tests. The most famous family is the xUnit framework, and some of it's descendants.

== Why Unit Testing ==
Well we write code that implements some functionality. We need a way to check and prove that the implementation is correct. Therefor we need tests. We need tests on the application level, at the integration level of different components, classes, interfaces. But we also need tests for the smallest building blocks, the units.
We also wans these tests to run very quickly. That we we can run the tests often, manually or automated.
These tests will also be our safeguards during refactoring of the code, extending the code or whatever maintenance tasks we carry out on the code.
These tests will also make us think of how our class, method, ... will be used. Since the test can be seen as a user of our code. Thanks do this, thinking about the tests before implementing the functionality can help us in the design : emergent design.
It will help us to avoid creating big classes, complex functions. We will only write the methods that are really needed, and no methods that we think might (n)ever be useful in the future. We are no good future tellers ! Those 'might be needed' methods and their tests are just a waste of time. Extending, refactoring will be done when it is actually needed, and at that time we have our unit tests to ensure we don't break any existing code.

Other times to add new unit tests are typically when a bug is discovered; Write a unit test to reproduces the bug, fix the code, and from now on the new unit test will watch your back so the bug won't reappear.

Unit test are also a good place of documentation. The little tests show how the class or method is used.
The code documents itself.

So the benefits are :
* better design
* prove of your code
* safe guard during code maintenance (refactoring, extensions)
* documentation
* ...

== Unit Test frameworks ==
When writing unit tests, one will create a lot of similar code. Since unit tests are nothing more then little programs, several tasks will be repeated, setting up the test environment, create your class, call a method, verify it's result, write out an error message when the test fails, preferably specifying what the wrong outcome was, and what the expected result is.
All these repetitive chores are taken care of by the frame work so the developer can focus on the real code of the test.
This document will use a small but very effective framework for the C++ language. It is called UnitTest++. It's homepage is at : [http://unittest-cpp.sourceforge.net/ UnitTest++].
You can download it directly at this [http://sourceforge.net/projects/unittest-cpp/files/UnitTest%2B%2B/1.4/unittest-cpp-1.4.zip/download link]. At the time of writing the latest version is 1.4.

== Setup our environment ==
Let's create a directory on our PC in which we will cary out our experiments. I will refer to this directory from now on as <TestPit>. For my laptop on which I am writing this article, that will be /home/lieven/Projects/UnitTestArticle. Note that everything we will do, works on linux and on windows!
Download the "unittest-cpp-1.4.zip" file from the link specified above. Extract it in the <TestPit> directory. All the files will end up in the <TestPit>/UnitTest++ directory.

== Build UnitTest++ ==
After the extracted the zip archive we have a directory structure like this :
<TestPit>/UnitTest++
|
+docs
|
+src

The files in the UnitTest++ directory are of little use for us, since they bring project files for some bizarre Microsoft IDE ;-) .
We will create our own Code::Blocks project to build the UnitTest++ framework.

Why do we need to build something ? Well as said, the framework will do a lot of chores for us, those chores are implemented by code, that code is framework. We will build to frame work into a static library, and for every unit test (or set of unit tests) we create a little (console/shell) program with the test code we wrote, which will link with the static library to obtain a unit test executable, driven by the framework.

We will put our Code::Blocks project file in a nice structured directory tree, therefor let's create a 'Project' subdirectory in the <TestPit>/UniTest++ directory.

In there create a new file with the name "UnitTest++.cbp".
Give that file the following content :

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="UnitTest++" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option platforms="Windows;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option platforms="Windows;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
<Target title="Debug(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<VirtualTargets>
<Add alias="All" targets="Debug;Release;Debug(linux);Release(linux);" />
</VirtualTargets>
<Unit filename="../src/AssertException.cpp" />
<Unit filename="../src/AssertException.h" />
<Unit filename="../src/CheckMacros.h" />
<Unit filename="../src/Checks.cpp" />
<Unit filename="../src/Checks.h" />
<Unit filename="../src/Config.h" />
<Unit filename="../src/CurrentTest.cpp" />
<Unit filename="../src/CurrentTest.h" />
<Unit filename="../src/DeferredTestReporter.cpp" />
<Unit filename="../src/DeferredTestReporter.h" />
<Unit filename="../src/DeferredTestResult.cpp" />
<Unit filename="../src/DeferredTestResult.h" />
<Unit filename="../src/ExecuteTest.h" />
<Unit filename="../src/MemoryOutStream.cpp" />
<Unit filename="../src/MemoryOutStream.h" />
<Unit filename="../src/Posix/SignalTranslator.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/SignalTranslator.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/ReportAssert.cpp" />
<Unit filename="../src/ReportAssert.h" />
<Unit filename="../src/Test.cpp" />
<Unit filename="../src/Test.h" />
<Unit filename="../src/TestDetails.cpp" />
<Unit filename="../src/TestDetails.h" />
<Unit filename="../src/TestList.cpp" />
<Unit filename="../src/TestList.h" />
<Unit filename="../src/TestMacros.h" />
<Unit filename="../src/TestReporter.cpp" />
<Unit filename="../src/TestReporter.h" />
<Unit filename="../src/TestReporterStdout.cpp" />
<Unit filename="../src/TestReporterStdout.h" />
<Unit filename="../src/TestResults.cpp" />
<Unit filename="../src/TestResults.h" />
<Unit filename="../src/TestRunner.cpp" />
<Unit filename="../src/TestRunner.h" />
<Unit filename="../src/TestSuite.h" />
<Unit filename="../src/TimeConstraint.cpp" />
<Unit filename="../src/TimeConstraint.h" />
<Unit filename="../src/TimeHelpers.h" />
<Unit filename="../src/UnitTest++.h" />
<Unit filename="../src/Win32/TimeHelpers.cpp">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/Win32/TimeHelpers.h">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/XmlTestReporter.cpp" />
<Unit filename="../src/XmlTestReporter.h" />
<Extensions>
<envvars />
<code_completion />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

Some things to note about the content of the project file, the power of Code::Blocks.
* there are 4 targets : Debug/Release for Windows and Debug/Release for linux [yes : 1 project file that allows building on linux and on windows]
* some files are only part of the linux targets, some only for the windows targets

But before we build, let's modify some source files (not really needed, but I prefer to have warning free compilations). These are the changes I carried out :
* ReportAssert.cpp : #include "ReportAssert.h"
* win32/TimeHelpers.cpp : first the m_threadHandle and then the m_startTime in the initializerlist

Next open up this project file in Code::Blocks and build the debug and release target. From now one we will only use the Release target, we go for speed ;-)

The result of the build process will show up in subdirectories of the new 'Deliv' subdirectory of <testPit>/UnitTest++ : '''<testPit>/UnitTest++/Deliv/Release/libUnitTest++.a'''

Alright, we have build the unit test framework in a platform independent way, no silly makefiles, no obscure M$ IDE, good old super Code::Blocks. It is time to write some code so we have something to unit test.

In the first example we will create a simple free function that checks if a a give year is a leap your or not.

The business logic is as follows : a year is a leap year when it can be divided by 4, unless itcan be divided by 100. But in case it can be divided by 400, then again it is a leap year.

In the next section we will first setup a Code::Blocks project containing both the 'functionality files, and the unit test files. Typically one will package several functionality files into a static library and create a unit test project that tests all the class/functionalities in that library package, also called a component. That is we have a component (whose deliverable is the static library, and we have a unit test project that tests the entire component).

== Our first test project environment ==
Let's create a new directory in our <TestPit> : <TestPit>/LeapYear.
For the simplicity we will put the project file and the source file all together in this directory. Normally we would work in a more structured way, but in a demo article we have some artistic freedom ;-)
Next you can create with the Code::Block's wizard a new console project in the LeapYear directory. Or you can create the following 4 files and give the the contents as specified below. Note that this demo works on linux and on windows, everything is still completely platform independent. Long Live Code::Blocks.

The project file : LeapYear.cbp (the one below already contains the 3 source files, in case you use the wizard you have to add the LeapYear.h/cpp files to the project)

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="LeapYear" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option output="Deliv/Debug/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Debug/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option output="Deliv/Release/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Release/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-O2" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<Compiler>
<Add option="-Wall" />
<Add option="-fexceptions" />
</Compiler>
<Unit filename="LeapYear.cpp" />
<Unit filename="LeapYear.h" />
<Unit filename="main.cpp" />
<Extensions>
<envvars />
<code_completion />
<lib_finder disable_auto="1" />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

The main source file : main.cpp
int main()
{
return 0;
}

The header exporting our powerful function : LeapYear.h

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

#endif // LEAPYEAR_H_INCLUDED

And the implementation of the leap year logic : LeapYear.cpp

#include "LeapYear.h"

And finishing with the source file for the tests : LeapYearTest.cpp (currently) empty

We can already build the project, we have a nice little program that does .... nothing.

Time to move to the next section, a little word about Test Driven Development.

== Test Driven Development ==
This is a practice where new code is only added to make a failing test pass. And one only adds the code needed to make that test pass. Once that is done, a new test is added to will check the next functionality to add.
On this really simple example we will more or less practice some TDD.

So get ready, it's time for LeapYear-Step1.

== LeapYear-Step1 ==
We will turn our main.cpp into the guy in charge to carry out the tests, all we need to do is change the contents of main.cpp into this :

#include "UnitTest++.h"

int main()
{
return UnitTest::RunAllTests();
}

And add '''../UnitTest++/src''' to the compiler search directories on the project level of our LeapYear project.
And add '''../UnitTest++/Deliv/Release/libUnitTest++.a''' to the link libraries of the project

Why : well we need to link with the framework and we need to include the UnitTest++ header so we can use it's functionalities.

The line '''UnitTest::RunAllTests()''' will make sure all test encountered in our sources will be carried out.
We don't have any tests yet, nor any functionality, but go ahead build the project and run it.
This is the output :

Success: 0 tests passed
Test time: 0.00 seconds.

Great : success, but no tests yet. Well it's a start.
Time to move forward, and write our first test.

== LeapYear-Step2 ==
Test, test, but there's nothing to test. Yes, absolutely. Let's think of a test, a test that will help us in the design. Now that's a good idea. Suppose I would be the user of the uplifting problem solving leap year checking library/component ... hmmm modesty first : leap year checking '''function'''.
How would I like that function to look.
bool IsLeapYear(int Year);

Yes that seems acceptable.
So let's write a test that will call that method.
We do that by adding the following code to LeapYearTest.cpp

#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

}

Things to note :
* we include the unit test header
* it is good to put the tests in nameless namespace (will be explained later on)
* we use the TEST macro, the argument is the name of the test : OurFirstTest
* we use CHECK_EQUAL to check if the expected result (the first argument) matches the computed result (the second argument)

Time to build. Woooooops errors. The tests fails completely, it does not even build. Time to add the code needed.
In order to compiler the test file, we need to include the LeapYear.h header and have that header export our function.
Our LeapYear header will look like this now (don't forget the include in the test file, it is not shown here) :

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

bool IsLeapYear(int Year);

#endif // LEAPYEAR_H_INCLUDED

At least now it compiles, but it doesn't link yet. Duh, that because we don't have an implementation yet.
Time to provide the bare minimum of code to make the test pass.
So we change the LeapYear.cpp into :

#include "LeapYear.h"

bool IsLeapYear(int /*Year*/)
{
return true;
}

Build it, run it. Yes, we have one test passed.
Great. Let's move on.

== LeapYear-Step3 ==
Anyone having the feeling we are cheating. Well the user does not know how we wrote our code on the inside. So just to be sure the user (we) adds the following test, ending up in :

#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

TEST(OurSecondTest)
{
const bool Result = IsLeapYear(1973);
CHECK_EQUAL(false, Result);
}

}

Building is already no issue any more, we can run it. Oh boy, a test is failing.
The framework tell us something like this :
<filename>:<Line>: error: Failure in OurSecondTest: Expected 0 but was 1
FAILURE: 1 out of 2 tests failed (1 failures)
Test time: 0.00 seconds.

So we are informed of the line where the failing tests occurs, next to that it tells us what it was expecting and what the actual outcome was. And it presents a resume of the total number of tests, and how many that failed. For you scripting hackers note that FAILURE != SUCCESS.

It seems we should do some more effort and implement some real logic.

== LeapYear-Step4 ==
Let's keep it taking one step at a time. Let's start by implementing the 'divisible by 4' logic. That will already solve our tests.
So our LeapYear.cpp will now look like this :

<source lang="cpp">
#include "LeapYear.h"

namespace
{

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year);
}

</source>
Build, run. All tests pass. Life is great.

But those changing requirements, always the change of the requirements. Years that can be divided by 100 should not be considered as a leap year.

Time for our next step.

== LeapYear-Step5 ==
We add a new test for checking for example the year 1900.

<pre>
TEST(DivisableBy100)
{
const bool Result = IsLeapYear(1900);
CHECK_EQUAL(false, Result);
}
</pre>

Build and run the tests. It will fail. So time to add the minimum code needed to make this test pass.
This will change our LeapYear.cpp into :

<pre>
#include "LeapYear.h"

namespace
{

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year) && !IsDivisableBy100(Year);
}
</pre>

Build and run the tests, yes : success. All 3 tests pass.

It seems life might be great again ...

Wrong, someone just added the following test :

<pre>
TEST(DivisableBy400)
{
const bool Result = IsLeapYear(2000);
CHECK_EQUAL(true, Result);
}
</pre>

And we once again have a failing test.

Time for the next step.

== LeapYear-Step6 ==
We should add logic to deal with years that can be divided by 400, since those are leap years.
We change our LeapYear.cpp into this :

<pre>
#include "LeapYear.h"

namespace
{

bool IsDivisableBy400(int Year)
{
return (Year%400) == 0;
}

bool IsDivisableBy100(int Year)
{
return (Year%100) == 0;
}

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
const bool LeapYear = IsDivisableBy400(Year) ||
(IsDivisableBy4(Year) && !IsDivisableBy100(Year));
return LeapYear;
}

</pre>

And once again everything works OK.
And it seems all the logical rules have been implemented.
This one is ready for shipping, and till the end of time we have our tests that can be run whenever we want (more on this later, we'd prefer this to be done automatically) to ensure we never break anything.

UnitTesting

2009-09-09T09:49:06Z

Killerbot: /* Our first test project environment */

This document is under development by killerbot. Starting from 7 September 2009.

== Introduction ==
This document will describe how unit testing can be combined with the Code::Blocks IDE. It will give a hands-on example on a unit testing framework and how it can be used with Code::Blocks.

== What is Unit Testing ==
Simply put Unit Testing is the discipline and best practice of writing and running little test programs that test little units of code.
Such a unit can be :
* a class
* a free function
* an interface
* ...
There are several unit test frameworks available to help you write, deploy, manage your unit tests. The most famous family is the xUnit framework, and some of it's descendants.

== Why Unit Testing ==
Well we write code that implements some functionality. We need a way to check and prove that the implementation is correct. Therefor we need tests. We need tests on the application level, at the integration level of different components, classes, interfaces. But we also need tests for the smallest building blocks, the units.
We also wans these tests to run very quickly. That we we can run the tests often, manually or automated.
These tests will also be our safeguards during refactoring of the code, extending the code or whatever maintenance tasks we carry out on the code.
These tests will also make us think of how our class, method, ... will be used. Since the test can be seen as a user of our code. Thanks do this, thinking about the tests before implementing the functionality can help us in the design : emergent design.
It will help us to avoid creating big classes, complex functions. We will only write the methods that are really needed, and no methods that we think might (n)ever be useful in the future. We are no good future tellers ! Those 'might be needed' methods and their tests are just a waste of time. Extending, refactoring will be done when it is actually needed, and at that time we have our unit tests to ensure we don't break any existing code.

Other times to add new unit tests are typically when a bug is discovered; Write a unit test to reproduces the bug, fix the code, and from now on the new unit test will watch your back so the bug won't reappear.

Unit test are also a good place of documentation. The little tests show how the class or method is used.
The code documents itself.

So the benefits are :
* better design
* prove of your code
* safe guard during code maintenance (refactoring, extensions)
* documentation
* ...

== Unit Test frameworks ==
When writing unit tests, one will create a lot of similar code. Since unit tests are nothing more then little programs, several tasks will be repeated, setting up the test environment, create your class, call a method, verify it's result, write out an error message when the test fails, preferably specifying what the wrong outcome was, and what the expected result is.
All these repetitive chores are taken care of by the frame work so the developer can focus on the real code of the test.
This document will use a small but very effective framework for the C++ language. It is called UnitTest++. It's homepage is at : [http://unittest-cpp.sourceforge.net/ UnitTest++].
You can download it directly at this [http://sourceforge.net/projects/unittest-cpp/files/UnitTest%2B%2B/1.4/unittest-cpp-1.4.zip/download link]. At the time of writing the latest version is 1.4.

== Setup our environment ==
Let's create a directory on our PC in which we will cary out our experiments. I will refer to this directory from now on as <TestPit>. For my laptop on which I am writing this article, that will be /home/lieven/Projects/UnitTestArticle. Note that everything we will do, works on linux and on windows!
Download the "unittest-cpp-1.4.zip" file from the link specified above. Extract it in the <TestPit> directory. All the files will end up in the <TestPit>/UnitTest++ directory.

== Build UnitTest++ ==
After the extracted the zip archive we have a directory structure like this :
<TestPit>/UnitTest++
|
+docs
|
+src

The files in the UnitTest++ directory are of little use for us, since they bring project files for some bizarre Microsoft IDE ;-) .
We will create our own Code::Blocks project to build the UnitTest++ framework.

Why do we need to build something ? Well as said, the framework will do a lot of chores for us, those chores are implemented by code, that code is framework. We will build to frame work into a static library, and for every unit test (or set of unit tests) we create a little (console/shell) program with the test code we wrote, which will link with the static library to obtain a unit test executable, driven by the framework.

We will put our Code::Blocks project file in a nice structured directory tree, therefor let's create a 'Project' subdirectory in the <TestPit>/UniTest++ directory.

In there create a new file with the name "UnitTest++.cbp".
Give that file the following content :

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="UnitTest++" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option platforms="Windows;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option platforms="Windows;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
<Target title="Debug(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<VirtualTargets>
<Add alias="All" targets="Debug;Release;Debug(linux);Release(linux);" />
</VirtualTargets>
<Unit filename="../src/AssertException.cpp" />
<Unit filename="../src/AssertException.h" />
<Unit filename="../src/CheckMacros.h" />
<Unit filename="../src/Checks.cpp" />
<Unit filename="../src/Checks.h" />
<Unit filename="../src/Config.h" />
<Unit filename="../src/CurrentTest.cpp" />
<Unit filename="../src/CurrentTest.h" />
<Unit filename="../src/DeferredTestReporter.cpp" />
<Unit filename="../src/DeferredTestReporter.h" />
<Unit filename="../src/DeferredTestResult.cpp" />
<Unit filename="../src/DeferredTestResult.h" />
<Unit filename="../src/ExecuteTest.h" />
<Unit filename="../src/MemoryOutStream.cpp" />
<Unit filename="../src/MemoryOutStream.h" />
<Unit filename="../src/Posix/SignalTranslator.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/SignalTranslator.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/ReportAssert.cpp" />
<Unit filename="../src/ReportAssert.h" />
<Unit filename="../src/Test.cpp" />
<Unit filename="../src/Test.h" />
<Unit filename="../src/TestDetails.cpp" />
<Unit filename="../src/TestDetails.h" />
<Unit filename="../src/TestList.cpp" />
<Unit filename="../src/TestList.h" />
<Unit filename="../src/TestMacros.h" />
<Unit filename="../src/TestReporter.cpp" />
<Unit filename="../src/TestReporter.h" />
<Unit filename="../src/TestReporterStdout.cpp" />
<Unit filename="../src/TestReporterStdout.h" />
<Unit filename="../src/TestResults.cpp" />
<Unit filename="../src/TestResults.h" />
<Unit filename="../src/TestRunner.cpp" />
<Unit filename="../src/TestRunner.h" />
<Unit filename="../src/TestSuite.h" />
<Unit filename="../src/TimeConstraint.cpp" />
<Unit filename="../src/TimeConstraint.h" />
<Unit filename="../src/TimeHelpers.h" />
<Unit filename="../src/UnitTest++.h" />
<Unit filename="../src/Win32/TimeHelpers.cpp">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/Win32/TimeHelpers.h">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/XmlTestReporter.cpp" />
<Unit filename="../src/XmlTestReporter.h" />
<Extensions>
<envvars />
<code_completion />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

Some things to note about the content of the project file, the power of Code::Blocks.
* there are 4 targets : Debug/Release for Windows and Debug/Release for linux [yes : 1 project file that allows building on linux and on windows]
* some files are only part of the linux targets, some only for the windows targets

But before we build, let's modify some source files (not really needed, but I prefer to have warning free compilations). These are the changes I carried out :
* ReportAssert.cpp : #include "ReportAssert.h"
* win32/TimeHelpers.cpp : first the m_threadHandle and then the m_startTime in the initializerlist

Next open up this project file in Code::Blocks and build the debug and release target. From now one we will only use the Release target, we go for speed ;-)

The result of the build process will show up in subdirectories of the new 'Deliv' subdirectory of <testPit>/UnitTest++ : '''<testPit>/UnitTest++/Deliv/Release/libUnitTest++.a'''

Alright, we have build the unit test framework in a platform independent way, no silly makefiles, no obscure M$ IDE, good old super Code::Blocks. It is time to write some code so we have something to unit test.

In the first example we will create a simple free function that checks if a a give year is a leap your or not.

The business logic is as follows : a year is a leap year when it can be divided by 4, unless itcan be divided by 100. But in case it can be divided by 400, then again it is a leap year.

In the next section we will first setup a Code::Blocks project containing both the 'functionality files, and the unit test files. Typically one will package several functionality files into a static library and create a unit test project that tests all the class/functionalities in that library package, also called a component. That is we have a component (whose deliverable is the static library, and we have a unit test project that tests the entire component).

== Our first test project environment ==
Let's create a new directory in our <TestPit> : <TestPit>/LeapYear.
For the simplicity we will put the project file and the source file all together in this directory. Normally we would work in a more structured way, but in a demo article we have some artistic freedom ;-)
Next you can create with the Code::Block's wizard a new console project in the LeapYear directory. Or you can create the following 4 files and give the the contents as specified below. Note that this demo works on linux and on windows, everything is still completely platform independent. Long Live Code::Blocks.

The project file : LeapYear.cbp (the one below already contains the 3 source files, in case you use the wizard you have to add the LeapYear.h/cpp files to the project)

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="LeapYear" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option output="Deliv/Debug/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Debug/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option output="Deliv/Release/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Release/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-O2" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<Compiler>
<Add option="-Wall" />
<Add option="-fexceptions" />
</Compiler>
<Unit filename="LeapYear.cpp" />
<Unit filename="LeapYear.h" />
<Unit filename="main.cpp" />
<Extensions>
<envvars />
<code_completion />
<lib_finder disable_auto="1" />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

The main source file : main.cpp
int main()
{
return 0;
}

The header exporting our powerful function : LeapYear.h

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

#endif // LEAPYEAR_H_INCLUDED

And the implementation of the leap year logic : LeapYear.cpp

#include "LeapYear.h"

And finishing with the source file for the tests : LeapYearTest.cpp (currently) empty

We can already build the project, we have a nice little program that does .... nothing.

Time to move to the next section, a little word about Test Driven Development.

== Test Driven Development ==
This is a practice where new code is only added to make a failing test pass. And one only adds the code needed to make that test pass. Once that is done, a new test is added to will check the next functionality to add.
On this really simple example we will more or less practice some TDD.

So get ready, it's time for LeapYear-Step1.

== LeapYear-Step1 ==
We will turn our main.cpp into the guy in charge to carry out the tests, all we need to do is change the contents of main.cpp into this :

#include "UnitTest++.h"

int main()
{
return UnitTest::RunAllTests();
}

And add '''../UnitTest++/src''' to the compiler search directories on the project level of our LeapYear project.
And add '''../UnitTest++/Deliv/Release/libUnitTest++.a''' to the link libraries of the project

Why : well we need to link with the framework and we need to include the UnitTest++ header so we can use it's functionalities.

The line '''UnitTest::RunAllTests()''' will make sure all test encountered in our sources will be carried out.
We don't have any tests yet, nor any functionality, but go ahead build the project and run it.
This is the output :

Success: 0 tests passed
Test time: 0.00 seconds.

Great : success, but no tests yet. Well it's a start.
Time to move forward, and write our first test.

== LeapYear-Step2 ==
Test, test, but there's nothing to test. Yes, absolutely. Let's think of a test, a test that will help us in the design. Now that's a good idea. Suppose I would be the user of the uplifting problem solving leap year checking library/component ... hmmm modesty first : leap year checking '''function'''.
How would I like that function to look.
bool IsLeapYear(int Year);

Yes that seems acceptable.
So let's write a test that will call that method.
We do that by adding the following code to LeapYearTest.cpp

#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

}

Things to note :
* we include the unit test header
* it is good to put the tests in nameless namespace (will be explained later on)
* we use the TEST macro, the argument is the name of the test : OurFirstTest
* we use CHECK_EQUAL to check if the expected result (the first argument) matches the computed result (the second argument)

Time to build. Woooooops errors. The tests fails completely, it does not even build. Time to add the code needed.
In order to compiler the test file, we need to include the LeapYear.h header and have that header export our function.
Our LeapYear header will look like this now (don't forget the include in the test file, it is not shown here) :

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

bool IsLeapYear(int Year);

#endif // LEAPYEAR_H_INCLUDED

At least now it compiles, but it doesn't link yet. Duh, that because we don't have an implementation yet.
Time to provide the bare minimum of code to make the test pass.
So we change the LeapYear.cpp into :

#include "LeapYear.h"

bool IsLeapYear(int /*Year*/)
{
return true;
}

Build it, run it. Yes, we have one test passed.
Great. Let's move on.

== LeapYear-Step3 ==
Anyone having the feeling we are cheating. Well the user does not know how we wrote our code on the inside. So just to be sure the user (we) adds the following test, ending up in :

#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

TEST(OurSecondTest)
{
const bool Result = IsLeapYear(1973);
CHECK_EQUAL(false, Result);
}

}

Building is already no issue any more, we can run it. Oh boy, a test is failing.
The framework tell us something like this :
<filename>:<Line>: error: Failure in OurSecondTest: Expected 0 but was 1
FAILURE: 1 out of 2 tests failed (1 failures)
Test time: 0.00 seconds.

So we are informed of the line where the failing tests occurs, next to that it tells us what it was expecting and what the actual outcome was. And it presents a resume of the total number of tests, and how many that failed. For you scripting hackers note that FAILURE != SUCCESS.

It seems we should do some more effort and implement some real logic.

== LeapYear-Step4 ==
Let's keep it taking one step at a time. Let's start by implementing the 'divisible by 4' logic. That will already solve our tests.
So our LeapYear.cpp will now look like this :

<source lang="cpp">
#include "LeapYear.h"

namespace
{

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year);
}

</source>
Build, run. All tests pass. Life is great.

But those changing requirements, always the change of the requirements. Years that can be divided by 100 should not be considered as a leap year.

UnitTesting

2009-09-09T09:45:19Z

Killerbot: /* LeapYear-Step4 */

This document is under development by killerbot. Starting from 7 September 2009.

== Introduction ==
This document will describe how unit testing can be combined with the Code::Blocks IDE. It will give a hands-on example on a unit testing framework and how it can be used with Code::Blocks.

== What is Unit Testing ==
Simply put Unit Testing is the discipline and best practice of writing and running little test programs that test little units of code.
Such a unit can be :
* a class
* a free function
* an interface
* ...
There are several unit test frameworks available to help you write, deploy, manage your unit tests. The most famous family is the xUnit framework, and some of it's descendants.

== Why Unit Testing ==
Well we write code that implements some functionality. We need a way to check and prove that the implementation is correct. Therefor we need tests. We need tests on the application level, at the integration level of different components, classes, interfaces. But we also need tests for the smallest building blocks, the units.
We also wans these tests to run very quickly. That we we can run the tests often, manually or automated.
These tests will also be our safeguards during refactoring of the code, extending the code or whatever maintenance tasks we carry out on the code.
These tests will also make us think of how our class, method, ... will be used. Since the test can be seen as a user of our code. Thanks do this, thinking about the tests before implementing the functionality can help us in the design : emergent design.
It will help us to avoid creating big classes, complex functions. We will only write the methods that are really needed, and no methods that we think might (n)ever be useful in the future. We are no good future tellers ! Those 'might be needed' methods and their tests are just a waste of time. Extending, refactoring will be done when it is actually needed, and at that time we have our unit tests to ensure we don't break any existing code.

Other times to add new unit tests are typically when a bug is discovered; Write a unit test to reproduces the bug, fix the code, and from now on the new unit test will watch your back so the bug won't reappear.

Unit test are also a good place of documentation. The little tests show how the class or method is used.
The code documents itself.

So the benefits are :
* better design
* prove of your code
* safe guard during code maintenance (refactoring, extensions)
* documentation
* ...

== Unit Test frameworks ==
When writing unit tests, one will create a lot of similar code. Since unit tests are nothing more then little programs, several tasks will be repeated, setting up the test environment, create your class, call a method, verify it's result, write out an error message when the test fails, preferably specifying what the wrong outcome was, and what the expected result is.
All these repetitive chores are taken care of by the frame work so the developer can focus on the real code of the test.
This document will use a small but very effective framework for the C++ language. It is called UnitTest++. It's homepage is at : [http://unittest-cpp.sourceforge.net/ UnitTest++].
You can download it directly at this [http://sourceforge.net/projects/unittest-cpp/files/UnitTest%2B%2B/1.4/unittest-cpp-1.4.zip/download link]. At the time of writing the latest version is 1.4.

== Setup our environment ==
Let's create a directory on our PC in which we will cary out our experiments. I will refer to this directory from now on as <TestPit>. For my laptop on which I am writing this article, that will be /home/lieven/Projects/UnitTestArticle. Note that everything we will do, works on linux and on windows!
Download the "unittest-cpp-1.4.zip" file from the link specified above. Extract it in the <TestPit> directory. All the files will end up in the <TestPit>/UnitTest++ directory.

== Build UnitTest++ ==
After the extracted the zip archive we have a directory structure like this :
<TestPit>/UnitTest++
|
+docs
|
+src

The files in the UnitTest++ directory are of little use for us, since they bring project files for some bizarre Microsoft IDE ;-) .
We will create our own Code::Blocks project to build the UnitTest++ framework.

Why do we need to build something ? Well as said, the framework will do a lot of chores for us, those chores are implemented by code, that code is framework. We will build to frame work into a static library, and for every unit test (or set of unit tests) we create a little (console/shell) program with the test code we wrote, which will link with the static library to obtain a unit test executable, driven by the framework.

We will put our Code::Blocks project file in a nice structured directory tree, therefor let's create a 'Project' subdirectory in the <TestPit>/UniTest++ directory.

In there create a new file with the name "UnitTest++.cbp".
Give that file the following content :

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="UnitTest++" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option platforms="Windows;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option platforms="Windows;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
<Target title="Debug(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<VirtualTargets>
<Add alias="All" targets="Debug;Release;Debug(linux);Release(linux);" />
</VirtualTargets>
<Unit filename="../src/AssertException.cpp" />
<Unit filename="../src/AssertException.h" />
<Unit filename="../src/CheckMacros.h" />
<Unit filename="../src/Checks.cpp" />
<Unit filename="../src/Checks.h" />
<Unit filename="../src/Config.h" />
<Unit filename="../src/CurrentTest.cpp" />
<Unit filename="../src/CurrentTest.h" />
<Unit filename="../src/DeferredTestReporter.cpp" />
<Unit filename="../src/DeferredTestReporter.h" />
<Unit filename="../src/DeferredTestResult.cpp" />
<Unit filename="../src/DeferredTestResult.h" />
<Unit filename="../src/ExecuteTest.h" />
<Unit filename="../src/MemoryOutStream.cpp" />
<Unit filename="../src/MemoryOutStream.h" />
<Unit filename="../src/Posix/SignalTranslator.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/SignalTranslator.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/ReportAssert.cpp" />
<Unit filename="../src/ReportAssert.h" />
<Unit filename="../src/Test.cpp" />
<Unit filename="../src/Test.h" />
<Unit filename="../src/TestDetails.cpp" />
<Unit filename="../src/TestDetails.h" />
<Unit filename="../src/TestList.cpp" />
<Unit filename="../src/TestList.h" />
<Unit filename="../src/TestMacros.h" />
<Unit filename="../src/TestReporter.cpp" />
<Unit filename="../src/TestReporter.h" />
<Unit filename="../src/TestReporterStdout.cpp" />
<Unit filename="../src/TestReporterStdout.h" />
<Unit filename="../src/TestResults.cpp" />
<Unit filename="../src/TestResults.h" />
<Unit filename="../src/TestRunner.cpp" />
<Unit filename="../src/TestRunner.h" />
<Unit filename="../src/TestSuite.h" />
<Unit filename="../src/TimeConstraint.cpp" />
<Unit filename="../src/TimeConstraint.h" />
<Unit filename="../src/TimeHelpers.h" />
<Unit filename="../src/UnitTest++.h" />
<Unit filename="../src/Win32/TimeHelpers.cpp">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/Win32/TimeHelpers.h">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/XmlTestReporter.cpp" />
<Unit filename="../src/XmlTestReporter.h" />
<Extensions>
<envvars />
<code_completion />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

Some things to note about the content of the project file, the power of Code::Blocks.
* there are 4 targets : Debug/Release for Windows and Debug/Release for linux [yes : 1 project file that allows building on linux and on windows]
* some files are only part of the linux targets, some only for the windows targets

But before we build, let's modify some source files (not really needed, but I prefer to have warning free compilations). These are the changes I carried out :
* ReportAssert.cpp : #include "ReportAssert.h"
* win32/TimeHelpers.cpp : first the m_threadHandle and then the m_startTime in the initializerlist

Next open up this project file in Code::Blocks and build the debug and release target. From now one we will only use the Release target, we go for speed ;-)

The result of the build process will show up in subdirectories of the new 'Deliv' subdirectory of <testPit>/UnitTest++ : '''<testPit>/UnitTest++/Deliv/Release/libUnitTest++.a'''

Alright, we have build the unit test framework in a platform independent way, no silly makefiles, no obscure M$ IDE, good old super Code::Blocks. It is time to write some code so we have something to unit test.

In the first example we will create a simple free function that checks if a a give year is a leap your or not.

The business logic is as follows : a year is a leap year when it can be divided by 4, unless itcan be divided by 100. But in case it can be divided by 400, then again it is a leap year.

In the next section we will first setup a Code::Blocks project containing both the 'functionality files, and the unit test files. Typically one will package several functionality files into a static library and create a unit test project that tests all the class/functionalities in that library package, also called a component. That is we have a component (whose deliverable is the static library, and we have a unit test project that tests the entire component).

== Our first test project environment ==
Let's create a new directory in our <TestPit> : <TestPit>/LeapYear.
For the simplicity we will put the project file and the source file all together in this directory. Normally we would work in a more structured way, but in a demo article we have some artistic freedom ;-)
Next you can create with the Code::Block's wizard a new console project in the LeapYear directory. Or you can create the following 4 files and give the the contents as specified below. Note that this demo works on linux and on windows, everything is still completely platform independent. Long Live Code::Blocks.

The project file : LeapYear.cbp (the one below already contains the 3 source files, in case you use the wizard you have to add the LeapYear.h/cpp files to the project)

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="LeapYear" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option output="Deliv/Debug/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Debug/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option output="Deliv/Release/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Release/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-O2" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<Compiler>
<Add option="-Wall" />
<Add option="-fexceptions" />
</Compiler>
<Unit filename="LeapYear.cpp" />
<Unit filename="LeapYear.h" />
<Unit filename="main.cpp" />
<Extensions>
<envvars />
<code_completion />
<lib_finder disable_auto="1" />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>

The main source file : main.cpp
int main()
{
return 0;
}

The header exporting our powerful function : LeapYear.h

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

#endif // LEAPYEAR_H_INCLUDED

And the implementation of the leap year logic : LeapYear.cpp

#include "LeapYear.h"

And finishing with the source file for the tests : LeapYearTest.cpp (currently) empty

We can already build the project, we have a nice little program that does .... nothing.

Time to move to the next section, a little word about Test Driven Development.

== Test Driven Development ==
This is a practice where new code is only added to make a failing test pass. And one only adds the code needed to make that test pass. Once that is done, a new test is added to will check the next functionality to add.
On this really simple example we will more or less practice some TDD.

So get ready, it's time for LeapYear-Step1.

== LeapYear-Step1 ==
We will turn our main.cpp into the guy in charge to carry out the tests, all we need to do is change the contents of main.cpp into this :

#include "UnitTest++.h"

int main()
{
return UnitTest::RunAllTests();
}

And add '''../UnitTest++/src''' to the compiler search directories on the project level of our LeapYear project.
And add '''../UnitTest++/Deliv/Release/libUnitTest++.a''' to the link libraries of the project

Why : well we need to link with the framework and we need to include the UnitTest++ header so we can use it's functionalities.

The line '''UnitTest::RunAllTests()''' will make sure all test encountered in our sources will be carried out.
We don't have any tests yet, nor any functionality, but go ahead build the project and run it.
This is the output :

Success: 0 tests passed
Test time: 0.00 seconds.

Great : success, but no tests yet. Well it's a start.
Time to move forward, and write our first test.

== LeapYear-Step2 ==
Test, test, but there's nothing to test. Yes, absolutely. Let's think of a test, a test that will help us in the design. Now that's a good idea. Suppose I would be the user of the uplifting problem solving leap year checking library/component ... hmmm modesty first : leap year checking '''function'''.
How would I like that function to look.
bool IsLeapYear(int Year);

Yes that seems acceptable.
So let's write a test that will call that method.
We do that by adding the following code to LeapYearTest.cpp

#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

}

Things to note :
* we include the unit test header
* it is good to put the tests in nameless namespace (will be explained later on)
* we use the TEST macro, the argument is the name of the test : OurFirstTest
* we use CHECK_EQUAL to check if the expected result (the first argument) matches the computed result (the second argument)

Time to build. Woooooops errors. The tests fails completely, it does not even build. Time to add the code needed.
In order to compiler the test file, we need to include the LeapYear.h header and have that header export our function.
Our LeapYear header will look like this now (don't forget the include in the test file, it is not shown here) :

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

bool IsLeapYear(int Year);

#endif // LEAPYEAR_H_INCLUDED

At least now it compiles, but it doesn't link yet. Duh, that because we don't have an implementation yet.
Time to provide the bare minimum of code to make the test pass.
So we change the LeapYear.cpp into :

#include "LeapYear.h"

bool IsLeapYear(int /*Year*/)
{
return true;
}

Build it, run it. Yes, we have one test passed.
Great. Let's move on.

== LeapYear-Step3 ==
Anyone having the feeling we are cheating. Well the user does not know how we wrote our code on the inside. So just to be sure the user (we) adds the following test, ending up in :

#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

TEST(OurSecondTest)
{
const bool Result = IsLeapYear(1973);
CHECK_EQUAL(false, Result);
}

}

Building is already no issue any more, we can run it. Oh boy, a test is failing.
The framework tell us something like this :
<filename>:<Line>: error: Failure in OurSecondTest: Expected 0 but was 1
FAILURE: 1 out of 2 tests failed (1 failures)
Test time: 0.00 seconds.

So we are informed of the line where the failing tests occurs, next to that it tells us what it was expecting and what the actual outcome was. And it presents a resume of the total number of tests, and how many that failed. For you scripting hackers note that FAILURE != SUCCESS.

It seems we should do some more effort and implement some real logic.

== LeapYear-Step4 ==
Let's keep it taking one step at a time. Let's start by implementing the 'divisible by 4' logic. That will already solve our tests.
So our LeapYear.cpp will now look like this :

<source lang="cpp">
#include "LeapYear.h"

namespace
{

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year);
}

</source>
Build, run. All tests pass. Life is great.

But those changing requirements, always the change of the requirements. Years that can be divided by 100 should not be considered as a leap year.

UnitTesting

2009-09-09T09:44:32Z

Killerbot: /* Build UnitTest++ */

This document is under development by killerbot. Starting from 7 September 2009.

== Introduction ==
This document will describe how unit testing can be combined with the Code::Blocks IDE. It will give a hands-on example on a unit testing framework and how it can be used with Code::Blocks.

== What is Unit Testing ==
Simply put Unit Testing is the discipline and best practice of writing and running little test programs that test little units of code.
Such a unit can be :
* a class
* a free function
* an interface
* ...
There are several unit test frameworks available to help you write, deploy, manage your unit tests. The most famous family is the xUnit framework, and some of it's descendants.

== Why Unit Testing ==
Well we write code that implements some functionality. We need a way to check and prove that the implementation is correct. Therefor we need tests. We need tests on the application level, at the integration level of different components, classes, interfaces. But we also need tests for the smallest building blocks, the units.
We also wans these tests to run very quickly. That we we can run the tests often, manually or automated.
These tests will also be our safeguards during refactoring of the code, extending the code or whatever maintenance tasks we carry out on the code.
These tests will also make us think of how our class, method, ... will be used. Since the test can be seen as a user of our code. Thanks do this, thinking about the tests before implementing the functionality can help us in the design : emergent design.
It will help us to avoid creating big classes, complex functions. We will only write the methods that are really needed, and no methods that we think might (n)ever be useful in the future. We are no good future tellers ! Those 'might be needed' methods and their tests are just a waste of time. Extending, refactoring will be done when it is actually needed, and at that time we have our unit tests to ensure we don't break any existing code.

Other times to add new unit tests are typically when a bug is discovered; Write a unit test to reproduces the bug, fix the code, and from now on the new unit test will watch your back so the bug won't reappear.

Unit test are also a good place of documentation. The little tests show how the class or method is used.
The code documents itself.

So the benefits are :
* better design
* prove of your code
* safe guard during code maintenance (refactoring, extensions)
* documentation
* ...

== Unit Test frameworks ==
When writing unit tests, one will create a lot of similar code. Since unit tests are nothing more then little programs, several tasks will be repeated, setting up the test environment, create your class, call a method, verify it's result, write out an error message when the test fails, preferably specifying what the wrong outcome was, and what the expected result is.
All these repetitive chores are taken care of by the frame work so the developer can focus on the real code of the test.
This document will use a small but very effective framework for the C++ language. It is called UnitTest++. It's homepage is at : [http://unittest-cpp.sourceforge.net/ UnitTest++].
You can download it directly at this [http://sourceforge.net/projects/unittest-cpp/files/UnitTest%2B%2B/1.4/unittest-cpp-1.4.zip/download link]. At the time of writing the latest version is 1.4.

== Setup our environment ==
Let's create a directory on our PC in which we will cary out our experiments. I will refer to this directory from now on as <TestPit>. For my laptop on which I am writing this article, that will be /home/lieven/Projects/UnitTestArticle. Note that everything we will do, works on linux and on windows!
Download the "unittest-cpp-1.4.zip" file from the link specified above. Extract it in the <TestPit> directory. All the files will end up in the <TestPit>/UnitTest++ directory.

== Build UnitTest++ ==
After the extracted the zip archive we have a directory structure like this :
<TestPit>/UnitTest++
|
+docs
|
+src

The files in the UnitTest++ directory are of little use for us, since they bring project files for some bizarre Microsoft IDE ;-) .
We will create our own Code::Blocks project to build the UnitTest++ framework.

Why do we need to build something ? Well as said, the framework will do a lot of chores for us, those chores are implemented by code, that code is framework. We will build to frame work into a static library, and for every unit test (or set of unit tests) we create a little (console/shell) program with the test code we wrote, which will link with the static library to obtain a unit test executable, driven by the framework.

We will put our Code::Blocks project file in a nice structured directory tree, therefor let's create a 'Project' subdirectory in the <TestPit>/UniTest++ directory.

In there create a new file with the name "UnitTest++.cbp".
Give that file the following content :

<pre>
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="UnitTest++" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option platforms="Windows;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option platforms="Windows;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
<Target title="Debug(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<VirtualTargets>
<Add alias="All" targets="Debug;Release;Debug(linux);Release(linux);" />
</VirtualTargets>
<Unit filename="../src/AssertException.cpp" />
<Unit filename="../src/AssertException.h" />
<Unit filename="../src/CheckMacros.h" />
<Unit filename="../src/Checks.cpp" />
<Unit filename="../src/Checks.h" />
<Unit filename="../src/Config.h" />
<Unit filename="../src/CurrentTest.cpp" />
<Unit filename="../src/CurrentTest.h" />
<Unit filename="../src/DeferredTestReporter.cpp" />
<Unit filename="../src/DeferredTestReporter.h" />
<Unit filename="../src/DeferredTestResult.cpp" />
<Unit filename="../src/DeferredTestResult.h" />
<Unit filename="../src/ExecuteTest.h" />
<Unit filename="../src/MemoryOutStream.cpp" />
<Unit filename="../src/MemoryOutStream.h" />
<Unit filename="../src/Posix/SignalTranslator.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/SignalTranslator.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/ReportAssert.cpp" />
<Unit filename="../src/ReportAssert.h" />
<Unit filename="../src/Test.cpp" />
<Unit filename="../src/Test.h" />
<Unit filename="../src/TestDetails.cpp" />
<Unit filename="../src/TestDetails.h" />
<Unit filename="../src/TestList.cpp" />
<Unit filename="../src/TestList.h" />
<Unit filename="../src/TestMacros.h" />
<Unit filename="../src/TestReporter.cpp" />
<Unit filename="../src/TestReporter.h" />
<Unit filename="../src/TestReporterStdout.cpp" />
<Unit filename="../src/TestReporterStdout.h" />
<Unit filename="../src/TestResults.cpp" />
<Unit filename="../src/TestResults.h" />
<Unit filename="../src/TestRunner.cpp" />
<Unit filename="../src/TestRunner.h" />
<Unit filename="../src/TestSuite.h" />
<Unit filename="../src/TimeConstraint.cpp" />
<Unit filename="../src/TimeConstraint.h" />
<Unit filename="../src/TimeHelpers.h" />
<Unit filename="../src/UnitTest++.h" />
<Unit filename="../src/Win32/TimeHelpers.cpp">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/Win32/TimeHelpers.h">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/XmlTestReporter.cpp" />
<Unit filename="../src/XmlTestReporter.h" />
<Extensions>
<envvars />
<code_completion />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>
</pre>

Some things to note about the content of the project file, the power of Code::Blocks.
* there are 4 targets : Debug/Release for Windows and Debug/Release for linux [yes : 1 project file that allows building on linux and on windows]
* some files are only part of the linux targets, some only for the windows targets

But before we build, let's modify some source files (not really needed, but I prefer to have warning free compilations). These are the changes I carried out :
* ReportAssert.cpp : #include "ReportAssert.h"
* win32/TimeHelpers.cpp : first the m_threadHandle and then the m_startTime in the initializerlist

Next open up this project file in Code::Blocks and build the debug and release target. From now one we will only use the Release target, we go for speed ;-)

The result of the build process will show up in subdirectories of the new 'Deliv' subdirectory of <testPit>/UnitTest++ : '''<testPit>/UnitTest++/Deliv/Release/libUnitTest++.a'''

Alright, we have build the unit test framework in a platform independent way, no silly makefiles, no obscure M$ IDE, good old super Code::Blocks. It is time to write some code so we have something to unit test.

In the first example we will create a simple free function that checks if a a give year is a leap your or not.

The business logic is as follows : a year is a leap year when it can be divided by 4, unless itcan be divided by 100. But in case it can be divided by 400, then again it is a leap year.

In the next section we will first setup a Code::Blocks project containing both the 'functionality files, and the unit test files. Typically one will package several functionality files into a static library and create a unit test project that tests all the class/functionalities in that library package, also called a component. That is we have a component (whose deliverable is the static library, and we have a unit test project that tests the entire component).

== Our first test project environment ==
Let's create a new directory in our <TestPit> : <TestPit>/LeapYear.
For the simplicity we will put the project file and the source file all together in this directory. Normally we would work in a more structured way, but in a demo article we have some artistic freedom ;-)
Next you can create with the Code::Block's wizard a new console project in the LeapYear directory. Or you can create the following 4 files and give the the contents as specified below. Note that this demo works on linux and on windows, everything is still completely platform independent. Long Live Code::Blocks.

The project file : LeapYear.cbp (the one below already contains the 3 source files, in case you use the wizard you have to add the LeapYear.h/cpp files to the project)

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="LeapYear" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option output="Deliv/Debug/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Debug/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option output="Deliv/Release/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Release/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-O2" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<Compiler>
<Add option="-Wall" />
<Add option="-fexceptions" />
</Compiler>
<Unit filename="LeapYear.cpp" />
<Unit filename="LeapYear.h" />
<Unit filename="main.cpp" />
<Extensions>
<envvars />
<code_completion />
<lib_finder disable_auto="1" />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>

The main source file : main.cpp
int main()
{
return 0;
}

The header exporting our powerful function : LeapYear.h

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

#endif // LEAPYEAR_H_INCLUDED

And the implementation of the leap year logic : LeapYear.cpp

#include "LeapYear.h"

And finishing with the source file for the tests : LeapYearTest.cpp (currently) empty

We can already build the project, we have a nice little program that does .... nothing.

Time to move to the next section, a little word about Test Driven Development.

== Test Driven Development ==
This is a practice where new code is only added to make a failing test pass. And one only adds the code needed to make that test pass. Once that is done, a new test is added to will check the next functionality to add.
On this really simple example we will more or less practice some TDD.

So get ready, it's time for LeapYear-Step1.

== LeapYear-Step1 ==
We will turn our main.cpp into the guy in charge to carry out the tests, all we need to do is change the contents of main.cpp into this :

#include "UnitTest++.h"

int main()
{
return UnitTest::RunAllTests();
}

And add '''../UnitTest++/src''' to the compiler search directories on the project level of our LeapYear project.
And add '''../UnitTest++/Deliv/Release/libUnitTest++.a''' to the link libraries of the project

Why : well we need to link with the framework and we need to include the UnitTest++ header so we can use it's functionalities.

The line '''UnitTest::RunAllTests()''' will make sure all test encountered in our sources will be carried out.
We don't have any tests yet, nor any functionality, but go ahead build the project and run it.
This is the output :

Success: 0 tests passed
Test time: 0.00 seconds.

Great : success, but no tests yet. Well it's a start.
Time to move forward, and write our first test.

== LeapYear-Step2 ==
Test, test, but there's nothing to test. Yes, absolutely. Let's think of a test, a test that will help us in the design. Now that's a good idea. Suppose I would be the user of the uplifting problem solving leap year checking library/component ... hmmm modesty first : leap year checking '''function'''.
How would I like that function to look.
bool IsLeapYear(int Year);

Yes that seems acceptable.
So let's write a test that will call that method.
We do that by adding the following code to LeapYearTest.cpp

#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

}

Things to note :
* we include the unit test header
* it is good to put the tests in nameless namespace (will be explained later on)
* we use the TEST macro, the argument is the name of the test : OurFirstTest
* we use CHECK_EQUAL to check if the expected result (the first argument) matches the computed result (the second argument)

Time to build. Woooooops errors. The tests fails completely, it does not even build. Time to add the code needed.
In order to compiler the test file, we need to include the LeapYear.h header and have that header export our function.
Our LeapYear header will look like this now (don't forget the include in the test file, it is not shown here) :

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

bool IsLeapYear(int Year);

#endif // LEAPYEAR_H_INCLUDED

At least now it compiles, but it doesn't link yet. Duh, that because we don't have an implementation yet.
Time to provide the bare minimum of code to make the test pass.
So we change the LeapYear.cpp into :

#include "LeapYear.h"

bool IsLeapYear(int /*Year*/)
{
return true;
}

Build it, run it. Yes, we have one test passed.
Great. Let's move on.

== LeapYear-Step3 ==
Anyone having the feeling we are cheating. Well the user does not know how we wrote our code on the inside. So just to be sure the user (we) adds the following test, ending up in :

#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

TEST(OurSecondTest)
{
const bool Result = IsLeapYear(1973);
CHECK_EQUAL(false, Result);
}

}

Building is already no issue any more, we can run it. Oh boy, a test is failing.
The framework tell us something like this :
<filename>:<Line>: error: Failure in OurSecondTest: Expected 0 but was 1
FAILURE: 1 out of 2 tests failed (1 failures)
Test time: 0.00 seconds.

So we are informed of the line where the failing tests occurs, next to that it tells us what it was expecting and what the actual outcome was. And it presents a resume of the total number of tests, and how many that failed. For you scripting hackers note that FAILURE != SUCCESS.

It seems we should do some more effort and implement some real logic.

== LeapYear-Step4 ==
Let's keep it taking one step at a time. Let's start by implementing the 'divisible by 4' logic. That will already solve our tests.
So our LeapYear.cpp will now look like this :

#include "LeapYear.h"

namespace
{

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year);
}

Build, run. All tests pass. Life is great.

But those changing requirements, always the change of the requirements. Years that can be divided by 100 should not be considered as a leap year.

UnitTesting

2009-09-08T21:27:10Z

Killerbot: /* LeapYear-Step4 */

This document is under development by killerbot. Starting from 7 September 2009.

== Introduction ==
This document will describe how unit testing can be combined with the Code::Blocks IDE. It will give a hands-on example on a unit testing framework and how it can be used with Code::Blocks.

== What is Unit Testing ==
Simply put Unit Testing is the discipline and best practice of writing and running little test programs that test little units of code.
Such a unit can be :
* a class
* a free function
* an interface
* ...
There are several unit test frameworks available to help you write, deploy, manage your unit tests. The most famous family is the xUnit framework, and some of it's descendants.

== Why Unit Testing ==
Well we write code that implements some functionality. We need a way to check and prove that the implementation is correct. Therefor we need tests. We need tests on the application level, at the integration level of different components, classes, interfaces. But we also need tests for the smallest building blocks, the units.
We also wans these tests to run very quickly. That we we can run the tests often, manually or automated.
These tests will also be our safeguards during refactoring of the code, extending the code or whatever maintenance tasks we carry out on the code.
These tests will also make us think of how our class, method, ... will be used. Since the test can be seen as a user of our code. Thanks do this, thinking about the tests before implementing the functionality can help us in the design : emergent design.
It will help us to avoid creating big classes, complex functions. We will only write the methods that are really needed, and no methods that we think might (n)ever be useful in the future. We are no good future tellers ! Those 'might be needed' methods and their tests are just a waste of time. Extending, refactoring will be done when it is actually needed, and at that time we have our unit tests to ensure we don't break any existing code.

Other times to add new unit tests are typically when a bug is discovered; Write a unit test to reproduces the bug, fix the code, and from now on the new unit test will watch your back so the bug won't reappear.

Unit test are also a good place of documentation. The little tests show how the class or method is used.
The code documents itself.

So the benefits are :
* better design
* prove of your code
* safe guard during code maintenance (refactoring, extensions)
* documentation
* ...

== Unit Test frameworks ==
When writing unit tests, one will create a lot of similar code. Since unit tests are nothing more then little programs, several tasks will be repeated, setting up the test environment, create your class, call a method, verify it's result, write out an error message when the test fails, preferably specifying what the wrong outcome was, and what the expected result is.
All these repetitive chores are taken care of by the frame work so the developer can focus on the real code of the test.
This document will use a small but very effective framework for the C++ language. It is called UnitTest++. It's homepage is at : [http://unittest-cpp.sourceforge.net/ UnitTest++].
You can download it directly at this [http://sourceforge.net/projects/unittest-cpp/files/UnitTest%2B%2B/1.4/unittest-cpp-1.4.zip/download link]. At the time of writing the latest version is 1.4.

== Setup our environment ==
Let's create a directory on our PC in which we will cary out our experiments. I will refer to this directory from now on as <TestPit>. For my laptop on which I am writing this article, that will be /home/lieven/Projects/UnitTestArticle. Note that everything we will do, works on linux and on windows!
Download the "unittest-cpp-1.4.zip" file from the link specified above. Extract it in the <TestPit> directory. All the files will end up in the <TestPit>/UnitTest++ directory.

== Build UnitTest++ ==
After the extracted the zip archive we have a directory structure like this :
<TestPit>/UnitTest++
|
+docs
|
+src

The files in the UnitTest++ directory are of little use for us, since they bring project files for some bizarre Microsoft IDE ;-) .
We will create our own Code::Blocks project to build the UnitTest++ framework.

Why do we need to build something ? Well as said, the framework will do a lot of chores for us, those chores are implemented by code, that code is framework. We will build to frame work into a static library, and for every unit test (or set of unit tests) we create a little (console/shell) program with the test code we wrote, which will link with the static library to obtain a unit test executable, driven by the framework.

We will put our Code::Blocks project file in a nice structured directory tree, therefor let's create a 'Project' subdirectory in the <TestPit>/UniTest++ directory.

In there create a new file with the name "UnitTest++.cbp".
Give that file the following content :

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="UnitTest++" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option platforms="Windows;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option platforms="Windows;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
<Target title="Debug(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<VirtualTargets>
<Add alias="All" targets="Debug;Release;Debug(linux);Release(linux);" />
</VirtualTargets>
<Unit filename="../src/AssertException.cpp" />
<Unit filename="../src/AssertException.h" />
<Unit filename="../src/CheckMacros.h" />
<Unit filename="../src/Checks.cpp" />
<Unit filename="../src/Checks.h" />
<Unit filename="../src/Config.h" />
<Unit filename="../src/CurrentTest.cpp" />
<Unit filename="../src/CurrentTest.h" />
<Unit filename="../src/DeferredTestReporter.cpp" />
<Unit filename="../src/DeferredTestReporter.h" />
<Unit filename="../src/DeferredTestResult.cpp" />
<Unit filename="../src/DeferredTestResult.h" />
<Unit filename="../src/ExecuteTest.h" />
<Unit filename="../src/MemoryOutStream.cpp" />
<Unit filename="../src/MemoryOutStream.h" />
<Unit filename="../src/Posix/SignalTranslator.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/SignalTranslator.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/ReportAssert.cpp" />
<Unit filename="../src/ReportAssert.h" />
<Unit filename="../src/Test.cpp" />
<Unit filename="../src/Test.h" />
<Unit filename="../src/TestDetails.cpp" />
<Unit filename="../src/TestDetails.h" />
<Unit filename="../src/TestList.cpp" />
<Unit filename="../src/TestList.h" />
<Unit filename="../src/TestMacros.h" />
<Unit filename="../src/TestReporter.cpp" />
<Unit filename="../src/TestReporter.h" />
<Unit filename="../src/TestReporterStdout.cpp" />
<Unit filename="../src/TestReporterStdout.h" />
<Unit filename="../src/TestResults.cpp" />
<Unit filename="../src/TestResults.h" />
<Unit filename="../src/TestRunner.cpp" />
<Unit filename="../src/TestRunner.h" />
<Unit filename="../src/TestSuite.h" />
<Unit filename="../src/TimeConstraint.cpp" />
<Unit filename="../src/TimeConstraint.h" />
<Unit filename="../src/TimeHelpers.h" />
<Unit filename="../src/UnitTest++.h" />
<Unit filename="../src/Win32/TimeHelpers.cpp">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/Win32/TimeHelpers.h">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/XmlTestReporter.cpp" />
<Unit filename="../src/XmlTestReporter.h" />
<Extensions>
<envvars />
<code_completion />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>

Some things to note about the content of the project file, the power of Code::Blocks.
* there are 4 targets : Debug/Release for Windows and Debug/Release for linux [yes : 1 project file that allows building on linux and on windows]
* some files are only part of the linux targets, some only for the windows targets

But before we build, let's modify some source files (not really needed, but I prefer to have warning free compilations). These are the changes I carried out :
* ReportAssert.cpp : #include "ReportAssert.h"
* win32/TimeHelpers.cpp : first the m_threadHandle and then the m_startTime in the initializerlist

Next open up this project file in Code::Blocks and build the debug and release target. From now one we will only use the Release target, we go for speed ;-)

The result of the build process will show up in subdirectories of the new 'Deliv' subdirectory of <testPit>/UnitTest++ : '''<testPit>/UnitTest++/Deliv/Release/libUnitTest++.a'''

Alright, we have build the unit test framework in a platform independent way, no silly makefiles, no obscure M$ IDE, good old super Code::Blocks. It is time to write some code so we have something to unit test.

In the first example we will create a simple free function that checks if a a give year is a leap your or not.

The business logic is as follows : a year is a leap year when it can be divided by 4, unless itcan be divided by 100. But in case it can be divided by 400, then again it is a leap year.

In the next section we will first setup a Code::Blocks project containing both the 'functionality files, and the unit test files. Typically one will package several functionality files into a static library and create a unit test project that tests all the class/functionalities in that library package, also called a component. That is we have a component (whose deliverable is the static library, and we have a unit test project that tests the entire component).

== Our first test project environment ==
Let's create a new directory in our <TestPit> : <TestPit>/LeapYear.
For the simplicity we will put the project file and the source file all together in this directory. Normally we would work in a more structured way, but in a demo article we have some artistic freedom ;-)
Next you can create with the Code::Block's wizard a new console project in the LeapYear directory. Or you can create the following 4 files and give the the contents as specified below. Note that this demo works on linux and on windows, everything is still completely platform independent. Long Live Code::Blocks.

The project file : LeapYear.cbp (the one below already contains the 3 source files, in case you use the wizard you have to add the LeapYear.h/cpp files to the project)

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="LeapYear" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option output="Deliv/Debug/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Debug/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option output="Deliv/Release/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Release/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-O2" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<Compiler>
<Add option="-Wall" />
<Add option="-fexceptions" />
</Compiler>
<Unit filename="LeapYear.cpp" />
<Unit filename="LeapYear.h" />
<Unit filename="main.cpp" />
<Extensions>
<envvars />
<code_completion />
<lib_finder disable_auto="1" />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>

The main source file : main.cpp
int main()
{
return 0;
}

The header exporting our powerful function : LeapYear.h

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

#endif // LEAPYEAR_H_INCLUDED

And the implementation of the leap year logic : LeapYear.cpp

#include "LeapYear.h"

And finishing with the source file for the tests : LeapYearTest.cpp (currently) empty

We can already build the project, we have a nice little program that does .... nothing.

Time to move to the next section, a little word about Test Driven Development.

== Test Driven Development ==
This is a practice where new code is only added to make a failing test pass. And one only adds the code needed to make that test pass. Once that is done, a new test is added to will check the next functionality to add.
On this really simple example we will more or less practice some TDD.

So get ready, it's time for LeapYear-Step1.

== LeapYear-Step1 ==
We will turn our main.cpp into the guy in charge to carry out the tests, all we need to do is change the contents of main.cpp into this :

#include "UnitTest++.h"

int main()
{
return UnitTest::RunAllTests();
}

And add '''../UnitTest++/src''' to the compiler search directories on the project level of our LeapYear project.
And add '''../UnitTest++/Deliv/Release/libUnitTest++.a''' to the link libraries of the project

Why : well we need to link with the framework and we need to include the UnitTest++ header so we can use it's functionalities.

The line '''UnitTest::RunAllTests()''' will make sure all test encountered in our sources will be carried out.
We don't have any tests yet, nor any functionality, but go ahead build the project and run it.
This is the output :

Success: 0 tests passed
Test time: 0.00 seconds.

Great : success, but no tests yet. Well it's a start.
Time to move forward, and write our first test.

== LeapYear-Step2 ==
Test, test, but there's nothing to test. Yes, absolutely. Let's think of a test, a test that will help us in the design. Now that's a good idea. Suppose I would be the user of the uplifting problem solving leap year checking library/component ... hmmm modesty first : leap year checking '''function'''.
How would I like that function to look.
bool IsLeapYear(int Year);

Yes that seems acceptable.
So let's write a test that will call that method.
We do that by adding the following code to LeapYearTest.cpp

#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

}

Things to note :
* we include the unit test header
* it is good to put the tests in nameless namespace (will be explained later on)
* we use the TEST macro, the argument is the name of the test : OurFirstTest
* we use CHECK_EQUAL to check if the expected result (the first argument) matches the computed result (the second argument)

Time to build. Woooooops errors. The tests fails completely, it does not even build. Time to add the code needed.
In order to compiler the test file, we need to include the LeapYear.h header and have that header export our function.
Our LeapYear header will look like this now (don't forget the include in the test file, it is not shown here) :

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

bool IsLeapYear(int Year);

#endif // LEAPYEAR_H_INCLUDED

At least now it compiles, but it doesn't link yet. Duh, that because we don't have an implementation yet.
Time to provide the bare minimum of code to make the test pass.
So we change the LeapYear.cpp into :

#include "LeapYear.h"

bool IsLeapYear(int /*Year*/)
{
return true;
}

Build it, run it. Yes, we have one test passed.
Great. Let's move on.

== LeapYear-Step3 ==
Anyone having the feeling we are cheating. Well the user does not know how we wrote our code on the inside. So just to be sure the user (we) adds the following test, ending up in :

#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

TEST(OurSecondTest)
{
const bool Result = IsLeapYear(1973);
CHECK_EQUAL(false, Result);
}

}

Building is already no issue any more, we can run it. Oh boy, a test is failing.
The framework tell us something like this :
<filename>:<Line>: error: Failure in OurSecondTest: Expected 0 but was 1
FAILURE: 1 out of 2 tests failed (1 failures)
Test time: 0.00 seconds.

So we are informed of the line where the failing tests occurs, next to that it tells us what it was expecting and what the actual outcome was. And it presents a resume of the total number of tests, and how many that failed. For you scripting hackers note that FAILURE != SUCCESS.

It seems we should do some more effort and implement some real logic.

== LeapYear-Step4 ==
Let's keep it taking one step at a time. Let's start by implementing the 'divisible by 4' logic. That will already solve our tests.
So our LeapYear.cpp will now look like this :

#include "LeapYear.h"

namespace
{

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year);
}

Build, run. All tests pass. Life is great.

But those changing requirements, always the change of the requirements. Years that can be divided by 100 should not be considered as a leap year.

UnitTesting

2009-09-08T21:26:44Z

Killerbot: /* LeapYear-Step4 */

This document is under development by killerbot. Starting from 7 September 2009.

== Introduction ==
This document will describe how unit testing can be combined with the Code::Blocks IDE. It will give a hands-on example on a unit testing framework and how it can be used with Code::Blocks.

== What is Unit Testing ==
Simply put Unit Testing is the discipline and best practice of writing and running little test programs that test little units of code.
Such a unit can be :
* a class
* a free function
* an interface
* ...
There are several unit test frameworks available to help you write, deploy, manage your unit tests. The most famous family is the xUnit framework, and some of it's descendants.

== Why Unit Testing ==
Well we write code that implements some functionality. We need a way to check and prove that the implementation is correct. Therefor we need tests. We need tests on the application level, at the integration level of different components, classes, interfaces. But we also need tests for the smallest building blocks, the units.
We also wans these tests to run very quickly. That we we can run the tests often, manually or automated.
These tests will also be our safeguards during refactoring of the code, extending the code or whatever maintenance tasks we carry out on the code.
These tests will also make us think of how our class, method, ... will be used. Since the test can be seen as a user of our code. Thanks do this, thinking about the tests before implementing the functionality can help us in the design : emergent design.
It will help us to avoid creating big classes, complex functions. We will only write the methods that are really needed, and no methods that we think might (n)ever be useful in the future. We are no good future tellers ! Those 'might be needed' methods and their tests are just a waste of time. Extending, refactoring will be done when it is actually needed, and at that time we have our unit tests to ensure we don't break any existing code.

Other times to add new unit tests are typically when a bug is discovered; Write a unit test to reproduces the bug, fix the code, and from now on the new unit test will watch your back so the bug won't reappear.

Unit test are also a good place of documentation. The little tests show how the class or method is used.
The code documents itself.

So the benefits are :
* better design
* prove of your code
* safe guard during code maintenance (refactoring, extensions)
* documentation
* ...

== Unit Test frameworks ==
When writing unit tests, one will create a lot of similar code. Since unit tests are nothing more then little programs, several tasks will be repeated, setting up the test environment, create your class, call a method, verify it's result, write out an error message when the test fails, preferably specifying what the wrong outcome was, and what the expected result is.
All these repetitive chores are taken care of by the frame work so the developer can focus on the real code of the test.
This document will use a small but very effective framework for the C++ language. It is called UnitTest++. It's homepage is at : [http://unittest-cpp.sourceforge.net/ UnitTest++].
You can download it directly at this [http://sourceforge.net/projects/unittest-cpp/files/UnitTest%2B%2B/1.4/unittest-cpp-1.4.zip/download link]. At the time of writing the latest version is 1.4.

== Setup our environment ==
Let's create a directory on our PC in which we will cary out our experiments. I will refer to this directory from now on as <TestPit>. For my laptop on which I am writing this article, that will be /home/lieven/Projects/UnitTestArticle. Note that everything we will do, works on linux and on windows!
Download the "unittest-cpp-1.4.zip" file from the link specified above. Extract it in the <TestPit> directory. All the files will end up in the <TestPit>/UnitTest++ directory.

== Build UnitTest++ ==
After the extracted the zip archive we have a directory structure like this :
<TestPit>/UnitTest++
|
+docs
|
+src

The files in the UnitTest++ directory are of little use for us, since they bring project files for some bizarre Microsoft IDE ;-) .
We will create our own Code::Blocks project to build the UnitTest++ framework.

Why do we need to build something ? Well as said, the framework will do a lot of chores for us, those chores are implemented by code, that code is framework. We will build to frame work into a static library, and for every unit test (or set of unit tests) we create a little (console/shell) program with the test code we wrote, which will link with the static library to obtain a unit test executable, driven by the framework.

We will put our Code::Blocks project file in a nice structured directory tree, therefor let's create a 'Project' subdirectory in the <TestPit>/UniTest++ directory.

In there create a new file with the name "UnitTest++.cbp".
Give that file the following content :

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="UnitTest++" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option platforms="Windows;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option platforms="Windows;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
<Target title="Debug(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<VirtualTargets>
<Add alias="All" targets="Debug;Release;Debug(linux);Release(linux);" />
</VirtualTargets>
<Unit filename="../src/AssertException.cpp" />
<Unit filename="../src/AssertException.h" />
<Unit filename="../src/CheckMacros.h" />
<Unit filename="../src/Checks.cpp" />
<Unit filename="../src/Checks.h" />
<Unit filename="../src/Config.h" />
<Unit filename="../src/CurrentTest.cpp" />
<Unit filename="../src/CurrentTest.h" />
<Unit filename="../src/DeferredTestReporter.cpp" />
<Unit filename="../src/DeferredTestReporter.h" />
<Unit filename="../src/DeferredTestResult.cpp" />
<Unit filename="../src/DeferredTestResult.h" />
<Unit filename="../src/ExecuteTest.h" />
<Unit filename="../src/MemoryOutStream.cpp" />
<Unit filename="../src/MemoryOutStream.h" />
<Unit filename="../src/Posix/SignalTranslator.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/SignalTranslator.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/ReportAssert.cpp" />
<Unit filename="../src/ReportAssert.h" />
<Unit filename="../src/Test.cpp" />
<Unit filename="../src/Test.h" />
<Unit filename="../src/TestDetails.cpp" />
<Unit filename="../src/TestDetails.h" />
<Unit filename="../src/TestList.cpp" />
<Unit filename="../src/TestList.h" />
<Unit filename="../src/TestMacros.h" />
<Unit filename="../src/TestReporter.cpp" />
<Unit filename="../src/TestReporter.h" />
<Unit filename="../src/TestReporterStdout.cpp" />
<Unit filename="../src/TestReporterStdout.h" />
<Unit filename="../src/TestResults.cpp" />
<Unit filename="../src/TestResults.h" />
<Unit filename="../src/TestRunner.cpp" />
<Unit filename="../src/TestRunner.h" />
<Unit filename="../src/TestSuite.h" />
<Unit filename="../src/TimeConstraint.cpp" />
<Unit filename="../src/TimeConstraint.h" />
<Unit filename="../src/TimeHelpers.h" />
<Unit filename="../src/UnitTest++.h" />
<Unit filename="../src/Win32/TimeHelpers.cpp">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/Win32/TimeHelpers.h">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/XmlTestReporter.cpp" />
<Unit filename="../src/XmlTestReporter.h" />
<Extensions>
<envvars />
<code_completion />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>

Some things to note about the content of the project file, the power of Code::Blocks.
* there are 4 targets : Debug/Release for Windows and Debug/Release for linux [yes : 1 project file that allows building on linux and on windows]
* some files are only part of the linux targets, some only for the windows targets

But before we build, let's modify some source files (not really needed, but I prefer to have warning free compilations). These are the changes I carried out :
* ReportAssert.cpp : #include "ReportAssert.h"
* win32/TimeHelpers.cpp : first the m_threadHandle and then the m_startTime in the initializerlist

Next open up this project file in Code::Blocks and build the debug and release target. From now one we will only use the Release target, we go for speed ;-)

The result of the build process will show up in subdirectories of the new 'Deliv' subdirectory of <testPit>/UnitTest++ : '''<testPit>/UnitTest++/Deliv/Release/libUnitTest++.a'''

Alright, we have build the unit test framework in a platform independent way, no silly makefiles, no obscure M$ IDE, good old super Code::Blocks. It is time to write some code so we have something to unit test.

In the first example we will create a simple free function that checks if a a give year is a leap your or not.

The business logic is as follows : a year is a leap year when it can be divided by 4, unless itcan be divided by 100. But in case it can be divided by 400, then again it is a leap year.

In the next section we will first setup a Code::Blocks project containing both the 'functionality files, and the unit test files. Typically one will package several functionality files into a static library and create a unit test project that tests all the class/functionalities in that library package, also called a component. That is we have a component (whose deliverable is the static library, and we have a unit test project that tests the entire component).

== Our first test project environment ==
Let's create a new directory in our <TestPit> : <TestPit>/LeapYear.
For the simplicity we will put the project file and the source file all together in this directory. Normally we would work in a more structured way, but in a demo article we have some artistic freedom ;-)
Next you can create with the Code::Block's wizard a new console project in the LeapYear directory. Or you can create the following 4 files and give the the contents as specified below. Note that this demo works on linux and on windows, everything is still completely platform independent. Long Live Code::Blocks.

The project file : LeapYear.cbp (the one below already contains the 3 source files, in case you use the wizard you have to add the LeapYear.h/cpp files to the project)

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="LeapYear" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option output="Deliv/Debug/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Debug/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option output="Deliv/Release/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Release/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-O2" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<Compiler>
<Add option="-Wall" />
<Add option="-fexceptions" />
</Compiler>
<Unit filename="LeapYear.cpp" />
<Unit filename="LeapYear.h" />
<Unit filename="main.cpp" />
<Extensions>
<envvars />
<code_completion />
<lib_finder disable_auto="1" />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>

The main source file : main.cpp
int main()
{
return 0;
}

The header exporting our powerful function : LeapYear.h

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

#endif // LEAPYEAR_H_INCLUDED

And the implementation of the leap year logic : LeapYear.cpp

#include "LeapYear.h"

And finishing with the source file for the tests : LeapYearTest.cpp (currently) empty

We can already build the project, we have a nice little program that does .... nothing.

Time to move to the next section, a little word about Test Driven Development.

== Test Driven Development ==
This is a practice where new code is only added to make a failing test pass. And one only adds the code needed to make that test pass. Once that is done, a new test is added to will check the next functionality to add.
On this really simple example we will more or less practice some TDD.

So get ready, it's time for LeapYear-Step1.

== LeapYear-Step1 ==
We will turn our main.cpp into the guy in charge to carry out the tests, all we need to do is change the contents of main.cpp into this :

#include "UnitTest++.h"

int main()
{
return UnitTest::RunAllTests();
}

And add '''../UnitTest++/src''' to the compiler search directories on the project level of our LeapYear project.
And add '''../UnitTest++/Deliv/Release/libUnitTest++.a''' to the link libraries of the project

Why : well we need to link with the framework and we need to include the UnitTest++ header so we can use it's functionalities.

The line '''UnitTest::RunAllTests()''' will make sure all test encountered in our sources will be carried out.
We don't have any tests yet, nor any functionality, but go ahead build the project and run it.
This is the output :

Success: 0 tests passed
Test time: 0.00 seconds.

Great : success, but no tests yet. Well it's a start.
Time to move forward, and write our first test.

== LeapYear-Step2 ==
Test, test, but there's nothing to test. Yes, absolutely. Let's think of a test, a test that will help us in the design. Now that's a good idea. Suppose I would be the user of the uplifting problem solving leap year checking library/component ... hmmm modesty first : leap year checking '''function'''.
How would I like that function to look.
bool IsLeapYear(int Year);

Yes that seems acceptable.
So let's write a test that will call that method.
We do that by adding the following code to LeapYearTest.cpp

#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

}

Things to note :
* we include the unit test header
* it is good to put the tests in nameless namespace (will be explained later on)
* we use the TEST macro, the argument is the name of the test : OurFirstTest
* we use CHECK_EQUAL to check if the expected result (the first argument) matches the computed result (the second argument)

Time to build. Woooooops errors. The tests fails completely, it does not even build. Time to add the code needed.
In order to compiler the test file, we need to include the LeapYear.h header and have that header export our function.
Our LeapYear header will look like this now (don't forget the include in the test file, it is not shown here) :

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

bool IsLeapYear(int Year);

#endif // LEAPYEAR_H_INCLUDED

At least now it compiles, but it doesn't link yet. Duh, that because we don't have an implementation yet.
Time to provide the bare minimum of code to make the test pass.
So we change the LeapYear.cpp into :

#include "LeapYear.h"

bool IsLeapYear(int /*Year*/)
{
return true;
}

Build it, run it. Yes, we have one test passed.
Great. Let's move on.

== LeapYear-Step3 ==
Anyone having the feeling we are cheating. Well the user does not know how we wrote our code on the inside. So just to be sure the user (we) adds the following test, ending up in :

#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

TEST(OurSecondTest)
{
const bool Result = IsLeapYear(1973);
CHECK_EQUAL(false, Result);
}

}

Building is already no issue any more, we can run it. Oh boy, a test is failing.
The framework tell us something like this :
<filename>:<Line>: error: Failure in OurSecondTest: Expected 0 but was 1
FAILURE: 1 out of 2 tests failed (1 failures)
Test time: 0.00 seconds.

So we are informed of the line where the failing tests occurs, next to that it tells us what it was expecting and what the actual outcome was. And it presents a resume of the total number of tests, and how many that failed. For you scripting hackers note that FAILURE != SUCCESS.

It seems we should do some more effort and implement some real logic.

== LeapYear-Step4 ==
Let's keep it taking one step at a time. Let's start by implementing the 'divisible by 4' logic. That will already solve our tests.
So our LeapYear.cpp will now look like this :

#include "LeapYear.h"

namespace
{

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year);
}

Build, run. All tests pass. Life is great.

But those changing requirements, always the change the requirements. Years that can be divided by 100 should not be considered as a leap year.

UnitTesting

2009-09-08T21:26:06Z

Killerbot: /* LeapYear-Step3 */

This document is under development by killerbot. Starting from 7 September 2009.

== Introduction ==
This document will describe how unit testing can be combined with the Code::Blocks IDE. It will give a hands-on example on a unit testing framework and how it can be used with Code::Blocks.

== What is Unit Testing ==
Simply put Unit Testing is the discipline and best practice of writing and running little test programs that test little units of code.
Such a unit can be :
* a class
* a free function
* an interface
* ...
There are several unit test frameworks available to help you write, deploy, manage your unit tests. The most famous family is the xUnit framework, and some of it's descendants.

== Why Unit Testing ==
Well we write code that implements some functionality. We need a way to check and prove that the implementation is correct. Therefor we need tests. We need tests on the application level, at the integration level of different components, classes, interfaces. But we also need tests for the smallest building blocks, the units.
We also wans these tests to run very quickly. That we we can run the tests often, manually or automated.
These tests will also be our safeguards during refactoring of the code, extending the code or whatever maintenance tasks we carry out on the code.
These tests will also make us think of how our class, method, ... will be used. Since the test can be seen as a user of our code. Thanks do this, thinking about the tests before implementing the functionality can help us in the design : emergent design.
It will help us to avoid creating big classes, complex functions. We will only write the methods that are really needed, and no methods that we think might (n)ever be useful in the future. We are no good future tellers ! Those 'might be needed' methods and their tests are just a waste of time. Extending, refactoring will be done when it is actually needed, and at that time we have our unit tests to ensure we don't break any existing code.

Other times to add new unit tests are typically when a bug is discovered; Write a unit test to reproduces the bug, fix the code, and from now on the new unit test will watch your back so the bug won't reappear.

Unit test are also a good place of documentation. The little tests show how the class or method is used.
The code documents itself.

So the benefits are :
* better design
* prove of your code
* safe guard during code maintenance (refactoring, extensions)
* documentation
* ...

== Unit Test frameworks ==
When writing unit tests, one will create a lot of similar code. Since unit tests are nothing more then little programs, several tasks will be repeated, setting up the test environment, create your class, call a method, verify it's result, write out an error message when the test fails, preferably specifying what the wrong outcome was, and what the expected result is.
All these repetitive chores are taken care of by the frame work so the developer can focus on the real code of the test.
This document will use a small but very effective framework for the C++ language. It is called UnitTest++. It's homepage is at : [http://unittest-cpp.sourceforge.net/ UnitTest++].
You can download it directly at this [http://sourceforge.net/projects/unittest-cpp/files/UnitTest%2B%2B/1.4/unittest-cpp-1.4.zip/download link]. At the time of writing the latest version is 1.4.

== Setup our environment ==
Let's create a directory on our PC in which we will cary out our experiments. I will refer to this directory from now on as <TestPit>. For my laptop on which I am writing this article, that will be /home/lieven/Projects/UnitTestArticle. Note that everything we will do, works on linux and on windows!
Download the "unittest-cpp-1.4.zip" file from the link specified above. Extract it in the <TestPit> directory. All the files will end up in the <TestPit>/UnitTest++ directory.

== Build UnitTest++ ==
After the extracted the zip archive we have a directory structure like this :
<TestPit>/UnitTest++
|
+docs
|
+src

The files in the UnitTest++ directory are of little use for us, since they bring project files for some bizarre Microsoft IDE ;-) .
We will create our own Code::Blocks project to build the UnitTest++ framework.

Why do we need to build something ? Well as said, the framework will do a lot of chores for us, those chores are implemented by code, that code is framework. We will build to frame work into a static library, and for every unit test (or set of unit tests) we create a little (console/shell) program with the test code we wrote, which will link with the static library to obtain a unit test executable, driven by the framework.

We will put our Code::Blocks project file in a nice structured directory tree, therefor let's create a 'Project' subdirectory in the <TestPit>/UniTest++ directory.

In there create a new file with the name "UnitTest++.cbp".
Give that file the following content :

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="UnitTest++" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option platforms="Windows;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option platforms="Windows;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
<Target title="Debug(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<VirtualTargets>
<Add alias="All" targets="Debug;Release;Debug(linux);Release(linux);" />
</VirtualTargets>
<Unit filename="../src/AssertException.cpp" />
<Unit filename="../src/AssertException.h" />
<Unit filename="../src/CheckMacros.h" />
<Unit filename="../src/Checks.cpp" />
<Unit filename="../src/Checks.h" />
<Unit filename="../src/Config.h" />
<Unit filename="../src/CurrentTest.cpp" />
<Unit filename="../src/CurrentTest.h" />
<Unit filename="../src/DeferredTestReporter.cpp" />
<Unit filename="../src/DeferredTestReporter.h" />
<Unit filename="../src/DeferredTestResult.cpp" />
<Unit filename="../src/DeferredTestResult.h" />
<Unit filename="../src/ExecuteTest.h" />
<Unit filename="../src/MemoryOutStream.cpp" />
<Unit filename="../src/MemoryOutStream.h" />
<Unit filename="../src/Posix/SignalTranslator.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/SignalTranslator.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/ReportAssert.cpp" />
<Unit filename="../src/ReportAssert.h" />
<Unit filename="../src/Test.cpp" />
<Unit filename="../src/Test.h" />
<Unit filename="../src/TestDetails.cpp" />
<Unit filename="../src/TestDetails.h" />
<Unit filename="../src/TestList.cpp" />
<Unit filename="../src/TestList.h" />
<Unit filename="../src/TestMacros.h" />
<Unit filename="../src/TestReporter.cpp" />
<Unit filename="../src/TestReporter.h" />
<Unit filename="../src/TestReporterStdout.cpp" />
<Unit filename="../src/TestReporterStdout.h" />
<Unit filename="../src/TestResults.cpp" />
<Unit filename="../src/TestResults.h" />
<Unit filename="../src/TestRunner.cpp" />
<Unit filename="../src/TestRunner.h" />
<Unit filename="../src/TestSuite.h" />
<Unit filename="../src/TimeConstraint.cpp" />
<Unit filename="../src/TimeConstraint.h" />
<Unit filename="../src/TimeHelpers.h" />
<Unit filename="../src/UnitTest++.h" />
<Unit filename="../src/Win32/TimeHelpers.cpp">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/Win32/TimeHelpers.h">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/XmlTestReporter.cpp" />
<Unit filename="../src/XmlTestReporter.h" />
<Extensions>
<envvars />
<code_completion />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>

Some things to note about the content of the project file, the power of Code::Blocks.
* there are 4 targets : Debug/Release for Windows and Debug/Release for linux [yes : 1 project file that allows building on linux and on windows]
* some files are only part of the linux targets, some only for the windows targets

But before we build, let's modify some source files (not really needed, but I prefer to have warning free compilations). These are the changes I carried out :
* ReportAssert.cpp : #include "ReportAssert.h"
* win32/TimeHelpers.cpp : first the m_threadHandle and then the m_startTime in the initializerlist

Next open up this project file in Code::Blocks and build the debug and release target. From now one we will only use the Release target, we go for speed ;-)

The result of the build process will show up in subdirectories of the new 'Deliv' subdirectory of <testPit>/UnitTest++ : '''<testPit>/UnitTest++/Deliv/Release/libUnitTest++.a'''

Alright, we have build the unit test framework in a platform independent way, no silly makefiles, no obscure M$ IDE, good old super Code::Blocks. It is time to write some code so we have something to unit test.

In the first example we will create a simple free function that checks if a a give year is a leap your or not.

The business logic is as follows : a year is a leap year when it can be divided by 4, unless itcan be divided by 100. But in case it can be divided by 400, then again it is a leap year.

In the next section we will first setup a Code::Blocks project containing both the 'functionality files, and the unit test files. Typically one will package several functionality files into a static library and create a unit test project that tests all the class/functionalities in that library package, also called a component. That is we have a component (whose deliverable is the static library, and we have a unit test project that tests the entire component).

== Our first test project environment ==
Let's create a new directory in our <TestPit> : <TestPit>/LeapYear.
For the simplicity we will put the project file and the source file all together in this directory. Normally we would work in a more structured way, but in a demo article we have some artistic freedom ;-)
Next you can create with the Code::Block's wizard a new console project in the LeapYear directory. Or you can create the following 4 files and give the the contents as specified below. Note that this demo works on linux and on windows, everything is still completely platform independent. Long Live Code::Blocks.

The project file : LeapYear.cbp (the one below already contains the 3 source files, in case you use the wizard you have to add the LeapYear.h/cpp files to the project)

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="LeapYear" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option output="Deliv/Debug/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Debug/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option output="Deliv/Release/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Release/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-O2" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<Compiler>
<Add option="-Wall" />
<Add option="-fexceptions" />
</Compiler>
<Unit filename="LeapYear.cpp" />
<Unit filename="LeapYear.h" />
<Unit filename="main.cpp" />
<Extensions>
<envvars />
<code_completion />
<lib_finder disable_auto="1" />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>

The main source file : main.cpp
int main()
{
return 0;
}

The header exporting our powerful function : LeapYear.h

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

#endif // LEAPYEAR_H_INCLUDED

And the implementation of the leap year logic : LeapYear.cpp

#include "LeapYear.h"

And finishing with the source file for the tests : LeapYearTest.cpp (currently) empty

We can already build the project, we have a nice little program that does .... nothing.

Time to move to the next section, a little word about Test Driven Development.

== Test Driven Development ==
This is a practice where new code is only added to make a failing test pass. And one only adds the code needed to make that test pass. Once that is done, a new test is added to will check the next functionality to add.
On this really simple example we will more or less practice some TDD.

So get ready, it's time for LeapYear-Step1.

== LeapYear-Step1 ==
We will turn our main.cpp into the guy in charge to carry out the tests, all we need to do is change the contents of main.cpp into this :

#include "UnitTest++.h"

int main()
{
return UnitTest::RunAllTests();
}

And add '''../UnitTest++/src''' to the compiler search directories on the project level of our LeapYear project.
And add '''../UnitTest++/Deliv/Release/libUnitTest++.a''' to the link libraries of the project

Why : well we need to link with the framework and we need to include the UnitTest++ header so we can use it's functionalities.

The line '''UnitTest::RunAllTests()''' will make sure all test encountered in our sources will be carried out.
We don't have any tests yet, nor any functionality, but go ahead build the project and run it.
This is the output :

Success: 0 tests passed
Test time: 0.00 seconds.

Great : success, but no tests yet. Well it's a start.
Time to move forward, and write our first test.

== LeapYear-Step2 ==
Test, test, but there's nothing to test. Yes, absolutely. Let's think of a test, a test that will help us in the design. Now that's a good idea. Suppose I would be the user of the uplifting problem solving leap year checking library/component ... hmmm modesty first : leap year checking '''function'''.
How would I like that function to look.
bool IsLeapYear(int Year);

Yes that seems acceptable.
So let's write a test that will call that method.
We do that by adding the following code to LeapYearTest.cpp

#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

}

Things to note :
* we include the unit test header
* it is good to put the tests in nameless namespace (will be explained later on)
* we use the TEST macro, the argument is the name of the test : OurFirstTest
* we use CHECK_EQUAL to check if the expected result (the first argument) matches the computed result (the second argument)

Time to build. Woooooops errors. The tests fails completely, it does not even build. Time to add the code needed.
In order to compiler the test file, we need to include the LeapYear.h header and have that header export our function.
Our LeapYear header will look like this now (don't forget the include in the test file, it is not shown here) :

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

bool IsLeapYear(int Year);

#endif // LEAPYEAR_H_INCLUDED

At least now it compiles, but it doesn't link yet. Duh, that because we don't have an implementation yet.
Time to provide the bare minimum of code to make the test pass.
So we change the LeapYear.cpp into :

#include "LeapYear.h"

bool IsLeapYear(int /*Year*/)
{
return true;
}

Build it, run it. Yes, we have one test passed.
Great. Let's move on.

== LeapYear-Step3 ==
Anyone having the feeling we are cheating. Well the user does not know how we wrote our code on the inside. So just to be sure the user (we) adds the following test, ending up in :

#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

TEST(OurSecondTest)
{
const bool Result = IsLeapYear(1973);
CHECK_EQUAL(false, Result);
}

}

Building is already no issue any more, we can run it. Oh boy, a test is failing.
The framework tell us something like this :
<filename>:<Line>: error: Failure in OurSecondTest: Expected 0 but was 1
FAILURE: 1 out of 2 tests failed (1 failures)
Test time: 0.00 seconds.

So we are informed of the line where the failing tests occurs, next to that it tells us what it was expecting and what the actual outcome was. And it presents a resume of the total number of tests, and how many that failed. For you scripting hackers note that FAILURE != SUCCESS.

It seems we should do some more effort and implement some real logic.

== LeapYear-Step4 ==
Let's keep it taking one step at a time. Let's start by implementing the 'divisible by 4' logic. That will already solve our tests.
So our LeapYear.cpp will now look like this :

#include "LeapYear.h"

namespace
{

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year);
}

Build, run. All test pass. Life is great.

But those changing requirements, always the change the requirements. Years that can be divided by 100 should not be considered as a leap year.

UnitTesting

2009-09-08T21:25:39Z

Killerbot: /* LeapYear-Step3 */

This document is under development by killerbot. Starting from 7 September 2009.

== Introduction ==
This document will describe how unit testing can be combined with the Code::Blocks IDE. It will give a hands-on example on a unit testing framework and how it can be used with Code::Blocks.

== What is Unit Testing ==
Simply put Unit Testing is the discipline and best practice of writing and running little test programs that test little units of code.
Such a unit can be :
* a class
* a free function
* an interface
* ...
There are several unit test frameworks available to help you write, deploy, manage your unit tests. The most famous family is the xUnit framework, and some of it's descendants.

== Why Unit Testing ==
Well we write code that implements some functionality. We need a way to check and prove that the implementation is correct. Therefor we need tests. We need tests on the application level, at the integration level of different components, classes, interfaces. But we also need tests for the smallest building blocks, the units.
We also wans these tests to run very quickly. That we we can run the tests often, manually or automated.
These tests will also be our safeguards during refactoring of the code, extending the code or whatever maintenance tasks we carry out on the code.
These tests will also make us think of how our class, method, ... will be used. Since the test can be seen as a user of our code. Thanks do this, thinking about the tests before implementing the functionality can help us in the design : emergent design.
It will help us to avoid creating big classes, complex functions. We will only write the methods that are really needed, and no methods that we think might (n)ever be useful in the future. We are no good future tellers ! Those 'might be needed' methods and their tests are just a waste of time. Extending, refactoring will be done when it is actually needed, and at that time we have our unit tests to ensure we don't break any existing code.

Other times to add new unit tests are typically when a bug is discovered; Write a unit test to reproduces the bug, fix the code, and from now on the new unit test will watch your back so the bug won't reappear.

Unit test are also a good place of documentation. The little tests show how the class or method is used.
The code documents itself.

So the benefits are :
* better design
* prove of your code
* safe guard during code maintenance (refactoring, extensions)
* documentation
* ...

== Unit Test frameworks ==
When writing unit tests, one will create a lot of similar code. Since unit tests are nothing more then little programs, several tasks will be repeated, setting up the test environment, create your class, call a method, verify it's result, write out an error message when the test fails, preferably specifying what the wrong outcome was, and what the expected result is.
All these repetitive chores are taken care of by the frame work so the developer can focus on the real code of the test.
This document will use a small but very effective framework for the C++ language. It is called UnitTest++. It's homepage is at : [http://unittest-cpp.sourceforge.net/ UnitTest++].
You can download it directly at this [http://sourceforge.net/projects/unittest-cpp/files/UnitTest%2B%2B/1.4/unittest-cpp-1.4.zip/download link]. At the time of writing the latest version is 1.4.

== Setup our environment ==
Let's create a directory on our PC in which we will cary out our experiments. I will refer to this directory from now on as <TestPit>. For my laptop on which I am writing this article, that will be /home/lieven/Projects/UnitTestArticle. Note that everything we will do, works on linux and on windows!
Download the "unittest-cpp-1.4.zip" file from the link specified above. Extract it in the <TestPit> directory. All the files will end up in the <TestPit>/UnitTest++ directory.

== Build UnitTest++ ==
After the extracted the zip archive we have a directory structure like this :
<TestPit>/UnitTest++
|
+docs
|
+src

The files in the UnitTest++ directory are of little use for us, since they bring project files for some bizarre Microsoft IDE ;-) .
We will create our own Code::Blocks project to build the UnitTest++ framework.

Why do we need to build something ? Well as said, the framework will do a lot of chores for us, those chores are implemented by code, that code is framework. We will build to frame work into a static library, and for every unit test (or set of unit tests) we create a little (console/shell) program with the test code we wrote, which will link with the static library to obtain a unit test executable, driven by the framework.

We will put our Code::Blocks project file in a nice structured directory tree, therefor let's create a 'Project' subdirectory in the <TestPit>/UniTest++ directory.

In there create a new file with the name "UnitTest++.cbp".
Give that file the following content :

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="UnitTest++" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option platforms="Windows;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option platforms="Windows;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
<Target title="Debug(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<VirtualTargets>
<Add alias="All" targets="Debug;Release;Debug(linux);Release(linux);" />
</VirtualTargets>
<Unit filename="../src/AssertException.cpp" />
<Unit filename="../src/AssertException.h" />
<Unit filename="../src/CheckMacros.h" />
<Unit filename="../src/Checks.cpp" />
<Unit filename="../src/Checks.h" />
<Unit filename="../src/Config.h" />
<Unit filename="../src/CurrentTest.cpp" />
<Unit filename="../src/CurrentTest.h" />
<Unit filename="../src/DeferredTestReporter.cpp" />
<Unit filename="../src/DeferredTestReporter.h" />
<Unit filename="../src/DeferredTestResult.cpp" />
<Unit filename="../src/DeferredTestResult.h" />
<Unit filename="../src/ExecuteTest.h" />
<Unit filename="../src/MemoryOutStream.cpp" />
<Unit filename="../src/MemoryOutStream.h" />
<Unit filename="../src/Posix/SignalTranslator.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/SignalTranslator.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/ReportAssert.cpp" />
<Unit filename="../src/ReportAssert.h" />
<Unit filename="../src/Test.cpp" />
<Unit filename="../src/Test.h" />
<Unit filename="../src/TestDetails.cpp" />
<Unit filename="../src/TestDetails.h" />
<Unit filename="../src/TestList.cpp" />
<Unit filename="../src/TestList.h" />
<Unit filename="../src/TestMacros.h" />
<Unit filename="../src/TestReporter.cpp" />
<Unit filename="../src/TestReporter.h" />
<Unit filename="../src/TestReporterStdout.cpp" />
<Unit filename="../src/TestReporterStdout.h" />
<Unit filename="../src/TestResults.cpp" />
<Unit filename="../src/TestResults.h" />
<Unit filename="../src/TestRunner.cpp" />
<Unit filename="../src/TestRunner.h" />
<Unit filename="../src/TestSuite.h" />
<Unit filename="../src/TimeConstraint.cpp" />
<Unit filename="../src/TimeConstraint.h" />
<Unit filename="../src/TimeHelpers.h" />
<Unit filename="../src/UnitTest++.h" />
<Unit filename="../src/Win32/TimeHelpers.cpp">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/Win32/TimeHelpers.h">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/XmlTestReporter.cpp" />
<Unit filename="../src/XmlTestReporter.h" />
<Extensions>
<envvars />
<code_completion />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>

Some things to note about the content of the project file, the power of Code::Blocks.
* there are 4 targets : Debug/Release for Windows and Debug/Release for linux [yes : 1 project file that allows building on linux and on windows]
* some files are only part of the linux targets, some only for the windows targets

But before we build, let's modify some source files (not really needed, but I prefer to have warning free compilations). These are the changes I carried out :
* ReportAssert.cpp : #include "ReportAssert.h"
* win32/TimeHelpers.cpp : first the m_threadHandle and then the m_startTime in the initializerlist

Next open up this project file in Code::Blocks and build the debug and release target. From now one we will only use the Release target, we go for speed ;-)

The result of the build process will show up in subdirectories of the new 'Deliv' subdirectory of <testPit>/UnitTest++ : '''<testPit>/UnitTest++/Deliv/Release/libUnitTest++.a'''

Alright, we have build the unit test framework in a platform independent way, no silly makefiles, no obscure M$ IDE, good old super Code::Blocks. It is time to write some code so we have something to unit test.

In the first example we will create a simple free function that checks if a a give year is a leap your or not.

The business logic is as follows : a year is a leap year when it can be divided by 4, unless itcan be divided by 100. But in case it can be divided by 400, then again it is a leap year.

In the next section we will first setup a Code::Blocks project containing both the 'functionality files, and the unit test files. Typically one will package several functionality files into a static library and create a unit test project that tests all the class/functionalities in that library package, also called a component. That is we have a component (whose deliverable is the static library, and we have a unit test project that tests the entire component).

== Our first test project environment ==
Let's create a new directory in our <TestPit> : <TestPit>/LeapYear.
For the simplicity we will put the project file and the source file all together in this directory. Normally we would work in a more structured way, but in a demo article we have some artistic freedom ;-)
Next you can create with the Code::Block's wizard a new console project in the LeapYear directory. Or you can create the following 4 files and give the the contents as specified below. Note that this demo works on linux and on windows, everything is still completely platform independent. Long Live Code::Blocks.

The project file : LeapYear.cbp (the one below already contains the 3 source files, in case you use the wizard you have to add the LeapYear.h/cpp files to the project)

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="LeapYear" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option output="Deliv/Debug/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Debug/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option output="Deliv/Release/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Release/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-O2" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<Compiler>
<Add option="-Wall" />
<Add option="-fexceptions" />
</Compiler>
<Unit filename="LeapYear.cpp" />
<Unit filename="LeapYear.h" />
<Unit filename="main.cpp" />
<Extensions>
<envvars />
<code_completion />
<lib_finder disable_auto="1" />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>

The main source file : main.cpp
int main()
{
return 0;
}

The header exporting our powerful function : LeapYear.h

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

#endif // LEAPYEAR_H_INCLUDED

And the implementation of the leap year logic : LeapYear.cpp

#include "LeapYear.h"

And finishing with the source file for the tests : LeapYearTest.cpp (currently) empty

We can already build the project, we have a nice little program that does .... nothing.

Time to move to the next section, a little word about Test Driven Development.

== Test Driven Development ==
This is a practice where new code is only added to make a failing test pass. And one only adds the code needed to make that test pass. Once that is done, a new test is added to will check the next functionality to add.
On this really simple example we will more or less practice some TDD.

So get ready, it's time for LeapYear-Step1.

== LeapYear-Step1 ==
We will turn our main.cpp into the guy in charge to carry out the tests, all we need to do is change the contents of main.cpp into this :

#include "UnitTest++.h"

int main()
{
return UnitTest::RunAllTests();
}

And add '''../UnitTest++/src''' to the compiler search directories on the project level of our LeapYear project.
And add '''../UnitTest++/Deliv/Release/libUnitTest++.a''' to the link libraries of the project

Why : well we need to link with the framework and we need to include the UnitTest++ header so we can use it's functionalities.

The line '''UnitTest::RunAllTests()''' will make sure all test encountered in our sources will be carried out.
We don't have any tests yet, nor any functionality, but go ahead build the project and run it.
This is the output :

Success: 0 tests passed
Test time: 0.00 seconds.

Great : success, but no tests yet. Well it's a start.
Time to move forward, and write our first test.

== LeapYear-Step2 ==
Test, test, but there's nothing to test. Yes, absolutely. Let's think of a test, a test that will help us in the design. Now that's a good idea. Suppose I would be the user of the uplifting problem solving leap year checking library/component ... hmmm modesty first : leap year checking '''function'''.
How would I like that function to look.
bool IsLeapYear(int Year);

Yes that seems acceptable.
So let's write a test that will call that method.
We do that by adding the following code to LeapYearTest.cpp

#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

}

Things to note :
* we include the unit test header
* it is good to put the tests in nameless namespace (will be explained later on)
* we use the TEST macro, the argument is the name of the test : OurFirstTest
* we use CHECK_EQUAL to check if the expected result (the first argument) matches the computed result (the second argument)

Time to build. Woooooops errors. The tests fails completely, it does not even build. Time to add the code needed.
In order to compiler the test file, we need to include the LeapYear.h header and have that header export our function.
Our LeapYear header will look like this now (don't forget the include in the test file, it is not shown here) :

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

bool IsLeapYear(int Year);

#endif // LEAPYEAR_H_INCLUDED

At least now it compiles, but it doesn't link yet. Duh, that because we don't have an implementation yet.
Time to provide the bare minimum of code to make the test pass.
So we change the LeapYear.cpp into :

#include "LeapYear.h"

bool IsLeapYear(int /*Year*/)
{
return true;
}

Build it, run it. Yes, we have one test passed.
Great. Let's move on.

== LeapYear-Step3 ==
Anyone having the feeling we are cheating. Well the user does not know how we wrote our code on the inside. So just to be sure the user (we) adds the following test, ending up in :

#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

TEST(OurSecondTest)
{
const bool Result = IsLeapYear(1973);
CHECK_EQUAL(false, Result);
}

}

Building is already no issue any more, we can run it. Oh boy, a test is failing.
The framework tell us something like this :
<filename>:<Line>: error: Failure in OurSecondTest: Expected 0 but was 1
FAILURE: 1 out of 2 tests failed (1 failures)
Test time: 0.00 seconds.

So we are informed of the line were the failing tests occurs, next to that it tells us what it was expecting and what the actual outcome was. And it presents a resume of the total number of tests, and how many that failed. For you scripting hackers note that FAILURE != SUCCESS.

It seems we should do some more effort and implement some real logic.

== LeapYear-Step4 ==
Let's keep it taking one step at a time. Let's start by implementing the 'divisible by 4' logic. That will already solve our tests.
So our LeapYear.cpp will now look like this :

#include "LeapYear.h"

namespace
{

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year);
}

Build, run. All test pass. Life is great.

But those changing requirements, always the change the requirements. Years that can be divided by 100 should not be considered as a leap year.

UnitTesting

2009-09-08T21:25:15Z

Killerbot: /* LeapYear-Step2 */

This document is under development by killerbot. Starting from 7 September 2009.

== Introduction ==
This document will describe how unit testing can be combined with the Code::Blocks IDE. It will give a hands-on example on a unit testing framework and how it can be used with Code::Blocks.

== What is Unit Testing ==
Simply put Unit Testing is the discipline and best practice of writing and running little test programs that test little units of code.
Such a unit can be :
* a class
* a free function
* an interface
* ...
There are several unit test frameworks available to help you write, deploy, manage your unit tests. The most famous family is the xUnit framework, and some of it's descendants.

== Why Unit Testing ==
Well we write code that implements some functionality. We need a way to check and prove that the implementation is correct. Therefor we need tests. We need tests on the application level, at the integration level of different components, classes, interfaces. But we also need tests for the smallest building blocks, the units.
We also wans these tests to run very quickly. That we we can run the tests often, manually or automated.
These tests will also be our safeguards during refactoring of the code, extending the code or whatever maintenance tasks we carry out on the code.
These tests will also make us think of how our class, method, ... will be used. Since the test can be seen as a user of our code. Thanks do this, thinking about the tests before implementing the functionality can help us in the design : emergent design.
It will help us to avoid creating big classes, complex functions. We will only write the methods that are really needed, and no methods that we think might (n)ever be useful in the future. We are no good future tellers ! Those 'might be needed' methods and their tests are just a waste of time. Extending, refactoring will be done when it is actually needed, and at that time we have our unit tests to ensure we don't break any existing code.

Other times to add new unit tests are typically when a bug is discovered; Write a unit test to reproduces the bug, fix the code, and from now on the new unit test will watch your back so the bug won't reappear.

Unit test are also a good place of documentation. The little tests show how the class or method is used.
The code documents itself.

So the benefits are :
* better design
* prove of your code
* safe guard during code maintenance (refactoring, extensions)
* documentation
* ...

== Unit Test frameworks ==
When writing unit tests, one will create a lot of similar code. Since unit tests are nothing more then little programs, several tasks will be repeated, setting up the test environment, create your class, call a method, verify it's result, write out an error message when the test fails, preferably specifying what the wrong outcome was, and what the expected result is.
All these repetitive chores are taken care of by the frame work so the developer can focus on the real code of the test.
This document will use a small but very effective framework for the C++ language. It is called UnitTest++. It's homepage is at : [http://unittest-cpp.sourceforge.net/ UnitTest++].
You can download it directly at this [http://sourceforge.net/projects/unittest-cpp/files/UnitTest%2B%2B/1.4/unittest-cpp-1.4.zip/download link]. At the time of writing the latest version is 1.4.

== Setup our environment ==
Let's create a directory on our PC in which we will cary out our experiments. I will refer to this directory from now on as <TestPit>. For my laptop on which I am writing this article, that will be /home/lieven/Projects/UnitTestArticle. Note that everything we will do, works on linux and on windows!
Download the "unittest-cpp-1.4.zip" file from the link specified above. Extract it in the <TestPit> directory. All the files will end up in the <TestPit>/UnitTest++ directory.

== Build UnitTest++ ==
After the extracted the zip archive we have a directory structure like this :
<TestPit>/UnitTest++
|
+docs
|
+src

The files in the UnitTest++ directory are of little use for us, since they bring project files for some bizarre Microsoft IDE ;-) .
We will create our own Code::Blocks project to build the UnitTest++ framework.

Why do we need to build something ? Well as said, the framework will do a lot of chores for us, those chores are implemented by code, that code is framework. We will build to frame work into a static library, and for every unit test (or set of unit tests) we create a little (console/shell) program with the test code we wrote, which will link with the static library to obtain a unit test executable, driven by the framework.

We will put our Code::Blocks project file in a nice structured directory tree, therefor let's create a 'Project' subdirectory in the <TestPit>/UniTest++ directory.

In there create a new file with the name "UnitTest++.cbp".
Give that file the following content :

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="UnitTest++" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option platforms="Windows;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option platforms="Windows;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
<Target title="Debug(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<VirtualTargets>
<Add alias="All" targets="Debug;Release;Debug(linux);Release(linux);" />
</VirtualTargets>
<Unit filename="../src/AssertException.cpp" />
<Unit filename="../src/AssertException.h" />
<Unit filename="../src/CheckMacros.h" />
<Unit filename="../src/Checks.cpp" />
<Unit filename="../src/Checks.h" />
<Unit filename="../src/Config.h" />
<Unit filename="../src/CurrentTest.cpp" />
<Unit filename="../src/CurrentTest.h" />
<Unit filename="../src/DeferredTestReporter.cpp" />
<Unit filename="../src/DeferredTestReporter.h" />
<Unit filename="../src/DeferredTestResult.cpp" />
<Unit filename="../src/DeferredTestResult.h" />
<Unit filename="../src/ExecuteTest.h" />
<Unit filename="../src/MemoryOutStream.cpp" />
<Unit filename="../src/MemoryOutStream.h" />
<Unit filename="../src/Posix/SignalTranslator.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/SignalTranslator.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/ReportAssert.cpp" />
<Unit filename="../src/ReportAssert.h" />
<Unit filename="../src/Test.cpp" />
<Unit filename="../src/Test.h" />
<Unit filename="../src/TestDetails.cpp" />
<Unit filename="../src/TestDetails.h" />
<Unit filename="../src/TestList.cpp" />
<Unit filename="../src/TestList.h" />
<Unit filename="../src/TestMacros.h" />
<Unit filename="../src/TestReporter.cpp" />
<Unit filename="../src/TestReporter.h" />
<Unit filename="../src/TestReporterStdout.cpp" />
<Unit filename="../src/TestReporterStdout.h" />
<Unit filename="../src/TestResults.cpp" />
<Unit filename="../src/TestResults.h" />
<Unit filename="../src/TestRunner.cpp" />
<Unit filename="../src/TestRunner.h" />
<Unit filename="../src/TestSuite.h" />
<Unit filename="../src/TimeConstraint.cpp" />
<Unit filename="../src/TimeConstraint.h" />
<Unit filename="../src/TimeHelpers.h" />
<Unit filename="../src/UnitTest++.h" />
<Unit filename="../src/Win32/TimeHelpers.cpp">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/Win32/TimeHelpers.h">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/XmlTestReporter.cpp" />
<Unit filename="../src/XmlTestReporter.h" />
<Extensions>
<envvars />
<code_completion />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>

Some things to note about the content of the project file, the power of Code::Blocks.
* there are 4 targets : Debug/Release for Windows and Debug/Release for linux [yes : 1 project file that allows building on linux and on windows]
* some files are only part of the linux targets, some only for the windows targets

But before we build, let's modify some source files (not really needed, but I prefer to have warning free compilations). These are the changes I carried out :
* ReportAssert.cpp : #include "ReportAssert.h"
* win32/TimeHelpers.cpp : first the m_threadHandle and then the m_startTime in the initializerlist

Next open up this project file in Code::Blocks and build the debug and release target. From now one we will only use the Release target, we go for speed ;-)

The result of the build process will show up in subdirectories of the new 'Deliv' subdirectory of <testPit>/UnitTest++ : '''<testPit>/UnitTest++/Deliv/Release/libUnitTest++.a'''

Alright, we have build the unit test framework in a platform independent way, no silly makefiles, no obscure M$ IDE, good old super Code::Blocks. It is time to write some code so we have something to unit test.

In the first example we will create a simple free function that checks if a a give year is a leap your or not.

The business logic is as follows : a year is a leap year when it can be divided by 4, unless itcan be divided by 100. But in case it can be divided by 400, then again it is a leap year.

In the next section we will first setup a Code::Blocks project containing both the 'functionality files, and the unit test files. Typically one will package several functionality files into a static library and create a unit test project that tests all the class/functionalities in that library package, also called a component. That is we have a component (whose deliverable is the static library, and we have a unit test project that tests the entire component).

== Our first test project environment ==
Let's create a new directory in our <TestPit> : <TestPit>/LeapYear.
For the simplicity we will put the project file and the source file all together in this directory. Normally we would work in a more structured way, but in a demo article we have some artistic freedom ;-)
Next you can create with the Code::Block's wizard a new console project in the LeapYear directory. Or you can create the following 4 files and give the the contents as specified below. Note that this demo works on linux and on windows, everything is still completely platform independent. Long Live Code::Blocks.

The project file : LeapYear.cbp (the one below already contains the 3 source files, in case you use the wizard you have to add the LeapYear.h/cpp files to the project)

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="LeapYear" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option output="Deliv/Debug/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Debug/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option output="Deliv/Release/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Release/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-O2" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<Compiler>
<Add option="-Wall" />
<Add option="-fexceptions" />
</Compiler>
<Unit filename="LeapYear.cpp" />
<Unit filename="LeapYear.h" />
<Unit filename="main.cpp" />
<Extensions>
<envvars />
<code_completion />
<lib_finder disable_auto="1" />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>

The main source file : main.cpp
int main()
{
return 0;
}

The header exporting our powerful function : LeapYear.h

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

#endif // LEAPYEAR_H_INCLUDED

And the implementation of the leap year logic : LeapYear.cpp

#include "LeapYear.h"

And finishing with the source file for the tests : LeapYearTest.cpp (currently) empty

We can already build the project, we have a nice little program that does .... nothing.

Time to move to the next section, a little word about Test Driven Development.

== Test Driven Development ==
This is a practice where new code is only added to make a failing test pass. And one only adds the code needed to make that test pass. Once that is done, a new test is added to will check the next functionality to add.
On this really simple example we will more or less practice some TDD.

So get ready, it's time for LeapYear-Step1.

== LeapYear-Step1 ==
We will turn our main.cpp into the guy in charge to carry out the tests, all we need to do is change the contents of main.cpp into this :

#include "UnitTest++.h"

int main()
{
return UnitTest::RunAllTests();
}

And add '''../UnitTest++/src''' to the compiler search directories on the project level of our LeapYear project.
And add '''../UnitTest++/Deliv/Release/libUnitTest++.a''' to the link libraries of the project

Why : well we need to link with the framework and we need to include the UnitTest++ header so we can use it's functionalities.

The line '''UnitTest::RunAllTests()''' will make sure all test encountered in our sources will be carried out.
We don't have any tests yet, nor any functionality, but go ahead build the project and run it.
This is the output :

Success: 0 tests passed
Test time: 0.00 seconds.

Great : success, but no tests yet. Well it's a start.
Time to move forward, and write our first test.

== LeapYear-Step2 ==
Test, test, but there's nothing to test. Yes, absolutely. Let's think of a test, a test that will help us in the design. Now that's a good idea. Suppose I would be the user of the uplifting problem solving leap year checking library/component ... hmmm modesty first : leap year checking '''function'''.
How would I like that function to look.
bool IsLeapYear(int Year);

Yes that seems acceptable.
So let's write a test that will call that method.
We do that by adding the following code to LeapYearTest.cpp

#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

}

Things to note :
* we include the unit test header
* it is good to put the tests in nameless namespace (will be explained later on)
* we use the TEST macro, the argument is the name of the test : OurFirstTest
* we use CHECK_EQUAL to check if the expected result (the first argument) matches the computed result (the second argument)

Time to build. Woooooops errors. The tests fails completely, it does not even build. Time to add the code needed.
In order to compiler the test file, we need to include the LeapYear.h header and have that header export our function.
Our LeapYear header will look like this now (don't forget the include in the test file, it is not shown here) :

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

bool IsLeapYear(int Year);

#endif // LEAPYEAR_H_INCLUDED

At least now it compiles, but it doesn't link yet. Duh, that because we don't have an implementation yet.
Time to provide the bare minimum of code to make the test pass.
So we change the LeapYear.cpp into :

#include "LeapYear.h"

bool IsLeapYear(int /*Year*/)
{
return true;
}

Build it, run it. Yes, we have one test passed.
Great. Let's move on.

== LeapYear-Step3 ==
Anyone having the feeling we are cheating. Well the user does not know how we wrote our ocde on the inside. So just to be sure the user (we) adds the following test, ending up in :

#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

TEST(OurSecondTest)
{
const bool Result = IsLeapYear(1973);
CHECK_EQUAL(false, Result);
}

}

Building is already no issue any more, we can run it. Oh boy, a test is failing.
The framework tell us something like this :
<filename>:<Line>: error: Failure in OurSecondTest: Expected 0 but was 1
FAILURE: 1 out of 2 tests failed (1 failures)
Test time: 0.00 seconds.

So we are informed of the line were the failing tests occurs, next to that it tells us what it was expecting and what the actual outcome was. And it presents a resume of the total number of tests, and how many that failed. For you scripting hackers note that FAILURE != SUCCESS.

It seems we should do some more effort and implement some real logic.

== LeapYear-Step4 ==
Let's keep it taking one step at a time. Let's start by implementing the 'divisible by 4' logic. That will already solve our tests.
So our LeapYear.cpp will now look like this :

#include "LeapYear.h"

namespace
{

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year);
}

Build, run. All test pass. Life is great.

But those changing requirements, always the change the requirements. Years that can be divided by 100 should not be considered as a leap year.

UnitTesting

2009-09-08T21:24:47Z

Killerbot: /* LeapYear-Step2 */

This document is under development by killerbot. Starting from 7 September 2009.

== Introduction ==
This document will describe how unit testing can be combined with the Code::Blocks IDE. It will give a hands-on example on a unit testing framework and how it can be used with Code::Blocks.

== What is Unit Testing ==
Simply put Unit Testing is the discipline and best practice of writing and running little test programs that test little units of code.
Such a unit can be :
* a class
* a free function
* an interface
* ...
There are several unit test frameworks available to help you write, deploy, manage your unit tests. The most famous family is the xUnit framework, and some of it's descendants.

== Why Unit Testing ==
Well we write code that implements some functionality. We need a way to check and prove that the implementation is correct. Therefor we need tests. We need tests on the application level, at the integration level of different components, classes, interfaces. But we also need tests for the smallest building blocks, the units.
We also wans these tests to run very quickly. That we we can run the tests often, manually or automated.
These tests will also be our safeguards during refactoring of the code, extending the code or whatever maintenance tasks we carry out on the code.
These tests will also make us think of how our class, method, ... will be used. Since the test can be seen as a user of our code. Thanks do this, thinking about the tests before implementing the functionality can help us in the design : emergent design.
It will help us to avoid creating big classes, complex functions. We will only write the methods that are really needed, and no methods that we think might (n)ever be useful in the future. We are no good future tellers ! Those 'might be needed' methods and their tests are just a waste of time. Extending, refactoring will be done when it is actually needed, and at that time we have our unit tests to ensure we don't break any existing code.

Other times to add new unit tests are typically when a bug is discovered; Write a unit test to reproduces the bug, fix the code, and from now on the new unit test will watch your back so the bug won't reappear.

Unit test are also a good place of documentation. The little tests show how the class or method is used.
The code documents itself.

So the benefits are :
* better design
* prove of your code
* safe guard during code maintenance (refactoring, extensions)
* documentation
* ...

== Unit Test frameworks ==
When writing unit tests, one will create a lot of similar code. Since unit tests are nothing more then little programs, several tasks will be repeated, setting up the test environment, create your class, call a method, verify it's result, write out an error message when the test fails, preferably specifying what the wrong outcome was, and what the expected result is.
All these repetitive chores are taken care of by the frame work so the developer can focus on the real code of the test.
This document will use a small but very effective framework for the C++ language. It is called UnitTest++. It's homepage is at : [http://unittest-cpp.sourceforge.net/ UnitTest++].
You can download it directly at this [http://sourceforge.net/projects/unittest-cpp/files/UnitTest%2B%2B/1.4/unittest-cpp-1.4.zip/download link]. At the time of writing the latest version is 1.4.

== Setup our environment ==
Let's create a directory on our PC in which we will cary out our experiments. I will refer to this directory from now on as <TestPit>. For my laptop on which I am writing this article, that will be /home/lieven/Projects/UnitTestArticle. Note that everything we will do, works on linux and on windows!
Download the "unittest-cpp-1.4.zip" file from the link specified above. Extract it in the <TestPit> directory. All the files will end up in the <TestPit>/UnitTest++ directory.

== Build UnitTest++ ==
After the extracted the zip archive we have a directory structure like this :
<TestPit>/UnitTest++
|
+docs
|
+src

The files in the UnitTest++ directory are of little use for us, since they bring project files for some bizarre Microsoft IDE ;-) .
We will create our own Code::Blocks project to build the UnitTest++ framework.

Why do we need to build something ? Well as said, the framework will do a lot of chores for us, those chores are implemented by code, that code is framework. We will build to frame work into a static library, and for every unit test (or set of unit tests) we create a little (console/shell) program with the test code we wrote, which will link with the static library to obtain a unit test executable, driven by the framework.

We will put our Code::Blocks project file in a nice structured directory tree, therefor let's create a 'Project' subdirectory in the <TestPit>/UniTest++ directory.

In there create a new file with the name "UnitTest++.cbp".
Give that file the following content :

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="UnitTest++" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option platforms="Windows;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option platforms="Windows;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
<Target title="Debug(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<VirtualTargets>
<Add alias="All" targets="Debug;Release;Debug(linux);Release(linux);" />
</VirtualTargets>
<Unit filename="../src/AssertException.cpp" />
<Unit filename="../src/AssertException.h" />
<Unit filename="../src/CheckMacros.h" />
<Unit filename="../src/Checks.cpp" />
<Unit filename="../src/Checks.h" />
<Unit filename="../src/Config.h" />
<Unit filename="../src/CurrentTest.cpp" />
<Unit filename="../src/CurrentTest.h" />
<Unit filename="../src/DeferredTestReporter.cpp" />
<Unit filename="../src/DeferredTestReporter.h" />
<Unit filename="../src/DeferredTestResult.cpp" />
<Unit filename="../src/DeferredTestResult.h" />
<Unit filename="../src/ExecuteTest.h" />
<Unit filename="../src/MemoryOutStream.cpp" />
<Unit filename="../src/MemoryOutStream.h" />
<Unit filename="../src/Posix/SignalTranslator.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/SignalTranslator.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/ReportAssert.cpp" />
<Unit filename="../src/ReportAssert.h" />
<Unit filename="../src/Test.cpp" />
<Unit filename="../src/Test.h" />
<Unit filename="../src/TestDetails.cpp" />
<Unit filename="../src/TestDetails.h" />
<Unit filename="../src/TestList.cpp" />
<Unit filename="../src/TestList.h" />
<Unit filename="../src/TestMacros.h" />
<Unit filename="../src/TestReporter.cpp" />
<Unit filename="../src/TestReporter.h" />
<Unit filename="../src/TestReporterStdout.cpp" />
<Unit filename="../src/TestReporterStdout.h" />
<Unit filename="../src/TestResults.cpp" />
<Unit filename="../src/TestResults.h" />
<Unit filename="../src/TestRunner.cpp" />
<Unit filename="../src/TestRunner.h" />
<Unit filename="../src/TestSuite.h" />
<Unit filename="../src/TimeConstraint.cpp" />
<Unit filename="../src/TimeConstraint.h" />
<Unit filename="../src/TimeHelpers.h" />
<Unit filename="../src/UnitTest++.h" />
<Unit filename="../src/Win32/TimeHelpers.cpp">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/Win32/TimeHelpers.h">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/XmlTestReporter.cpp" />
<Unit filename="../src/XmlTestReporter.h" />
<Extensions>
<envvars />
<code_completion />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>

Some things to note about the content of the project file, the power of Code::Blocks.
* there are 4 targets : Debug/Release for Windows and Debug/Release for linux [yes : 1 project file that allows building on linux and on windows]
* some files are only part of the linux targets, some only for the windows targets

But before we build, let's modify some source files (not really needed, but I prefer to have warning free compilations). These are the changes I carried out :
* ReportAssert.cpp : #include "ReportAssert.h"
* win32/TimeHelpers.cpp : first the m_threadHandle and then the m_startTime in the initializerlist

Next open up this project file in Code::Blocks and build the debug and release target. From now one we will only use the Release target, we go for speed ;-)

The result of the build process will show up in subdirectories of the new 'Deliv' subdirectory of <testPit>/UnitTest++ : '''<testPit>/UnitTest++/Deliv/Release/libUnitTest++.a'''

Alright, we have build the unit test framework in a platform independent way, no silly makefiles, no obscure M$ IDE, good old super Code::Blocks. It is time to write some code so we have something to unit test.

In the first example we will create a simple free function that checks if a a give year is a leap your or not.

The business logic is as follows : a year is a leap year when it can be divided by 4, unless itcan be divided by 100. But in case it can be divided by 400, then again it is a leap year.

In the next section we will first setup a Code::Blocks project containing both the 'functionality files, and the unit test files. Typically one will package several functionality files into a static library and create a unit test project that tests all the class/functionalities in that library package, also called a component. That is we have a component (whose deliverable is the static library, and we have a unit test project that tests the entire component).

== Our first test project environment ==
Let's create a new directory in our <TestPit> : <TestPit>/LeapYear.
For the simplicity we will put the project file and the source file all together in this directory. Normally we would work in a more structured way, but in a demo article we have some artistic freedom ;-)
Next you can create with the Code::Block's wizard a new console project in the LeapYear directory. Or you can create the following 4 files and give the the contents as specified below. Note that this demo works on linux and on windows, everything is still completely platform independent. Long Live Code::Blocks.

The project file : LeapYear.cbp (the one below already contains the 3 source files, in case you use the wizard you have to add the LeapYear.h/cpp files to the project)

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="LeapYear" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option output="Deliv/Debug/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Debug/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option output="Deliv/Release/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Release/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-O2" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<Compiler>
<Add option="-Wall" />
<Add option="-fexceptions" />
</Compiler>
<Unit filename="LeapYear.cpp" />
<Unit filename="LeapYear.h" />
<Unit filename="main.cpp" />
<Extensions>
<envvars />
<code_completion />
<lib_finder disable_auto="1" />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>

The main source file : main.cpp
int main()
{
return 0;
}

The header exporting our powerful function : LeapYear.h

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

#endif // LEAPYEAR_H_INCLUDED

And the implementation of the leap year logic : LeapYear.cpp

#include "LeapYear.h"

And finishing with the source file for the tests : LeapYearTest.cpp (currently) empty

We can already build the project, we have a nice little program that does .... nothing.

Time to move to the next section, a little word about Test Driven Development.

== Test Driven Development ==
This is a practice where new code is only added to make a failing test pass. And one only adds the code needed to make that test pass. Once that is done, a new test is added to will check the next functionality to add.
On this really simple example we will more or less practice some TDD.

So get ready, it's time for LeapYear-Step1.

== LeapYear-Step1 ==
We will turn our main.cpp into the guy in charge to carry out the tests, all we need to do is change the contents of main.cpp into this :

#include "UnitTest++.h"

int main()
{
return UnitTest::RunAllTests();
}

And add '''../UnitTest++/src''' to the compiler search directories on the project level of our LeapYear project.
And add '''../UnitTest++/Deliv/Release/libUnitTest++.a''' to the link libraries of the project

Why : well we need to link with the framework and we need to include the UnitTest++ header so we can use it's functionalities.

The line '''UnitTest::RunAllTests()''' will make sure all test encountered in our sources will be carried out.
We don't have any tests yet, nor any functionality, but go ahead build the project and run it.
This is the output :

Success: 0 tests passed
Test time: 0.00 seconds.

Great : success, but no tests yet. Well it's a start.
Time to move forward, and write our first test.

== LeapYear-Step2 ==
Test, test, but there's nothing to test. Yes, absolutely. Let's think of a test, a test that will help us in the design. Now that's a good idea. Suppose I would be the user of the uplifting problem solving leap year checking library/component ... hmmm modesty first : leap year checking '''function'''.
How would I like that function to look.
bool IsLeapYear(int Year);

Yes that seems acceptable.
So let's write a test that will call that method.
We do that by adding the following code to LeapYearTest.cpp

#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

}

Things to note :
* we include the unit test header
* it is good to put the tests in nameless namespace (will be explained later on)
* we use the TEST macro, the argument is the name of the test : OurFirstTest
* we use CHECK_EQUAL to check if the expected result (the first argument) matches the computed result (the second argument)

Time to build. Woooooops errors. The tests fails completely, it does not even build. Time to add the code needed.
In order to compiler the test file, we need to include the LeapYear.h header and have that header export our function.
Our LeapYear header will look like this now (don't forget the include in the test file, it is not shown here) :

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

bool IsLeapYear(int Year);

#endif // LEAPYEAR_H_INCLUDED

At least now it compiler, but it doesn't link yet. Duh, that because we don't have an implementation yet.
Time to provide the bare minimum of code to make the test pass.
So we change the LeapYear.cpp into :

#include "LeapYear.h"

bool IsLeapYear(int /*Year*/)
{
return true;
}

Build it, run it. Yes, we have one test passed.
Great. Let's move on.

== LeapYear-Step3 ==
Anyone having the feeling we are cheating. Well the user does not know how we wrote our ocde on the inside. So just to be sure the user (we) adds the following test, ending up in :

#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

TEST(OurSecondTest)
{
const bool Result = IsLeapYear(1973);
CHECK_EQUAL(false, Result);
}

}

Building is already no issue any more, we can run it. Oh boy, a test is failing.
The framework tell us something like this :
<filename>:<Line>: error: Failure in OurSecondTest: Expected 0 but was 1
FAILURE: 1 out of 2 tests failed (1 failures)
Test time: 0.00 seconds.

So we are informed of the line were the failing tests occurs, next to that it tells us what it was expecting and what the actual outcome was. And it presents a resume of the total number of tests, and how many that failed. For you scripting hackers note that FAILURE != SUCCESS.

It seems we should do some more effort and implement some real logic.

== LeapYear-Step4 ==
Let's keep it taking one step at a time. Let's start by implementing the 'divisible by 4' logic. That will already solve our tests.
So our LeapYear.cpp will now look like this :

#include "LeapYear.h"

namespace
{

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year);
}

Build, run. All test pass. Life is great.

But those changing requirements, always the change the requirements. Years that can be divided by 100 should not be considered as a leap year.

UnitTesting

2009-09-08T20:21:52Z

Killerbot: /* LeapYear-Step4 */

This document is under development by killerbot. Starting from 7 September 2009.

== Introduction ==
This document will describe how unit testing can be combined with the Code::Blocks IDE. It will give a hands-on example on a unit testing framework and how it can be used with Code::Blocks.

== What is Unit Testing ==
Simply put Unit Testing is the discipline and best practice of writing and running little test programs that test little units of code.
Such a unit can be :
* a class
* a free function
* an interface
* ...
There are several unit test frameworks available to help you write, deploy, manage your unit tests. The most famous family is the xUnit framework, and some of it's descendants.

== Why Unit Testing ==
Well we write code that implements some functionality. We need a way to check and prove that the implementation is correct. Therefor we need tests. We need tests on the application level, at the integration level of different components, classes, interfaces. But we also need tests for the smallest building blocks, the units.
We also wans these tests to run very quickly. That we we can run the tests often, manually or automated.
These tests will also be our safeguards during refactoring of the code, extending the code or whatever maintenance tasks we carry out on the code.
These tests will also make us think of how our class, method, ... will be used. Since the test can be seen as a user of our code. Thanks do this, thinking about the tests before implementing the functionality can help us in the design : emergent design.
It will help us to avoid creating big classes, complex functions. We will only write the methods that are really needed, and no methods that we think might (n)ever be useful in the future. We are no good future tellers ! Those 'might be needed' methods and their tests are just a waste of time. Extending, refactoring will be done when it is actually needed, and at that time we have our unit tests to ensure we don't break any existing code.

Other times to add new unit tests are typically when a bug is discovered; Write a unit test to reproduces the bug, fix the code, and from now on the new unit test will watch your back so the bug won't reappear.

Unit test are also a good place of documentation. The little tests show how the class or method is used.
The code documents itself.

So the benefits are :
* better design
* prove of your code
* safe guard during code maintenance (refactoring, extensions)
* documentation
* ...

== Unit Test frameworks ==
When writing unit tests, one will create a lot of similar code. Since unit tests are nothing more then little programs, several tasks will be repeated, setting up the test environment, create your class, call a method, verify it's result, write out an error message when the test fails, preferably specifying what the wrong outcome was, and what the expected result is.
All these repetitive chores are taken care of by the frame work so the developer can focus on the real code of the test.
This document will use a small but very effective framework for the C++ language. It is called UnitTest++. It's homepage is at : [http://unittest-cpp.sourceforge.net/ UnitTest++].
You can download it directly at this [http://sourceforge.net/projects/unittest-cpp/files/UnitTest%2B%2B/1.4/unittest-cpp-1.4.zip/download link]. At the time of writing the latest version is 1.4.

== Setup our environment ==
Let's create a directory on our PC in which we will cary out our experiments. I will refer to this directory from now on as <TestPit>. For my laptop on which I am writing this article, that will be /home/lieven/Projects/UnitTestArticle. Note that everything we will do, works on linux and on windows!
Download the "unittest-cpp-1.4.zip" file from the link specified above. Extract it in the <TestPit> directory. All the files will end up in the <TestPit>/UnitTest++ directory.

== Build UnitTest++ ==
After the extracted the zip archive we have a directory structure like this :
<TestPit>/UnitTest++
|
+docs
|
+src

The files in the UnitTest++ directory are of little use for us, since they bring project files for some bizarre Microsoft IDE ;-) .
We will create our own Code::Blocks project to build the UnitTest++ framework.

Why do we need to build something ? Well as said, the framework will do a lot of chores for us, those chores are implemented by code, that code is framework. We will build to frame work into a static library, and for every unit test (or set of unit tests) we create a little (console/shell) program with the test code we wrote, which will link with the static library to obtain a unit test executable, driven by the framework.

We will put our Code::Blocks project file in a nice structured directory tree, therefor let's create a 'Project' subdirectory in the <TestPit>/UniTest++ directory.

In there create a new file with the name "UnitTest++.cbp".
Give that file the following content :

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="UnitTest++" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option platforms="Windows;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option platforms="Windows;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
<Target title="Debug(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<VirtualTargets>
<Add alias="All" targets="Debug;Release;Debug(linux);Release(linux);" />
</VirtualTargets>
<Unit filename="../src/AssertException.cpp" />
<Unit filename="../src/AssertException.h" />
<Unit filename="../src/CheckMacros.h" />
<Unit filename="../src/Checks.cpp" />
<Unit filename="../src/Checks.h" />
<Unit filename="../src/Config.h" />
<Unit filename="../src/CurrentTest.cpp" />
<Unit filename="../src/CurrentTest.h" />
<Unit filename="../src/DeferredTestReporter.cpp" />
<Unit filename="../src/DeferredTestReporter.h" />
<Unit filename="../src/DeferredTestResult.cpp" />
<Unit filename="../src/DeferredTestResult.h" />
<Unit filename="../src/ExecuteTest.h" />
<Unit filename="../src/MemoryOutStream.cpp" />
<Unit filename="../src/MemoryOutStream.h" />
<Unit filename="../src/Posix/SignalTranslator.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/SignalTranslator.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/ReportAssert.cpp" />
<Unit filename="../src/ReportAssert.h" />
<Unit filename="../src/Test.cpp" />
<Unit filename="../src/Test.h" />
<Unit filename="../src/TestDetails.cpp" />
<Unit filename="../src/TestDetails.h" />
<Unit filename="../src/TestList.cpp" />
<Unit filename="../src/TestList.h" />
<Unit filename="../src/TestMacros.h" />
<Unit filename="../src/TestReporter.cpp" />
<Unit filename="../src/TestReporter.h" />
<Unit filename="../src/TestReporterStdout.cpp" />
<Unit filename="../src/TestReporterStdout.h" />
<Unit filename="../src/TestResults.cpp" />
<Unit filename="../src/TestResults.h" />
<Unit filename="../src/TestRunner.cpp" />
<Unit filename="../src/TestRunner.h" />
<Unit filename="../src/TestSuite.h" />
<Unit filename="../src/TimeConstraint.cpp" />
<Unit filename="../src/TimeConstraint.h" />
<Unit filename="../src/TimeHelpers.h" />
<Unit filename="../src/UnitTest++.h" />
<Unit filename="../src/Win32/TimeHelpers.cpp">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/Win32/TimeHelpers.h">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/XmlTestReporter.cpp" />
<Unit filename="../src/XmlTestReporter.h" />
<Extensions>
<envvars />
<code_completion />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>

Some things to note about the content of the project file, the power of Code::Blocks.
* there are 4 targets : Debug/Release for Windows and Debug/Release for linux [yes : 1 project file that allows building on linux and on windows]
* some files are only part of the linux targets, some only for the windows targets

But before we build, let's modify some source files (not really needed, but I prefer to have warning free compilations). These are the changes I carried out :
* ReportAssert.cpp : #include "ReportAssert.h"
* win32/TimeHelpers.cpp : first the m_threadHandle and then the m_startTime in the initializerlist

Next open up this project file in Code::Blocks and build the debug and release target. From now one we will only use the Release target, we go for speed ;-)

The result of the build process will show up in subdirectories of the new 'Deliv' subdirectory of <testPit>/UnitTest++ : '''<testPit>/UnitTest++/Deliv/Release/libUnitTest++.a'''

Alright, we have build the unit test framework in a platform independent way, no silly makefiles, no obscure M$ IDE, good old super Code::Blocks. It is time to write some code so we have something to unit test.

In the first example we will create a simple free function that checks if a a give year is a leap your or not.

The business logic is as follows : a year is a leap year when it can be divided by 4, unless itcan be divided by 100. But in case it can be divided by 400, then again it is a leap year.

In the next section we will first setup a Code::Blocks project containing both the 'functionality files, and the unit test files. Typically one will package several functionality files into a static library and create a unit test project that tests all the class/functionalities in that library package, also called a component. That is we have a component (whose deliverable is the static library, and we have a unit test project that tests the entire component).

== Our first test project environment ==
Let's create a new directory in our <TestPit> : <TestPit>/LeapYear.
For the simplicity we will put the project file and the source file all together in this directory. Normally we would work in a more structured way, but in a demo article we have some artistic freedom ;-)
Next you can create with the Code::Block's wizard a new console project in the LeapYear directory. Or you can create the following 4 files and give the the contents as specified below. Note that this demo works on linux and on windows, everything is still completely platform independent. Long Live Code::Blocks.

The project file : LeapYear.cbp (the one below already contains the 3 source files, in case you use the wizard you have to add the LeapYear.h/cpp files to the project)

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="LeapYear" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option output="Deliv/Debug/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Debug/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option output="Deliv/Release/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Release/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-O2" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<Compiler>
<Add option="-Wall" />
<Add option="-fexceptions" />
</Compiler>
<Unit filename="LeapYear.cpp" />
<Unit filename="LeapYear.h" />
<Unit filename="main.cpp" />
<Extensions>
<envvars />
<code_completion />
<lib_finder disable_auto="1" />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>

The main source file : main.cpp
int main()
{
return 0;
}

The header exporting our powerful function : LeapYear.h

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

#endif // LEAPYEAR_H_INCLUDED

And the implementation of the leap year logic : LeapYear.cpp

#include "LeapYear.h"

And finishing with the source file for the tests : LeapYearTest.cpp (currently) empty

We can already build the project, we have a nice little program that does .... nothing.

Time to move to the next section, a little word about Test Driven Development.

== Test Driven Development ==
This is a practice where new code is only added to make a failing test pass. And one only adds the code needed to make that test pass. Once that is done, a new test is added to will check the next functionality to add.
On this really simple example we will more or less practice some TDD.

So get ready, it's time for LeapYear-Step1.

== LeapYear-Step1 ==
We will turn our main.cpp into the guy in charge to carry out the tests, all we need to do is change the contents of main.cpp into this :

#include "UnitTest++.h"

int main()
{
return UnitTest::RunAllTests();
}

And add '''../UnitTest++/src''' to the compiler search directories on the project level of our LeapYear project.
And add '''../UnitTest++/Deliv/Release/libUnitTest++.a''' to the link libraries of the project

Why : well we need to link with the framework and we need to include the UnitTest++ header so we can use it's functionalities.

The line '''UnitTest::RunAllTests()''' will make sure all test encountered in our sources will be carried out.
We don't have any tests yet, nor any functionality, but go ahead build the project and run it.
This is the output :

Success: 0 tests passed
Test time: 0.00 seconds.

Great : success, but no tests yet. Well it's a start.
Time to move forward, and write our first test.

== LeapYear-Step2 ==
Test, test, but there's nothing to test. yes, absolutely. Let's think of a test, a test that will help us in the design. Now that's a good idea. Suppose I would be the user of the uplifting problem solving leap year checking library/component ... hmmm modesty first : leap year checking '''function'''.
How would I like that function to look.
bool IsLeapYear(int Year);

Yes that seems acceptable.
So let's right a test that will call that method.
We do that by adding the following code to LeapYearTest.cpp

#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

}

Things to note :
* we include the unit test header
* it is good to put the tests in nameless namespace (will be explained later on)
* we use the TEST macro, the argument is the name of the test : OurFirstTest
* we use CHECK_EQUAL to check if the expected result (the first argument) matches the computed result (the second argument)

Time to build. Woooooops errors. The tests fails completely, it does not even build. Time to add the code needed.
In order to compiler the test file, we need to include the LeapYear.h header and have that header export our function.
Our LeapYear header will look like this now (don't forget the include in the test file, it is not shown here) :

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

bool IsLeapYear(int Year);

#endif // LEAPYEAR_H_INCLUDED

At least now it compiler, but it doesn't link yet. Duh, that because we don't have an implementation yet.
Time to provide the bare minimum of code to make the test pass.
So we change the LeapYear.cpp into :

#include "LeapYear.h"

bool IsLeapYear(int /*Year*/)
{
return true;
}

Build it, run it. Yes, we have one test passed.
Great. Let's move on.

== LeapYear-Step3 ==
Anyone having the feeling we are cheating. Well the user does not know how we wrote our ocde on the inside. So just to be sure the user (we) adds the following test, ending up in :

#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

TEST(OurSecondTest)
{
const bool Result = IsLeapYear(1973);
CHECK_EQUAL(false, Result);
}

}

Building is already no issue any more, we can run it. Oh boy, a test is failing.
The framework tell us something like this :
<filename>:<Line>: error: Failure in OurSecondTest: Expected 0 but was 1
FAILURE: 1 out of 2 tests failed (1 failures)
Test time: 0.00 seconds.

So we are informed of the line were the failing tests occurs, next to that it tells us what it was expecting and what the actual outcome was. And it presents a resume of the total number of tests, and how many that failed. For you scripting hackers note that FAILURE != SUCCESS.

It seems we should do some more effort and implement some real logic.

== LeapYear-Step4 ==
Let's keep it taking one step at a time. Let's start by implementing the 'divisible by 4' logic. That will already solve our tests.
So our LeapYear.cpp will now look like this :

#include "LeapYear.h"

namespace
{

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year);
}

Build, run. All test pass. Life is great.

But those changing requirements, always the change the requirements. Years that can be divided by 100 should not be considered as a leap year.

UnitTesting

2009-09-08T20:21:06Z

Killerbot: /* LeapYear-Step4 */

This document is under development by killerbot. Starting from 7 September 2009.

== Introduction ==
This document will describe how unit testing can be combined with the Code::Blocks IDE. It will give a hands-on example on a unit testing framework and how it can be used with Code::Blocks.

== What is Unit Testing ==
Simply put Unit Testing is the discipline and best practice of writing and running little test programs that test little units of code.
Such a unit can be :
* a class
* a free function
* an interface
* ...
There are several unit test frameworks available to help you write, deploy, manage your unit tests. The most famous family is the xUnit framework, and some of it's descendants.

== Why Unit Testing ==
Well we write code that implements some functionality. We need a way to check and prove that the implementation is correct. Therefor we need tests. We need tests on the application level, at the integration level of different components, classes, interfaces. But we also need tests for the smallest building blocks, the units.
We also wans these tests to run very quickly. That we we can run the tests often, manually or automated.
These tests will also be our safeguards during refactoring of the code, extending the code or whatever maintenance tasks we carry out on the code.
These tests will also make us think of how our class, method, ... will be used. Since the test can be seen as a user of our code. Thanks do this, thinking about the tests before implementing the functionality can help us in the design : emergent design.
It will help us to avoid creating big classes, complex functions. We will only write the methods that are really needed, and no methods that we think might (n)ever be useful in the future. We are no good future tellers ! Those 'might be needed' methods and their tests are just a waste of time. Extending, refactoring will be done when it is actually needed, and at that time we have our unit tests to ensure we don't break any existing code.

Other times to add new unit tests are typically when a bug is discovered; Write a unit test to reproduces the bug, fix the code, and from now on the new unit test will watch your back so the bug won't reappear.

Unit test are also a good place of documentation. The little tests show how the class or method is used.
The code documents itself.

So the benefits are :
* better design
* prove of your code
* safe guard during code maintenance (refactoring, extensions)
* documentation
* ...

== Unit Test frameworks ==
When writing unit tests, one will create a lot of similar code. Since unit tests are nothing more then little programs, several tasks will be repeated, setting up the test environment, create your class, call a method, verify it's result, write out an error message when the test fails, preferably specifying what the wrong outcome was, and what the expected result is.
All these repetitive chores are taken care of by the frame work so the developer can focus on the real code of the test.
This document will use a small but very effective framework for the C++ language. It is called UnitTest++. It's homepage is at : [http://unittest-cpp.sourceforge.net/ UnitTest++].
You can download it directly at this [http://sourceforge.net/projects/unittest-cpp/files/UnitTest%2B%2B/1.4/unittest-cpp-1.4.zip/download link]. At the time of writing the latest version is 1.4.

== Setup our environment ==
Let's create a directory on our PC in which we will cary out our experiments. I will refer to this directory from now on as <TestPit>. For my laptop on which I am writing this article, that will be /home/lieven/Projects/UnitTestArticle. Note that everything we will do, works on linux and on windows!
Download the "unittest-cpp-1.4.zip" file from the link specified above. Extract it in the <TestPit> directory. All the files will end up in the <TestPit>/UnitTest++ directory.

== Build UnitTest++ ==
After the extracted the zip archive we have a directory structure like this :
<TestPit>/UnitTest++
|
+docs
|
+src

The files in the UnitTest++ directory are of little use for us, since they bring project files for some bizarre Microsoft IDE ;-) .
We will create our own Code::Blocks project to build the UnitTest++ framework.

Why do we need to build something ? Well as said, the framework will do a lot of chores for us, those chores are implemented by code, that code is framework. We will build to frame work into a static library, and for every unit test (or set of unit tests) we create a little (console/shell) program with the test code we wrote, which will link with the static library to obtain a unit test executable, driven by the framework.

We will put our Code::Blocks project file in a nice structured directory tree, therefor let's create a 'Project' subdirectory in the <TestPit>/UniTest++ directory.

In there create a new file with the name "UnitTest++.cbp".
Give that file the following content :

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="UnitTest++" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option platforms="Windows;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option platforms="Windows;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
<Target title="Debug(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<VirtualTargets>
<Add alias="All" targets="Debug;Release;Debug(linux);Release(linux);" />
</VirtualTargets>
<Unit filename="../src/AssertException.cpp" />
<Unit filename="../src/AssertException.h" />
<Unit filename="../src/CheckMacros.h" />
<Unit filename="../src/Checks.cpp" />
<Unit filename="../src/Checks.h" />
<Unit filename="../src/Config.h" />
<Unit filename="../src/CurrentTest.cpp" />
<Unit filename="../src/CurrentTest.h" />
<Unit filename="../src/DeferredTestReporter.cpp" />
<Unit filename="../src/DeferredTestReporter.h" />
<Unit filename="../src/DeferredTestResult.cpp" />
<Unit filename="../src/DeferredTestResult.h" />
<Unit filename="../src/ExecuteTest.h" />
<Unit filename="../src/MemoryOutStream.cpp" />
<Unit filename="../src/MemoryOutStream.h" />
<Unit filename="../src/Posix/SignalTranslator.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/SignalTranslator.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/ReportAssert.cpp" />
<Unit filename="../src/ReportAssert.h" />
<Unit filename="../src/Test.cpp" />
<Unit filename="../src/Test.h" />
<Unit filename="../src/TestDetails.cpp" />
<Unit filename="../src/TestDetails.h" />
<Unit filename="../src/TestList.cpp" />
<Unit filename="../src/TestList.h" />
<Unit filename="../src/TestMacros.h" />
<Unit filename="../src/TestReporter.cpp" />
<Unit filename="../src/TestReporter.h" />
<Unit filename="../src/TestReporterStdout.cpp" />
<Unit filename="../src/TestReporterStdout.h" />
<Unit filename="../src/TestResults.cpp" />
<Unit filename="../src/TestResults.h" />
<Unit filename="../src/TestRunner.cpp" />
<Unit filename="../src/TestRunner.h" />
<Unit filename="../src/TestSuite.h" />
<Unit filename="../src/TimeConstraint.cpp" />
<Unit filename="../src/TimeConstraint.h" />
<Unit filename="../src/TimeHelpers.h" />
<Unit filename="../src/UnitTest++.h" />
<Unit filename="../src/Win32/TimeHelpers.cpp">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/Win32/TimeHelpers.h">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/XmlTestReporter.cpp" />
<Unit filename="../src/XmlTestReporter.h" />
<Extensions>
<envvars />
<code_completion />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>

Some things to note about the content of the project file, the power of Code::Blocks.
* there are 4 targets : Debug/Release for Windows and Debug/Release for linux [yes : 1 project file that allows building on linux and on windows]
* some files are only part of the linux targets, some only for the windows targets

But before we build, let's modify some source files (not really needed, but I prefer to have warning free compilations). These are the changes I carried out :
* ReportAssert.cpp : #include "ReportAssert.h"
* win32/TimeHelpers.cpp : first the m_threadHandle and then the m_startTime in the initializerlist

Next open up this project file in Code::Blocks and build the debug and release target. From now one we will only use the Release target, we go for speed ;-)

The result of the build process will show up in subdirectories of the new 'Deliv' subdirectory of <testPit>/UnitTest++ : '''<testPit>/UnitTest++/Deliv/Release/libUnitTest++.a'''

Alright, we have build the unit test framework in a platform independent way, no silly makefiles, no obscure M$ IDE, good old super Code::Blocks. It is time to write some code so we have something to unit test.

In the first example we will create a simple free function that checks if a a give year is a leap your or not.

The business logic is as follows : a year is a leap year when it can be divided by 4, unless itcan be divided by 100. But in case it can be divided by 400, then again it is a leap year.

In the next section we will first setup a Code::Blocks project containing both the 'functionality files, and the unit test files. Typically one will package several functionality files into a static library and create a unit test project that tests all the class/functionalities in that library package, also called a component. That is we have a component (whose deliverable is the static library, and we have a unit test project that tests the entire component).

== Our first test project environment ==
Let's create a new directory in our <TestPit> : <TestPit>/LeapYear.
For the simplicity we will put the project file and the source file all together in this directory. Normally we would work in a more structured way, but in a demo article we have some artistic freedom ;-)
Next you can create with the Code::Block's wizard a new console project in the LeapYear directory. Or you can create the following 4 files and give the the contents as specified below. Note that this demo works on linux and on windows, everything is still completely platform independent. Long Live Code::Blocks.

The project file : LeapYear.cbp (the one below already contains the 3 source files, in case you use the wizard you have to add the LeapYear.h/cpp files to the project)

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="LeapYear" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option output="Deliv/Debug/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Debug/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option output="Deliv/Release/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Release/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-O2" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<Compiler>
<Add option="-Wall" />
<Add option="-fexceptions" />
</Compiler>
<Unit filename="LeapYear.cpp" />
<Unit filename="LeapYear.h" />
<Unit filename="main.cpp" />
<Extensions>
<envvars />
<code_completion />
<lib_finder disable_auto="1" />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>

The main source file : main.cpp
int main()
{
return 0;
}

The header exporting our powerful function : LeapYear.h

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

#endif // LEAPYEAR_H_INCLUDED

And the implementation of the leap year logic : LeapYear.cpp

#include "LeapYear.h"

And finishing with the source file for the tests : LeapYearTest.cpp (currently) empty

We can already build the project, we have a nice little program that does .... nothing.

Time to move to the next section, a little word about Test Driven Development.

== Test Driven Development ==
This is a practice where new code is only added to make a failing test pass. And one only adds the code needed to make that test pass. Once that is done, a new test is added to will check the next functionality to add.
On this really simple example we will more or less practice some TDD.

So get ready, it's time for LeapYear-Step1.

== LeapYear-Step1 ==
We will turn our main.cpp into the guy in charge to carry out the tests, all we need to do is change the contents of main.cpp into this :

#include "UnitTest++.h"

int main()
{
return UnitTest::RunAllTests();
}

And add '''../UnitTest++/src''' to the compiler search directories on the project level of our LeapYear project.
And add '''../UnitTest++/Deliv/Release/libUnitTest++.a''' to the link libraries of the project

Why : well we need to link with the framework and we need to include the UnitTest++ header so we can use it's functionalities.

The line '''UnitTest::RunAllTests()''' will make sure all test encountered in our sources will be carried out.
We don't have any tests yet, nor any functionality, but go ahead build the project and run it.
This is the output :

Success: 0 tests passed
Test time: 0.00 seconds.

Great : success, but no tests yet. Well it's a start.
Time to move forward, and write our first test.

== LeapYear-Step2 ==
Test, test, but there's nothing to test. yes, absolutely. Let's think of a test, a test that will help us in the design. Now that's a good idea. Suppose I would be the user of the uplifting problem solving leap year checking library/component ... hmmm modesty first : leap year checking '''function'''.
How would I like that function to look.
bool IsLeapYear(int Year);

Yes that seems acceptable.
So let's right a test that will call that method.
We do that by adding the following code to LeapYearTest.cpp

#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

}

Things to note :
* we include the unit test header
* it is good to put the tests in nameless namespace (will be explained later on)
* we use the TEST macro, the argument is the name of the test : OurFirstTest
* we use CHECK_EQUAL to check if the expected result (the first argument) matches the computed result (the second argument)

Time to build. Woooooops errors. The tests fails completely, it does not even build. Time to add the code needed.
In order to compiler the test file, we need to include the LeapYear.h header and have that header export our function.
Our LeapYear header will look like this now (don't forget the include in the test file, it is not shown here) :

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

bool IsLeapYear(int Year);

#endif // LEAPYEAR_H_INCLUDED

At least now it compiler, but it doesn't link yet. Duh, that because we don't have an implementation yet.
Time to provide the bare minimum of code to make the test pass.
So we change the LeapYear.cpp into :

#include "LeapYear.h"

bool IsLeapYear(int /*Year*/)
{
return true;
}

Build it, run it. Yes, we have one test passed.
Great. Let's move on.

== LeapYear-Step3 ==
Anyone having the feeling we are cheating. Well the user does not know how we wrote our ocde on the inside. So just to be sure the user (we) adds the following test, ending up in :

#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

TEST(OurSecondTest)
{
const bool Result = IsLeapYear(1973);
CHECK_EQUAL(false, Result);
}

}

Building is already no issue any more, we can run it. Oh boy, a test is failing.
The framework tell us something like this :
<filename>:<Line>: error: Failure in OurSecondTest: Expected 0 but was 1
FAILURE: 1 out of 2 tests failed (1 failures)
Test time: 0.00 seconds.

So we are informed of the line were the failing tests occurs, next to that it tells us what it was expecting and what the actual outcome was. And it presents a resume of the total number of tests, and how many that failed. For you scripting hackers note that FAILURE != SUCCESS.

It seems we should do some more effort and implement some real logic.

== LeapYear-Step4 ==
Let's keep it taking one step at a time. Let's start by implementing the 'divisible by 4' logic. That will already solve our tests.
So our LeapYear.cpp will now look like this :

#include "LeapYear.h"

namespace
{

bool IsDivisableBy4(int Year)
{
return (Year%4) == 0;
}

}

bool IsLeapYear(int Year)
{
return IsDivisableBy4(Year);
}

Build, run. All test pass. Life is great.

UnitTesting

2009-09-08T20:18:23Z

Killerbot: /* LeapYear-Step2 */

This document is under development by killerbot. Starting from 7 September 2009.

== Introduction ==
This document will describe how unit testing can be combined with the Code::Blocks IDE. It will give a hands-on example on a unit testing framework and how it can be used with Code::Blocks.

== What is Unit Testing ==
Simply put Unit Testing is the discipline and best practice of writing and running little test programs that test little units of code.
Such a unit can be :
* a class
* a free function
* an interface
* ...
There are several unit test frameworks available to help you write, deploy, manage your unit tests. The most famous family is the xUnit framework, and some of it's descendants.

== Why Unit Testing ==
Well we write code that implements some functionality. We need a way to check and prove that the implementation is correct. Therefor we need tests. We need tests on the application level, at the integration level of different components, classes, interfaces. But we also need tests for the smallest building blocks, the units.
We also wans these tests to run very quickly. That we we can run the tests often, manually or automated.
These tests will also be our safeguards during refactoring of the code, extending the code or whatever maintenance tasks we carry out on the code.
These tests will also make us think of how our class, method, ... will be used. Since the test can be seen as a user of our code. Thanks do this, thinking about the tests before implementing the functionality can help us in the design : emergent design.
It will help us to avoid creating big classes, complex functions. We will only write the methods that are really needed, and no methods that we think might (n)ever be useful in the future. We are no good future tellers ! Those 'might be needed' methods and their tests are just a waste of time. Extending, refactoring will be done when it is actually needed, and at that time we have our unit tests to ensure we don't break any existing code.

Other times to add new unit tests are typically when a bug is discovered; Write a unit test to reproduces the bug, fix the code, and from now on the new unit test will watch your back so the bug won't reappear.

Unit test are also a good place of documentation. The little tests show how the class or method is used.
The code documents itself.

So the benefits are :
* better design
* prove of your code
* safe guard during code maintenance (refactoring, extensions)
* documentation
* ...

== Unit Test frameworks ==
When writing unit tests, one will create a lot of similar code. Since unit tests are nothing more then little programs, several tasks will be repeated, setting up the test environment, create your class, call a method, verify it's result, write out an error message when the test fails, preferably specifying what the wrong outcome was, and what the expected result is.
All these repetitive chores are taken care of by the frame work so the developer can focus on the real code of the test.
This document will use a small but very effective framework for the C++ language. It is called UnitTest++. It's homepage is at : [http://unittest-cpp.sourceforge.net/ UnitTest++].
You can download it directly at this [http://sourceforge.net/projects/unittest-cpp/files/UnitTest%2B%2B/1.4/unittest-cpp-1.4.zip/download link]. At the time of writing the latest version is 1.4.

== Setup our environment ==
Let's create a directory on our PC in which we will cary out our experiments. I will refer to this directory from now on as <TestPit>. For my laptop on which I am writing this article, that will be /home/lieven/Projects/UnitTestArticle. Note that everything we will do, works on linux and on windows!
Download the "unittest-cpp-1.4.zip" file from the link specified above. Extract it in the <TestPit> directory. All the files will end up in the <TestPit>/UnitTest++ directory.

== Build UnitTest++ ==
After the extracted the zip archive we have a directory structure like this :
<TestPit>/UnitTest++
|
+docs
|
+src

The files in the UnitTest++ directory are of little use for us, since they bring project files for some bizarre Microsoft IDE ;-) .
We will create our own Code::Blocks project to build the UnitTest++ framework.

Why do we need to build something ? Well as said, the framework will do a lot of chores for us, those chores are implemented by code, that code is framework. We will build to frame work into a static library, and for every unit test (or set of unit tests) we create a little (console/shell) program with the test code we wrote, which will link with the static library to obtain a unit test executable, driven by the framework.

We will put our Code::Blocks project file in a nice structured directory tree, therefor let's create a 'Project' subdirectory in the <TestPit>/UniTest++ directory.

In there create a new file with the name "UnitTest++.cbp".
Give that file the following content :

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="UnitTest++" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option platforms="Windows;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option platforms="Windows;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
<Target title="Debug(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Debug/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Debug/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release(linux)">
<Option platforms="Unix;Mac;" />
<Option output="../Deliv/Release/libUnitTest++.a" prefix_auto="0" extension_auto="0" />
<Option working_dir="" />
<Option object_output="../Deliv/Release/" />
<Option type="2" />
<Option compiler="gcc" />
<Option createDefFile="1" />
<Compiler>
<Add option="-O3" />
<Add option="-Winit-self" />
<Add option="-Wredundant-decls" />
<Add option="-Wcast-align" />
<Add option="-Wundef" />
<Add option="-Wfloat-equal" />
<Add option="-Wmissing-declarations" />
<Add option="-Wmissing-include-dirs" />
<Add option="-Wswitch-enum" />
<Add option="-Wswitch-default" />
<Add option="-Wmain" />
<Add option="-pedantic" />
<Add option="-std=c++98" />
<Add option="-Wextra" />
<Add option="-Wall" />
<Add option="-ansi" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<VirtualTargets>
<Add alias="All" targets="Debug;Release;Debug(linux);Release(linux);" />
</VirtualTargets>
<Unit filename="../src/AssertException.cpp" />
<Unit filename="../src/AssertException.h" />
<Unit filename="../src/CheckMacros.h" />
<Unit filename="../src/Checks.cpp" />
<Unit filename="../src/Checks.h" />
<Unit filename="../src/Config.h" />
<Unit filename="../src/CurrentTest.cpp" />
<Unit filename="../src/CurrentTest.h" />
<Unit filename="../src/DeferredTestReporter.cpp" />
<Unit filename="../src/DeferredTestReporter.h" />
<Unit filename="../src/DeferredTestResult.cpp" />
<Unit filename="../src/DeferredTestResult.h" />
<Unit filename="../src/ExecuteTest.h" />
<Unit filename="../src/MemoryOutStream.cpp" />
<Unit filename="../src/MemoryOutStream.h" />
<Unit filename="../src/Posix/SignalTranslator.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/SignalTranslator.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.cpp">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/Posix/TimeHelpers.h">
<Option target="Debug(linux)" />
<Option target="Release(linux)" />
</Unit>
<Unit filename="../src/ReportAssert.cpp" />
<Unit filename="../src/ReportAssert.h" />
<Unit filename="../src/Test.cpp" />
<Unit filename="../src/Test.h" />
<Unit filename="../src/TestDetails.cpp" />
<Unit filename="../src/TestDetails.h" />
<Unit filename="../src/TestList.cpp" />
<Unit filename="../src/TestList.h" />
<Unit filename="../src/TestMacros.h" />
<Unit filename="../src/TestReporter.cpp" />
<Unit filename="../src/TestReporter.h" />
<Unit filename="../src/TestReporterStdout.cpp" />
<Unit filename="../src/TestReporterStdout.h" />
<Unit filename="../src/TestResults.cpp" />
<Unit filename="../src/TestResults.h" />
<Unit filename="../src/TestRunner.cpp" />
<Unit filename="../src/TestRunner.h" />
<Unit filename="../src/TestSuite.h" />
<Unit filename="../src/TimeConstraint.cpp" />
<Unit filename="../src/TimeConstraint.h" />
<Unit filename="../src/TimeHelpers.h" />
<Unit filename="../src/UnitTest++.h" />
<Unit filename="../src/Win32/TimeHelpers.cpp">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/Win32/TimeHelpers.h">
<Option target="Debug" />
<Option target="Release" />
</Unit>
<Unit filename="../src/XmlTestReporter.cpp" />
<Unit filename="../src/XmlTestReporter.h" />
<Extensions>
<envvars />
<code_completion />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>

Some things to note about the content of the project file, the power of Code::Blocks.
* there are 4 targets : Debug/Release for Windows and Debug/Release for linux [yes : 1 project file that allows building on linux and on windows]
* some files are only part of the linux targets, some only for the windows targets

But before we build, let's modify some source files (not really needed, but I prefer to have warning free compilations). These are the changes I carried out :
* ReportAssert.cpp : #include "ReportAssert.h"
* win32/TimeHelpers.cpp : first the m_threadHandle and then the m_startTime in the initializerlist

Next open up this project file in Code::Blocks and build the debug and release target. From now one we will only use the Release target, we go for speed ;-)

The result of the build process will show up in subdirectories of the new 'Deliv' subdirectory of <testPit>/UnitTest++ : '''<testPit>/UnitTest++/Deliv/Release/libUnitTest++.a'''

Alright, we have build the unit test framework in a platform independent way, no silly makefiles, no obscure M$ IDE, good old super Code::Blocks. It is time to write some code so we have something to unit test.

In the first example we will create a simple free function that checks if a a give year is a leap your or not.

The business logic is as follows : a year is a leap year when it can be divided by 4, unless itcan be divided by 100. But in case it can be divided by 400, then again it is a leap year.

In the next section we will first setup a Code::Blocks project containing both the 'functionality files, and the unit test files. Typically one will package several functionality files into a static library and create a unit test project that tests all the class/functionalities in that library package, also called a component. That is we have a component (whose deliverable is the static library, and we have a unit test project that tests the entire component).

== Our first test project environment ==
Let's create a new directory in our <TestPit> : <TestPit>/LeapYear.
For the simplicity we will put the project file and the source file all together in this directory. Normally we would work in a more structured way, but in a demo article we have some artistic freedom ;-)
Next you can create with the Code::Block's wizard a new console project in the LeapYear directory. Or you can create the following 4 files and give the the contents as specified below. Note that this demo works on linux and on windows, everything is still completely platform independent. Long Live Code::Blocks.

The project file : LeapYear.cbp (the one below already contains the 3 source files, in case you use the wizard you have to add the LeapYear.h/cpp files to the project)

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<CodeBlocks_project_file>
<FileVersion major="1" minor="6" />
<Project>
<Option title="LeapYear" />
<Option pch_mode="2" />
<Option compiler="gcc" />
<Build>
<Target title="Debug">
<Option output="Deliv/Debug/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Debug/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-g" />
</Compiler>
</Target>
<Target title="Release">
<Option output="Deliv/Release/LeapYear" prefix_auto="1" extension_auto="1" />
<Option object_output="Deliv/Release/" />
<Option type="1" />
<Option compiler="gcc" />
<Compiler>
<Add option="-O2" />
</Compiler>
<Linker>
<Add option="-s" />
</Linker>
</Target>
</Build>
<Compiler>
<Add option="-Wall" />
<Add option="-fexceptions" />
</Compiler>
<Unit filename="LeapYear.cpp" />
<Unit filename="LeapYear.h" />
<Unit filename="main.cpp" />
<Extensions>
<envvars />
<code_completion />
<lib_finder disable_auto="1" />
<debugger />
</Extensions>
</Project>
</CodeBlocks_project_file>

The main source file : main.cpp
int main()
{
return 0;
}

The header exporting our powerful function : LeapYear.h

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

#endif // LEAPYEAR_H_INCLUDED

And the implementation of the leap year logic : LeapYear.cpp

#include "LeapYear.h"

And finishing with the source file for the tests : LeapYearTest.cpp (currently) empty

We can already build the project, we have a nice little program that does .... nothing.

Time to move to the next section, a little word about Test Driven Development.

== Test Driven Development ==
This is a practice where new code is only added to make a failing test pass. And one only adds the code needed to make that test pass. Once that is done, a new test is added to will check the next functionality to add.
On this really simple example we will more or less practice some TDD.

So get ready, it's time for LeapYear-Step1.

== LeapYear-Step1 ==
We will turn our main.cpp into the guy in charge to carry out the tests, all we need to do is change the contents of main.cpp into this :

#include "UnitTest++.h"

int main()
{
return UnitTest::RunAllTests();
}

And add '''../UnitTest++/src''' to the compiler search directories on the project level of our LeapYear project.
And add '''../UnitTest++/Deliv/Release/libUnitTest++.a''' to the link libraries of the project

Why : well we need to link with the framework and we need to include the UnitTest++ header so we can use it's functionalities.

The line '''UnitTest::RunAllTests()''' will make sure all test encountered in our sources will be carried out.
We don't have any tests yet, nor any functionality, but go ahead build the project and run it.
This is the output :

Success: 0 tests passed
Test time: 0.00 seconds.

Great : success, but no tests yet. Well it's a start.
Time to move forward, and write our first test.

== LeapYear-Step2 ==
Test, test, but there's nothing to test. yes, absolutely. Let's think of a test, a test that will help us in the design. Now that's a good idea. Suppose I would be the user of the uplifting problem solving leap year checking library/component ... hmmm modesty first : leap year checking '''function'''.
How would I like that function to look.
bool IsLeapYear(int Year);

Yes that seems acceptable.
So let's right a test that will call that method.
We do that by adding the following code to LeapYearTest.cpp

#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

}

Things to note :
* we include the unit test header
* it is good to put the tests in nameless namespace (will be explained later on)
* we use the TEST macro, the argument is the name of the test : OurFirstTest
* we use CHECK_EQUAL to check if the expected result (the first argument) matches the computed result (the second argument)

Time to build. Woooooops errors. The tests fails completely, it does not even build. Time to add the code needed.
In order to compiler the test file, we need to include the LeapYear.h header and have that header export our function.
Our LeapYear header will look like this now (don't forget the include in the test file, it is not shown here) :

#ifndef LEAPYEAR_H_INCLUDED
#define LEAPYEAR_H_INCLUDED

bool IsLeapYear(int Year);

#endif // LEAPYEAR_H_INCLUDED

At least now it compiler, but it doesn't link yet. Duh, that because we don't have an implementation yet.
Time to provide the bare minimum of code to make the test pass.
So we change the LeapYear.cpp into :

#include "LeapYear.h"

bool IsLeapYear(int /*Year*/)
{
return true;
}

Build it, run it. Yes, we have one test passed.
Great. Let's move on.

== LeapYear-Step3 ==
Anyone having the feeling we are cheating. Well the user does not know how we wrote our ocde on the inside. So just to be sure the user (we) adds the following test, ending up in :

#include "UnitTest++.h"

namespace
{

TEST(OurFirstTest)
{
const bool Result = IsLeapYear(1972);
CHECK_EQUAL(true, Result);
}

TEST(OurSecondTest)
{
const bool Result = IsLeapYear(1973);
CHECK_EQUAL(false, Result);
}

}

Building is already no issue any more, we can run it. Oh boy, a test is failing.
The framework tell us something like this :
<filename>:<Line>: error: Failure in OurSecondTest: Expected 0 but was 1
FAILURE: 1 out of 2 tests failed (1 failures)
Test time: 0.00 seconds.

So we are informed of the line were the failing tests occurs, next to that it tells us what it was expecting and what the actual outcome was. And it presents a resume of the total number of tests, and how many that failed. For you scripting hackers note that FAILURE != SUCCESS.

It seems we should do some more effort and implement some real logic.

== LeapYear-Step4 ==
Let's keep it taking one step at a time. Let's start by implementing the 'divisible by 4' logic. That will already solve our tests.

UnitTesting

2009-09-08T20:04:27Z

Killerbot: /* LeapYear-Step1 */

UnitTesting

2009-09-08T19:53:29Z

Killerbot: /* Our first test project environment */

UnitTesting

2009-09-08T19:52:20Z

Killerbot: /* LeapYear-Step1 */

UnitTesting

2009-09-08T19:49:29Z

Killerbot: /* Our first test project environment */

UnitTesting

2009-09-08T19:40:21Z

Killerbot: /* Our first test project environment */

UnitTesting

2009-09-08T19:39:28Z

Killerbot: /* Our first test project environment */

UnitTesting

2009-09-08T19:38:55Z

Killerbot: /* Our first test project environment */

UnitTesting

2009-09-08T19:38:09Z

Killerbot: /* Our first test project environment */

UnitTesting

2009-09-08T19:37:01Z

Killerbot: /* Build UnitTest++ */