Skip to content
CppUTest unit testing and mocking framework for C/C++
Branch: master
Clone or download
basvodde Merge pull request #1220 from asgeroverby/enable-cmake-buildtime-disc…

Enable cmake buildtime discover tests for CppUTest clients.
Latest commit 8baa764 Jun 14, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.settings Committing accidentally removed file Aug 4, 2015
build Add -Wno-reserved-id-macro and -Wno-keyword-macro to clang builds. Fi… Jul 1, 2018
builds void operator delete was trying to return something. It caused proble… Sep 12, 2013
cmake Enable cmake buildtime discover tests for CppuUTest clients. Jun 5, 2019
cpputest_build Add final newline Aug 31, 2014
docs Created VS2010 related document and template. Nov 7, 2012
examples remove warning, cast from 'const void *' to 'Event *' drops const qua… Jul 1, 2018
include Merge pull request #1215 from offa/macro_fixes May 11, 2019
m4 Install a generated config.h which is prefixed Apr 18, 2016
platforms add new tests to all build systems Sep 18, 2018
platforms_examples Removed Prag Prog, Grenning copyright. May 17, 2016
scripts Use CPPUTEST_HOME env variable for eclipse project include path Aug 22, 2018
src Enable cmake buildtime discover tests for CppuUTest clients. Jun 5, 2019
tests Merge pull request #1215 from offa/macro_fixes May 11, 2019
.cproject Suggested improvements - hopefully "kosher" Sep 5, 2014
.gitattributes .dep and .mak should be crlf as well Mar 14, 2015
.gitignore Shuffle test execution order with -s Jan 11, 2019
.project fixed the broken eclipse project files Jan 7, 2012
.travis.yml Deprecated travis option removed. Nov 26, 2018
.travis_github_deployer.yml Hopefully this format is final Sep 4, 2014
AUTHORS Files needed for GNU standards Dec 22, 2012
CMakeLists.txt Enable cmake buildtime discover tests for CppuUTest clients. Jun 5, 2019
COPYING Files needed for GNU standards Dec 22, 2012
ChangeLog Fixed a very weird ChangeLog :) May 4, 2015
CppUTest.dep Re-generate .mak and .dep Mar 14, 2015
CppUTest.dsp Add build option for longlong Apr 20, 2016
CppUTest.dsw Revert "Removed non-existing AllTests.dsp from CppUTest.dsw" Mar 11, 2015
CppUTest.mak Add build option for longlong Apr 20, 2016
CppUTest.sln Regenerated and test solution (VS2005) Mar 17, 2015
CppUTest.vcproj Add/Remove headers in project file May 7, 2016
CppUTest.vcxproj Enable warnings as error on release builds Oct 25, 2017 do not include config if target is already defined May 30, 2015 Enable cmake buildtime discover tests for CppuUTest clients. Jun 5, 2019
CppUTest_VS201x.sln Add x64 as a target platform Oct 14, 2017
Doxyfile Small changes to the Doxgen generation. Lots more to do related to that May 3, 2013 Add Shuffle.h to autotools install Jun 12, 2019
Makefile_CppUTestExt Delayed merge from @simshi. Merge request 48 Dec 17, 2012
Makefile_using_MakefileWorker Fix path in old-style makefile for new test folder Nov 11, 2016
NEWS Files needed for GNU standards Dec 22, 2012
README Removed unneeded whitesapce Feb 12, 2015 CPPUTEST_HOME variable prefixed with a $ Apr 22, 2019
README_CppUTest_for_C.txt spelling fixes Nov 4, 2015
README_InstallCppUTest.txt Update READMEs to make working Jan 13, 2016
README_UsersOfPriorVersions.txt Added README for prior users Aug 9, 2007
appveyor.yml Fix all the warnings detected by clang 5.0.0 in C++11 mode Feb 23, 2018 removing the configure call Aug 5, 2014
config.h.cmake Add build option for longlong Apr 20, 2016 Added support for strdup macro replacement on tests. Using auto gener… Nov 11, 2016 - Adding the required linker flags to the pkgcfg. Apr 26, 2013
cpputest_doxy_gen.conf First doxygen file Apr 24, 2013
makeAndRun.bat Add makeAndRun.bat again Mar 14, 2015
makeVS2008.bat Fix the line endings May 7, 2014
makeVS201x.bat ...and again Jan 16, 2015
makeVc6.bat Fix the line endings May 7, 2014
valgrind.suppressions Hope this now also works when the compiler optimizes Aug 19, 2013


CppUTest unit testing and mocking framework for C/C++

More information on the project page

Travis Linux build status: Build Status

AppVeyor Windows build status: Build status

Coverage: Coverage Status

Getting Started

You'll need to do the following to get started:

Building from source (unix-based, cygwin, MacOSX):

  • Download latest version
  • make a build directory and change to it mkdir a_build_dir && cd a_build_dir
  • configure ../configure
  • make
  • make check
  • You can use make install if you want to install CppUTest system-wide

You can also use CMake, which also works for Windows Visual Studio.

  • Download latest version
  • cmake CMakeList.txt
  • make

Then to get started, you'll need to do the following:

  • Add the include path to the Makefile. Something like:
    • CPPFLAGS += -I$(CPPUTEST_HOME)/include
  • Add the memory leak macros to your Makefile (needed for additional debug info!). Something like:
    • CXXFLAGS += -include $(CPPUTEST_HOME)/include/CppUTest/MemoryLeakDetectorNewMacros.h
    • CFLAGS += -include $(CPPUTEST_HOME)/include/CppUTest/MemoryLeakDetectorMallocMacros.h
  • Add the library linking to your Makefile. Something like:
    • LD_LIBRARIES = -L$(CPPUTEST_HOME)/lib -lCppUTest -lCppUTestExt

