This post is an introduction to a library I have written, UnitC++.
UnitC++ is a modern, light weight, header-only C++ library for making unit testing easy. The intention of this library is to make it really easy to test C++ code in a portable way.
How to Use UnitC++
How to Get UnitC++
UnitC++ is stored in a mercurial repository. The best way to get it is to clone it onto local disk. Like so.
hg clone https://firstname.lastname@example.org/davidcorne/unitcpp
You can also download/clone it from GitHub at https://github.com/davidcorne/UnitCpp.
How to Include UnitC++ in Your Project
As a header-only library, this step should be easy to accomplish. However, while how you do this will vary depending on your build process, it will be straightforward. As this is a header-only library, all you need to do is add the repository path to the compiler include line. Here are two examples of how that is done.
From Command Line
Compiling from the command line, you add the argument
-I $(path_to_unitc++). This works for g++/clang/cl from the command line. This can also be added to the compiler arguments in a makefile.
From Visual Studio
In Visual Studio, you go to Project Properties -> C/C++ -> Additional Include Directories, and browse to $(path_to_unitc++).
How to Write a Unit Test Using UnitC++
Writing a Test
The first thing to do is include. This is the header which will bring in everything you need.
Then you need to declare you are writing a test by writing
TEST(goup_name, test_name). This works like declaring a function, so a set of tests for a class called
MyString will look something like this.
Note: The pattern here is to write several tests for a class with the class as the
group_name and what you are testing as the
test_name in the
Now you are ready to write the test code. UnitC++ provided some helpful macros for writing tests. Here is a list of them.
TEST_APPROX_EQUAL(A, B, TOLERANCE)
TEST_THROWS(FUNCTION, EXCEPTION, ...)
So here is a filled out version of the above example of a test.
MyString str("This is a string");
TEST_APPROX_EQUAL(str.length(), 15, 1.1);
#endif // UNITCPP_TEST_THROWS_AVAILABLE
This is obviously a contrived example, there are several tests checking the same thing, i.e., that the length of
"This is a string" is
16. However, it is an example of how the macros are used.
Note the use of
TEST_THROWS, it is for testing that a certain exception was thrown. It takes a function to call, the exception which should be thrown and the arguments to the function. Note the use of a lambda function, this is because
TEST_THROWS is expecting a function and you want to call a member function.
TEST, you can use functions from
TestCase. This means for example, you can call
test_equal(1, some_function()) if you want the values to be compared as
Running the Tests
So you’ve written a nice set of tests and now you want to run them. This is done with the
TestRegister class. This is a singleton that has registered all of the tests you’ve declared with the
TEST macro. These are run in the following way:
As long as the code with the tests in is linked into the executable,
TestRegister::test_register().run_tests() will run the tests.
You can also call
TestRegister::test_register().run_tests("group_name") to run all the tests in a specific group.
In the Example folder, there is a working example for a further demonstration of some of the capabilities of UnitC++.
Frequently Asked Questions
UnitC++ Doesn’t Work With My Compiler!
Ok, this isn’t actually a commonly asked question. But, if your compiler doesn’t work with UnitC++, please let me know! I will fix this as soon as I can. See _How do I report an issue or request a feature_ for how to let me know, thanks.
How Do I Request a Feature or Report an Issue
I am always happy to take a look at an improvement or fix a bug, you just have to let me know about it. The best way to do this is file an issue on my issue tracker. This is located here don’t be shy, I’m not going to snap at anyone.
Do You Use This?
I made UnitC++ for my personal use. This means that I use it whenever I need to test anything.
How is UnitC++ Tested?
It’s tested using UnitC++ of course! I run continuous integration using drone.io. I currently test it with
drone.io, I test
clang and I test/develop with
cl on my windows machine using cygwin. The current state of the
drone.io build is .
How Does It Work?
TEST does 3 things:
- It defines a class derived from
- It makes a global instance of this class.
- It lets you provide the body of the overriden function
The reason a global object is declared is to call the constructor. In the constructor of
TestCase, it registers itself so
TestRegister knows which tests to run. This is how as long as the objects are linked against,
TestRegister::test_register().run_tests() will run them all.
You Say This is a Modern Library, Why Are There So Many Preprocessor Macros?
This is because unfortunately macros are the best way of doing some things. Macros are used for 2 reasons in UnitC++.
- For judging compiler support. For the
TEST_THROWS functionality, we use variadic templates, this was not supported by Visual Studio until 2013. As pre-2013 Visual Studio compilers are in very widely use, we decided to include this functionality for those with compiler support, and to not break the build of those without.
- For generating good error messages in tests. Compare the following message;
Fail: These arguments should be equal and
Fail: "Maths::sqrt(4.0) should equal 2." utest_Maths.cpp:8. I know I prefer the second one, and getting the line of code, file name and line number cannot be done without macros.
Contributing to UnitC++
The GitHub site is a mirror of the mercurial repository. So you should use mercurial and bitbucket. Send me a pull request at https://email@example.com/davidcorne/unitcpp and I’ll get back to you.