Building And Integrating CppUnitLite in Eclipse on Linux


For this tutorial, I will be demonstrating how to build and integrate the lightweight C++ Unit Testing Framework, CppUnitLite, into your eclipse projects. I will be using Eclipse Juno on Xubuntu, but the same can be done on any other platform of your choice.

If you are familiar with CppUnit, CppUnitLite is – as the website mentions – more barebones, lighter, and more portable as it avoids using some C++ features such as exceptions, and templates.

We will build it as a static library, so that we can then link into any of our projects that we would like to write unit tests for later.

First, we need to get the source code form the CppUnitLite website. Go there and get it. Once you do, extract the zip file. You’ll find that it contains a lot of files and a couple of folders. We only need a sub-set of those, specifically the folders in the CppUnitLite sub-folder highlighted in the below screen shot.

Needed Files

Now go ahead and open up Eclipse. Select File > New > C++ Project.

New C++ Project Menu

From the C++ Project Window, name your project CppUnitLite, and make sure you selected a Static Library project type. Now click on Next >.

Static Library

For the build configuration, you can just select Debug for now. Then click Finish.

Build Configuration

You are now ready to import the source files. Right-click the project and click Import … from the menu.

Import

From the Import window, select General > File System as the import source. Then click Next >.

Import Source

From the next window, click on the Browse button, and navigate to the folder where the needed CppUnitLite sources (highlighted at the top of this post) are located. Now select only the needed files. Make sure NOT to select the two sub-folders Cpp and CppUnitTests. When you’re done, click Finish.

Import Files

Now before we build, I hope you noticed on their website that they have this important note about a bug in the CHECK_EQUAL macro, and the revised one has been provided. This macro is located in the file Test.h. Copy the correct one from the website, and paste over the wrong one in the file.

CHECK_EQUAL Bug

CHECK_EQUAL Correction

Now Build the project. This will create a sub-folder named Debug under your project. If you take a look inside it, you’ll find a file named libCppUnitLite.a. This is the static library file that you would want to link in your projects later.

Build

Library File

Now we’re done with building the library, and we need to experiment with it to write some simple unit tests. For demonstration purposes, we will create a new project, import the library, and the header files of CppUnitLite there, and write some simple unit tests just to show how things work. Create a new C++ project, and make sure the project type is Executable this time. Name the project whatever you want. I named it TestCppUnitLite. Now click Finish.

Test Project

We will create a sub-folder under this project in which we will import the CppUnitLite library and header files shortly. Right-click on the project name and select New > Source Folder. Name the folder CppUnitLite.

Source Folder Menu

Now right-click on that newly created folder, and select Import. From the Import window, as shown above, select General > File System as the import source and click Next >. Click the Browse button and navigate to the folder where we built the library. Once you do that select only the library file (libCppUnitLite.a) from the list and click finish.

Import Library

Repeat exactly the same above mentioned process again to import the header files. Just browse to where they are and import them into the same folder. You’ll need to import 6 header files namely Test.h, TestHarness.h, TestResult.h, TestRegistry.h, SimpleString.h, and Failure.h. Then click Finish.

Import Headers

Now it’s time to write some simple code. Right-click on the project name, and click New > Source File. Name the file main.cpp and click Finish.

Main CPP

All you need to write is the following code. It’s kind of like a boiler-plate code to start running the tests and reporting the results.

#include "CppUnitLite/TestHarness.h"
int main()
{
     TestResult tr;
     TestRegistry::runAllTests(tr);
     return 0;
}

At this moment there isn’t any tests to run, so we need to write some very simple tests just to show how things work. We will create a new source file and we will name it tests.cpp. In this newly created file we will write some tests, some of them are intended to fail just to show how CppUnitLite reports a test failure. Notice that CppUnitLite used predefined macros to enable us to write these simple unit tests easily. Copy and paste the following code into tests.cpp.

#include "CppUnitLite/TestHarness.h"
TEST(EqualitySuccess, EqualityGroup)
{
     int a = 5;
     CHECK(a == 5);
}
TEST(EqualityFailure, EqualityGroup)
{
     int a = 6;
     CHECK(a == 5);
}
TEST(GreaterSuccess, GreaterGroup)
{
     int a = 50;
     CHECK(a > 30);
}
TEST(GreaterFailure, GreaterGroup)
{
     int a = 50;
     CHECK(a > 100);
}

For any test you write, First you’ll need to include the TestHarness.h header file, which includes all of the others for you. Next you’ll need to use the TEST macro. the TEST macro takes two arguments, the first is the test name, the second is the test group. This is useful when you want to create multiple tests that belong to a single group. As you can see above I have to test groups, each of which has two tests, one that is intended to succeed, and the other is intended to fail.

I’m using the CHECK macro for all of my tests above, but you have others too that you can use such as CHECK_EQUAL, LONGS_EQUAL, .. etc. They’re defined in the header file Test.h.

Now we need to build and run those tests to see the result. But WAIT!! If you try to build now, you’ll fail as the linker doesn’t know how to link to the library file. You must specify that yourself.

Right-click the project name and select Properties. From the Properties window, go to C/C++ Build > Settings. From the Tool Settings tab, under GCC C++ Linker > Libraries, you’ll need to do two things.

Linker

You’ll need to add  the library search path. Click on the Add… button next to Library Search Path (-L) and click on the Workspace button, and select the folder where we imported the library file. click Ok, and then Ok again.

Linker Search Path

Next you’ll need to specify the name of the library. From the same window click on the Add… button next to Libraries (-l) and type CppUnitLib. Remember our library file is name libCppUnitLite.a, but GCC C++ Linker doesn’t need the lib or .a parts of the name. So if you named your library libMonkey.a, just type Monkey when you add the library :). Click Ok and then Ok again to exit the project Properties window.

Linker Library

Now everything is ready to build and run. Build the project and run it as a C++ Application, and see the output on the console window. You’ll see that it reports the two intentional failures, what conditions that failed, in which files they are, and in which lines as well.

Console

That’s it! As you can see it’s quite easy and simple to work with CppUnitLite. Thanks everyone! Happy unit testing.

About these ads

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s