CTest

Configure a project for testing with CTest/CDash

Include this module in the top CMakeLists.txt file of a project to enable testing with CTest and dashboard submissions to CDash:

project(MyProject)
...
include(CTest)

The module automatically creates the following variables:

BUILD_TESTING

Option selecting whether include(CTest) calls enable_testing(). The option is ON by default when created by the module.

After including the module, use code like:

if(BUILD_TESTING)
  # ... CMake code to create tests ...
endif()

to creating tests when testing is enabled.

To enable submissions to a CDash server, create a CTestConfig.cmake file at the top of the project with content such as:

set(CTEST_NIGHTLY_START_TIME "01:00:00 UTC")
set(CTEST_SUBMIT_URL "http://my.cdash.org/submit.php?project=MyProject")

The CDash server can provide the file to a project administrator who configures MyProject. Settings in the config file are shared by both this CTest module and the ctest(1) command-line Dashboard Client mode (ctest -S).

While building a project for submission to CDash, CTest scans the build output for errors and warnings and reports them with surrounding context from the build log. This generic approach works for all build tools, but does not give details about the command invocation that produced a given problem. One may get more detailed reports by setting the CTEST_USE_LAUNCHERS variable:

set(CTEST_USE_LAUNCHERS 1)

in the CTestConfig.cmake file.

Dashboard Targets

When BUILD_TESTING is enabled, the module also adds custom targets to the build system that run a Dashboard Client from the build tree and submit the results. Each target runs ctest -S on a script generated by the module in CMakeFiles/CTestScript.cmake. The script is configured with the settings collected by the module.

The following targets are added for all generators:

Experimental

Run the Start, Configure, Build, Test, Coverage, and Submit steps in Experimental mode.

Nightly

Run the Start, Update, Configure, Build, Test, Coverage, and Submit steps in Nightly mode.

Continuous

Run the same steps as Nightly in Continuous mode, but stop after the Update step if it reports no changes.

NightlyMemoryCheck

Run the Start, Update, Configure, Build, MemCheck, Coverage, and Submit steps in Nightly mode.

The Makefile Generators, Ninja Generators, and FASTBuild generator also add a <Mode><Step> target for each combination of <Mode> in Experimental, Nightly, and Continuous and <Step> in Start, Update, Configure, Build, Test, Coverage, MemCheck, and Submit. Each runs only that step, such as:

cmake --build . --target ExperimentalTest

See the Dashboard Client documentation for details on each step and mode.