diff --git a/Help/command/enable_testing.rst b/Help/command/enable_testing.rst index 7bae5c08f9..4a45aacb96 100644 --- a/Help/command/enable_testing.rst +++ b/Help/command/enable_testing.rst @@ -1,20 +1,51 @@ enable_testing -------------- -Enable testing for current directory and below. +Enables testing for the current directory and below: .. code-block:: cmake enable_testing() -Enables testing for this directory and below. - -This command should be in the top-level source directory because +This command should be invoked in the top-level source directory because :manual:`ctest(1)` expects to find a test file in the top-level build directory. -This command is automatically invoked when the :module:`CTest` +This command is also automatically invoked when the :module:`CTest` module is included, except if the :variable:`BUILD_TESTING` option is turned off. -See also the :command:`add_test` command. +The following restrictions apply to where ``enable_testing()`` may be called: + +* It must be called in file scope, not in a :command:`function` call nor inside + a :command:`block`. + +Examples +^^^^^^^^ + +In the following example, this command is conditionally called depending on how +the project is used. For instance, when the Example project is added via the +:module:`FetchContent` module as a subdirectory of a parent project that defines +its own tests, testing for the Example project is disabled. + +.. code-block:: cmake + :caption: ``CMakeLists.txt`` + + project(Example) + + option(Example_ENABLE_TESTING "Enable testing" ${PROJECT_IS_TOP_LEVEL}) + + if(Example_ENABLE_TESTING) + enable_testing() + endif() + + # ... + + if(Example_ENABLE_TESTING) + add_test(...) + endif() + +See Also +^^^^^^^^ + +* The :command:`add_test` command.