UnitC++ is a modern, light weight, header-only c++ library for making unit testing easy. The intention of UnitC++ is to make it really easy to test c++ code in a portable way.
For Users
UnitC++ has a project page on SourceForge which has versioned downloads.
For Developers
UnitC++ is stored in a mercurial repository centrally at bitbucket. The best way to get it is to clone it onto local disk. Like so.
cd ~
hg clone https://davidcorne@bitbucket.org/davidcorne/unitcpp
You can also download/clone it from GitHub at https://github.com/davidcorne/UnitCpp
.
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++).
Writing a test
The first thing to do is include <UnitCpp/Test.h>
. This is the header whihc 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.
#include <UnitCpp/Test.h>
TEST(MyString, length_test)
{
//...
}
TEST(MyString, validity_test)
{
//...
}
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 TEST
macro.
Now you are ready to write the test code. UnitC++ provided some helpful macros for writing tests. Here is a list of them.
TEST_EQUAL(A, B)
TEST_NOT_EQUAL(A, B)
TEST_LESS_THAN(A, B)
TEST_MORE_THAN(A, B)
TEST_APPROX_EQUAL(A, B, TOLERANCE)
TEST_TRUE(A)
TEST_FALSE(A)
TEST_THROWS(FUNCTION, EXCEPTION, ...)
So here is a filled out version of the above example of a test.
#include <UnitCpp/Test.h>
TEST(MyString, length_test)
{
MyString str("This is a string");
TEST_EQUAL(str.length(), 16);
TEST_NOT_EQUAL(str.length(), 17);
TEST_LESS_THAN(str.length(), 20);
TEST_MORE_THAN(str.length(), 10);
TEST_APPROX_EQUAL(str.length(), 15, 1.1); // test the length is within 1.1 of 15
}
TEST(MyString, validity_test)
{
MyString invalid_string;
TEST_FALSE(invalid_string.valid());
MyString valid_string("");
TEST_TRUE(valid_string.valid());
#ifdef UNITCPP_TEST_THROWS_AVAILABLE
TEST_THROWS([&](){invalid_string.length();}, MyString::InvalidStringException);
#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.
In each TEST
you can use functions from TestCase
. This means for example, you can call test_equal<double>(1, some_function())
if you want the values to be compared as doubles
s not int
s.
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.
#include <UnitCpp/TestRegister.h>
int main()
{
return UnitCpp::TestRegister::test_register().run_tests();
}
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.
Working examples
In the Example
folder there is a working example for a further demonstration of some of the capabilities of UnitC++.
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 https://bitbucket.org/davidcorne/unitcpp/issues?status=new&status=open 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 g++
, clang
and cl
. On drone.io I test g++
and clang
and I test/develop with g++
and cl
on my windows machine using cygwin. The current state of the drone.io build is .
How does it work?
Each TEST
does 3 things:
TestCase
.run()
.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 wide 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.
The GitHub site is a mirror of the mercurial repository. So you should use mercurial and bitbucket. Send me a pull request at https://davidcorne@bitbucket.org/davidcorne/unitcpp and I'll get back to you.