After this, you can write your first test:


TEST(FirstTestGroup, FirstTest)
   FAIL("Fail me!");

Command line switches

  • -v verbose, print each test name as it runs
  • -r# repeat the tests some number of times, default is one, default if # is not specified is 2. This is handy if you are experiencing memory leaks related to statics and caches.
  • -s# random shuffle the test execution order. # is an integer used for seeding the random number generator. # is optional, and if omitted, the seed value is chosen automatically, which results in a different order every time. The seed value is printed to console to make it possible to reproduce a previously generated execution order. Handy for detecting problems related to dependencies between tests.
  • -g group only run test whose group contains the substring group
  • -n name only run test whose name contains the substring name

Test Macros

  • TEST(group, name) - define a test
  • IGNORE_TEST(group, name) - turn off the execution of a test
  • TEST_GROUP(group) - Declare a test group to which certain tests belong. This will also create the link needed from another library.
  • TEST_GROUP_BASE(group, base) - Same as TEST_GROUP, just use a different base class than Utest
  • TEST_SETUP() - Declare a void setup method in a TEST_GROUP - this is the same as declaring void setup()
  • TEST_TEARDOWN() - Declare a void setup method in a TEST_GROUP
  • IMPORT_TEST_GROUP(group) - Export the name of a test group so it can be linked in from a library. Needs to be done in main.

Set up and tear down support

  • Each TEST_GROUP may contain a setup and/or a teardown method.
  • setup() is called prior to each TEST body and teardown() is called after the test body.

Assertion Macros

The failure of one of these macros causes the current test to immediately exit

  • CHECK(boolean condition) - checks any boolean result
  • CHECK_TRUE(boolean condition) - checks for true
  • CHECK_FALSE(boolean condition) - checks for false
  • CHECK_EQUAL(expected, actual) - checks for equality between entities using ==. So if you have a class that supports operator==() you can use this macro to compare two instances.
  • STRCMP_EQUAL(expected, actual) - check const char* strings for equality using strcmp
  • LONGS_EQUAL(expected, actual) - Compares two numbers
  • BYTES_EQUAL(expected, actual) - Compares two numbers, eight bits wide
  • POINTERS_EQUAL(expected, actual) - Compares two const void *
  • DOUBLES_EQUAL(expected, actual, tolerance) - Compares two doubles within some tolerance
  • ENUMS_EQUAL_INT(excepted, actual) - Compares two enums which their underlying type is int
  • ENUMS_EQUAL_TYPE(underlying_type, excepted, actual) - Compares two enums which they have the same underlying type
  • FAIL(text) - always fails
  • TEST_EXIT - Exit the test without failure - useful for contract testing (implementing an assert fake)

Customize CHECK_EQUAL to work with your types that support operator==()

  • Create the function: SimpleString StringFrom(const yourType&)

The Extensions directory has a few of these.

Building default checks with TestPlugin

  • CppUTest can support extra checking functionality by inserting TestPlugins
  • TestPlugin is derived from the TestPlugin class and can be inserted in the TestRegistry via the installPlugin method.
  • TestPlugins can be used for, for example, system stability and resource handling like files, memory or network connection clean-up.
  • In CppUTest, the memory leak detection is done via a default enabled TestPlugin

Example of a main with a TestPlugin:

int main(int ac, char** av)
   LogPlugin logPlugin;
   int result = CommandLineTestRunner::RunAllTests(ac, av);
   return result;

Memory leak detection

  • A platform specific memory leak detection mechanism is provided.
  • If a test fails and has allocated memory prior to the fail and that memory is not cleaned up by TearDown, a memory leak is reported. It is best to only chase memory leaks when other errors have been eliminated.
  • Some code uses lazy initialization and appears to leak when it really does not (for example: gcc stringstream used to in an earlier release). One cause is that some standard library calls allocate something and do not free it until after main (or never). To find out if a memory leak is due to lazy initialization set the -r switch to run tests twice. The signature of this situation is that the first run shows leaks and the second run shows no leaks. When both runs show leaks, you have a leak to find.

How is memory leak detection implemented?

  • Before setup() a memory usage checkpoint is recorded
  • After teardown() another checkpoint is taken and compared to the original checkpoint
  • In Visual Studio the MS debug heap capabilities are used
  • For GCC a simple new/delete count is used in overridden operators new, new[], delete and delete[]

If you use some leaky code that you can't or won't fix you can tell a TEST to ignore a certain number of leaks as in this example:

TEST(MemoryLeakWarningTest, Ignore1)
    char* arrayToLeak1 = new char[100];

Example Main

#include "CppUTest/CommandLineTestRunner.h"

int main(int ac, char** av)
  return RUN_ALL_TESTS(ac, av);

Example Test

#include "CppUTest/TestHarness.h"
#include "ClassName.h"

  ClassName* className;

  void setup()
    className = new ClassName();
  void teardown()
    delete className;

TEST(ClassName, Create)
  CHECK(0 != className);
  DOUBLES_EQUAL(1.000, 1.001, .01);
  STRCMP_EQUAL("hello", "hello");
  FAIL("The prior tests pass, but this one doesn't");

There are some scripts that are helpful in creating your initial h, cpp, and Test files. See scripts/README.TXT

You can’t perform that action at this time.