# 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.