Every Flavour Beans

CppUnit is the most popular unit testing framework available for the C++ language today. So integrating it with one of the most popular IDEs available for the C++ language should be very appealing indeed. If you have not yet configured CppUnit library to work with the Eclipse IDE yet, here is a step-by-step procedure to do the same. By the end of it you will be able to create C++ classes and functions, write unit tests for them, run them and see the results, all from with-in the Eclipse IDE. This is for the Windows users; can be adapted for GNU/Linux users but there are shorter procedures for them.

You can either use Eclipse Europa for C++ as the IDE or other IDEs based on it like EasyEclipse, Wascana etc. And of course MinGW or someother C++ toolchain must already be installed and configured with your Eclipse IDE; if not, read the MinGW and EasyEclipse configuration post for more information; it’s for older version of the Eclipse and configuration is much simpler for Eclipse Europa.

Downloading and Preparing the CppUnit Package

You can skip this section and the next one if you already have CppUnit library built/installed on your system and you know where its include and library files reside. Jump over to the last section in that case.

1. Download CppUnit package from its sourceforge.net page.
   
   Extract it to a directory of your choice. I will assume that it is extracted to ‘c:\cpp\cppunit’. This directory should look like this:
   
   (If the downloaded archive file gets extracted to a directory named cppunit-1.12.0 then just rename it to cppunit.)
2. What we downloaded in the above step is the CppUnit source code. We need to build this source code to create a library file which we can then use in the C++ programs. CppUnit can be built from sources either from the command line or from the Eclipse IDE itself. To build it from the Eclipse IDE, we still need to generate at least one file from the MSYS command line. Go to your MSYS installation directory and click on msys.bat file in it. In the MSYS console window, change to the CppUnit directory(c:\cpp\cppunit in our example) and run the ./configure command.

   

   This will create the cppunit/config-auto.h file that we need. Close the MSYS command window.

Building CppUnit Package from the Source Code in Eclipse IDE

1. Start the Eclipse IDE and create a new C++ project in it by going to File -> New -> C++ Project, enter a name(say, “CppUnitBuild”) in the Project Name text box, select “Static Library” from the Project Types pane and “MinGW GCC” from the Toolchain pane.

   

   You can also choose to select “Shared Library” if you want to build CppUnit as a shared library. Similary, select “Cygwin GCC” if that is the toolchain you prefer.

   Click Finish when done.

2. Now we need to import the entire CppUnit source code into this project. Right-click on the newly created project(CppUnitBuild) and select the “Import” menu item. In the “Import” dialog box, expand the “General” tab, select “File System” and click the Next button. Click “Browse” and browse to the c:\cppunit\src\cppunit directory and click the “Select All” button and click Finish.

   

   This will select and import all the source(.cpp) and header(.h) files of the CppUnit package into the CppUnitBuild project.

3. Next step is to add the CppUnit include directory to the compiler’s include path. Right-click on the project(CppUnitBuild), select “Properties” and go to C/C++ Build -> Settings node. In the right pane, go to Tool Settings -> GCC C++ Compiler -> Directories. Click the “Add” button located near the “Include Paths (-I)” text box(see the screenshot below), click “File System…” button and browse to c:\cpp\cppunit\include directory.

   

4. Finally, build the project by pressing Ctrl-B or by right-clicking on the project and selecting “Build Project.”
   At the end of the build process, a static CppUnit library(libCppUnitBuild.a) should be built in the Debug subdirectory of the project directory in your Eclipse workspace(If you build using the Release configuration, the library will be generated in Release subdirectory instead). If you had opted for a shared library earlier, then [1] suggests that you define CPPUNIT_DLL_BUILD variable by going to Project -> Properties -> C/C++ Build -> Settings -> GCC C++ Compiler -> Preprocessor -> Define Symbols (-D). You will see a file named libCppUnitBuild.dll generated in this case.

   Let us test it with a sample C++ project.

Unit Testing C++ Programs using CppUnit in Eclipse IDE

1. From the Eclipse IDE, create a new project by going to File -> New -> C++ Project, enter a name(say “CppUnitDemo”) in the Project Name text field, select Executable -> Empty Project from the Project Types pane and “MinGW GCC” from the Toolchain pane and click Finish.
2. Now you can create a sample C++ class and write unit tests for it. A faster way would be to download this sample zip file that contains all the files required for testing. Download and extract it to some directory and then import all its contents to the CppUnitDemo project(right-click on project name and select Import, just like we did in Step 2 of second section). You can also drag and drop these files on the project name in Eclipse.
3. Add CppUnit include directory to the project’s include path just like we did in Step 3 of second section. But remember to add the path to the CppUnitDemo project, not to the CppUnitBuild project! We also need to add the CppUnit library file that we have generated in the second part of this post to our CppUnitDemo project.

   Right-click on the project name, select Properties, select C/C++ Build -> Settings node, select the Tools Settings tab, select MinGW C++ Linker -> Libraries node, click the Add button near “Libraries (-l)” text box and enter CppUnitBuild in the popped-up dialog box. Similary, click the Add button near “Library search path (-L)” text box, click “File System…” button and browse to the path where the CppUnit library file was generated([your-eclipse-workspace]\CppUnitBuild\Debug\; The generated file might be in the Release sub-directory if you had chosen a Release build configuration to build the CppUnitBuild project earlier).

   

   If you had built CppUnit as a shared library earlier, then you need to define CPPUNIT_DLL at this stage; see Step 6 for more details.

4. Right-click on the project name and select “Build Project” to build the project and right-click on the project name and select Run As -> Local C/C++ Application, select ‘gdb debugger’ and click OK to run the project. You should see two dots in the output to represent that the two unit tests present in the sample files ran successfully. You can now create your C++ classes, write unit tests for them and then run the tests. Need help in getting started with writing unit tests using CppUnit? Here’s a CppUnit cookbook for you and you can also download the CppUnit documentation.

Next up is how to integrate CppUnit Qt GUI test runner in Eclipse IDE. Then I will write about how to integrate CxxTest unit testing framework with the Eclipse IDE. Doxygen integration may follow, so hang tight ;)

[1] http://cppunit.sourceforge.net/cppunit-wiki/CppUnitWithEclipse - the sample zip file and other help for creating this tutorial were taken from this wiki page.