Cmake Cppunit

This module defines functions to help use the Google Test infrastructure. Twomechanisms for adding tests are provided. gtest_add_tests() has beenaround for some time, originally via find_package(GTest).gtest_discover_tests() was introduced in CMake 3.10.

The (older) gtest_add_tests() scans source files to identify tests.This is usually effective, with some caveats, including in cross-compilingenvironments, and makes setting additional properties on tests more convenient.However, its handling of parameterized tests is less comprehensive, and itrequires re-running CMake to detect changes to the list of tests.

Update: Hudson for C/CMake/CppUnit Revised. As a follow-up to Using grails projects in Hudson, here is another not-so-standard usage of Hudson: C projects with CMake and CppUnit. Let’s see how that works out. As long as you have Java/Ant/JUnit based projects, a fine tool that it is, configuration of Hudson is pretty straight forward. CMAKEINCLUDECURRENTDIR¶ Automatically add the current source and build directories to the include path. If this variable is enabled, CMake automatically adds CMAKECURRENTSOURCEDIR and CMAKECURRENTBINARYDIR to the include path for each directory. These additional include directories do not propagate down to subdirectories.

The (newer) gtest_discover_tests() discovers tests by asking thecompiled test executable to enumerate its tests. This is more robust andprovides better handling of parameterized tests, and does not require CMaketo be re-run when tests change. However, it may not work in a cross-compilingenvironment, and setting test properties is less convenient.

More details can be found in the documentation of the respective functions.

Both commands are intended to replace use of add_test() to registertests, and will create a separate CTest test for each Google Test test case.Note that this is in some cases less efficient, as common set-up and tear-downlogic cannot be shared by multiple test cases executing in the same instance.However, it provides more fine-grained pass/fail information to CTest, which isusually considered as more beneficial. By default, the CTest test name is thesame as the Google Test name (i.e. suite.testcase); see alsoTEST_PREFIX and TEST_SUFFIX.

gtest_add_tests
Cmake cppunit 2

Automatically add tests with CTest by scanning source code for Google Testmacros:

gtest_add_tests attempts to identify tests by scanning source files.Although this is generally effective, it uses only a basic regular expressionmatch, which can be defeated by atypical test declarations, and is unable tofully 'split' parameterized tests. Additionally, it requires that CMake bere-run to discover any newly added, removed or renamed tests (by default,this means that CMake is re-run when any test source file is changed, but seeSKIP_DEPENDENCY). However, it has the advantage of declaring tests atCMake time, which somewhat simplifies setting additional properties on tests,and always works in a cross-compiling environment.

The options are:

TARGETtarget

Specifies the Google Test executable, which must be a known CMakeexecutable target. Plex oculus go. CMake will substitute the location of the builtexecutable when running the test.

SOURCESsrc1..

When provided, only the listed files will be scanned for test cases. Ifthis option is not given, the SOURCES property of thespecified target will be used to obtain the list of sources.

EXTRA_ARGSarg1..

Any extra arguments to pass on the command line to each test case.

Install
WORKING_DIRECTORYdir

Specifies the directory in which to run the discovered test cases. If thisoption is not provided, the current binary directory is used.

TEST_PREFIXprefix

Cmake Cppunit 2

Specifies a prefix to be prepended to the name of each discovered testcase. This can be useful when the same source files are being used inmultiple calls to gtest_add_test() but with different EXTRA_ARGS.

TEST_SUFFIXsuffix

Similar to TEST_PREFIX except the suffix is appended to the name ofevery discovered test case. Both TEST_PREFIX and TEST_SUFFIX maybe specified.

SKIP_DEPENDENCY

Normally, the function creates a dependency which will cause CMake to bere-run if any of the sources being scanned are changed. This is to ensurethat the list of discovered tests is updated. If this behavior is notdesired (as may be the case while actually writing the test cases), thisoption can be used to prevent the dependency from being added.

TEST_LISToutVar

The variable named by outVar will be populated in the calling scopewith the list of discovered test cases. This allows the caller to dothings like manipulate test properties of the discovered tests.

Usage example:

For backward compatibility, the following form is also supported:

Cmake
exe

The path to the test executable or the name of a CMake target.

args

A ;-list of extra arguments to be passed to executable. The entirelist must be passed as a single argument. Enclose it in quotes,or pass ' for no arguments.

files..

A list of source files to search for tests and test fixtures.Alternatively, use AUTO to specify that exe is the nameof a CMake executable target whose sources should be scanned.

gtest_discover_tests

Automatically add tests with CTest by querying the compiled test executablefor available tests:

New in version 3.10.

gtest_discover_tests() sets up a post-build command on the test executablethat generates the list of tests by parsing the output from running the testwith the --gtest_list_tests argument. Compared to the source parsingapproach of gtest_add_tests(), this ensures that the full list oftests, including instantiations of parameterized tests, is obtained. Sincetest discovery occurs at build time, it is not necessary to re-run CMake whenthe list of tests changes.However, it requires that CROSSCOMPILING_EMULATOR is properly setin order to function in a cross-compiling environment.

Additionally, setting properties on tests is somewhat less convenient, sincethe tests are not available at CMake time. Additional test properties may beassigned to the set of tests as a whole using the PROPERTIES option. Ifmore fine-grained test control is needed, custom content may be providedthrough an external CTest script using the TEST_INCLUDE_FILESdirectory property. The set of discovered tests is made accessible to such ascript via the <target>_TESTS variable.

The options are:

target

Cppunit Cmake Test

Specifies the Google Test executable, which must be a known CMakeexecutable target. CMake will substitute the location of the builtexecutable when running the test.

EXTRA_ARGSarg1..

Any extra arguments to pass on the command line to each test case.

WORKING_DIRECTORYdir

Specifies the directory in which to run the discovered test cases. If thisoption is not provided, the current binary directory is used.

TEST_PREFIXprefix

Specifies a prefix to be prepended to the name of each discovered testcase. This can be useful when the same test executable is being used inmultiple calls to gtest_discover_tests() but with differentEXTRA_ARGS.

TEST_SUFFIXsuffix

Similar to TEST_PREFIX except the suffix is appended to the name ofevery discovered test case. Both TEST_PREFIX and TEST_SUFFIX maybe specified.

NO_PRETTY_TYPES

By default, the type index of type-parameterized tests is replaced by theactual type name in the CTest test name. If this behavior is undesirable(e.g. because the type names are unwieldy), this option will suppress thisbehavior.

NO_PRETTY_VALUES

By default, the value index of value-parameterized tests is replaced by theactual value in the CTest test name. If this behavior is undesirable(e.g. because the value strings are unwieldy), this option will suppressthis behavior.

PROPERTIESname1value1..

Specifies additional properties to be set on all tests discovered by thisinvocation of gtest_discover_tests().

TEST_LISTvar

Make the list of tests available in the variable var, rather than thedefault <target>_TESTS. This can be useful when the same testexecutable is being used in multiple calls to gtest_discover_tests().Note that this variable is only available in CTest.

DISCOVERY_TIMEOUTnum

Specifies how long (in seconds) CMake will wait for the test to enumerateavailable tests. If the test takes longer than this, discovery (and yourbuild) will fail. Most test executables will enumerate their tests veryquickly, but under some exceptional circumstances, a test may require alonger timeout. The default is 5. See also the TIMEOUT option ofexecute_process().

Note

In CMake versions 3.10.1 and 3.10.2, this option was called TIMEOUT.This clashed with the TIMEOUT test property, which is one of thecommon properties that would be set with the PROPERTIES keyword,usually leading to legal but unintended behavior. The keyword waschanged to DISCOVERY_TIMEOUT in CMake 3.10.3 to address thisproblem. The ambiguous behavior of the TIMEOUT keyword in 3.10.1and 3.10.2 has not been preserved.

XML_OUTPUT_DIRdir

If specified, the parameter is passed along with --gtest_output=xml:to test executable. The actual file name is the same as the test target,including prefix and suffix. This should be used instead ofEXTRA_ARGS--gtest_output=xml to avoid race conditions writing theXML result output when using parallel test execution.

DISCOVERY_MODE

New in version 3.18.

Provides greater control over when gtest_discover_tests() performs testdiscovery. By default, POST_BUILD sets up a post-build commandto perform test discovery at build time. In certain scenarios, likecross-compiling, this POST_BUILD behavior is not desirable.By contrast, PRE_TEST delays test discovery until just prior to testexecution. This way test discovery occurs in the target environmentwhere the test has a better chance at finding appropriate runtimedependencies.

DISCOVERY_MODE defaults to the value of theCMAKE_GTEST_DISCOVER_TESTS_DISCOVERY_MODE variable if it is notpassed when calling gtest_discover_tests(). This provides a mechanismfor globally selecting a preferred test discovery behavior without havingto modify each call site.

General Testing Information

In your main CMakeLists.txt you need to add the following function call (not in a subfolder):

Which will enable testing and set a BUILD_TESTING option so users can turn testing on and off (along with a few other things). Or you can do this yourself by directly calling enable_testing().

When you add your test folder, you should do something like this:

The reason for this is that if someone else includes your package, and they use BUILD_TESTING, they probably do not want your tests to build. In the rare case that you really do want to enable testing on both packages, you can provide an override:

The main use case for the override above is actually in this book's own examples, as the master CMake project really does want to run all the subproject tests.

You can register targets with:

If you put something else besides a target name after COMMAND, it will register as a command line to run. It would also be valid to put the generator expression:

which would use the output location (thus, the executable) of the produced target.

Cmake Cppunit

Building as part of a test

If you want to run CMake to build a project as part of a test, you can do that too (in fact, this is how CMake tests itself). For example, if your master project was called MyProject and you had an examples/simple project that could build by itself, this would look like:

Testing Frameworks

Look at the subchapters for recipes for popular frameworks.

  • GoogleTest: A popular option from Google. Development can be a bit slow.
  • Catch2: A modern, PyTest-like framework with clever macros.
  • DocTest: A replacement for Catch2 that is supposed to compile much faster and be cleaner. See Catch2 chapter and replace with DocTest.