1# Distributed under the OSI-approved BSD 3-Clause License. See accompanying 2# file Copyright.txt or https://cmake.org/licensing for details. 3 4#[=======================================================================[.rst: 5Catch 6----- 7 8This module defines a function to help use the Catch test framework. 9 10The :command:`catch_discover_tests` discovers tests by asking the compiled test 11executable to enumerate its tests. This does not require CMake to be re-run 12when tests change. However, it may not work in a cross-compiling environment, 13and setting test properties is less convenient. 14 15This command is intended to replace use of :command:`add_test` to register 16tests, and will create a separate CTest test for each Catch test case. Note 17that this is in some cases less efficient, as common set-up and tear-down logic 18cannot be shared by multiple test cases executing in the same instance. 19However, it provides more fine-grained pass/fail information to CTest, which is 20usually considered as more beneficial. By default, the CTest test name is the 21same as the Catch name; see also ``TEST_PREFIX`` and ``TEST_SUFFIX``. 22 23.. command:: catch_discover_tests 24 25 Automatically add tests with CTest by querying the compiled test executable 26 for available tests:: 27 28 catch_discover_tests(target 29 [TEST_SPEC arg1...] 30 [EXTRA_ARGS arg1...] 31 [WORKING_DIRECTORY dir] 32 [TEST_PREFIX prefix] 33 [TEST_SUFFIX suffix] 34 [PROPERTIES name1 value1...] 35 [TEST_LIST var] 36 ) 37 38 ``catch_discover_tests`` sets up a post-build command on the test executable 39 that generates the list of tests by parsing the output from running the test 40 with the ``--list-test-names-only`` argument. This ensures that the full 41 list of tests is obtained. Since test discovery occurs at build time, it is 42 not necessary to re-run CMake when the list of tests changes. 43 However, it requires that :prop_tgt:`CROSSCOMPILING_EMULATOR` is properly set 44 in order to function in a cross-compiling environment. 45 46 Additionally, setting properties on tests is somewhat less convenient, since 47 the tests are not available at CMake time. Additional test properties may be 48 assigned to the set of tests as a whole using the ``PROPERTIES`` option. If 49 more fine-grained test control is needed, custom content may be provided 50 through an external CTest script using the :prop_dir:`TEST_INCLUDE_FILES` 51 directory property. The set of discovered tests is made accessible to such a 52 script via the ``<target>_TESTS`` variable. 53 54 The options are: 55 56 ``target`` 57 Specifies the Catch executable, which must be a known CMake executable 58 target. CMake will substitute the location of the built executable when 59 running the test. 60 61 ``TEST_SPEC arg1...`` 62 Specifies test cases, wildcarded test cases, tags and tag expressions to 63 pass to the Catch executable with the ``--list-test-names-only`` argument. 64 65 ``EXTRA_ARGS arg1...`` 66 Any extra arguments to pass on the command line to each test case. 67 68 ``WORKING_DIRECTORY dir`` 69 Specifies the directory in which to run the discovered test cases. If this 70 option is not provided, the current binary directory is used. 71 72 ``TEST_PREFIX prefix`` 73 Specifies a ``prefix`` to be prepended to the name of each discovered test 74 case. This can be useful when the same test executable is being used in 75 multiple calls to ``catch_discover_tests()`` but with different 76 ``TEST_SPEC`` or ``EXTRA_ARGS``. 77 78 ``TEST_SUFFIX suffix`` 79 Similar to ``TEST_PREFIX`` except the ``suffix`` is appended to the name of 80 every discovered test case. Both ``TEST_PREFIX`` and ``TEST_SUFFIX`` may 81 be specified. 82 83 ``PROPERTIES name1 value1...`` 84 Specifies additional properties to be set on all tests discovered by this 85 invocation of ``catch_discover_tests``. 86 87 ``TEST_LIST var`` 88 Make the list of tests available in the variable ``var``, rather than the 89 default ``<target>_TESTS``. This can be useful when the same test 90 executable is being used in multiple calls to ``catch_discover_tests()``. 91 Note that this variable is only available in CTest. 92 93#]=======================================================================] 94 95#------------------------------------------------------------------------------ 96function(catch_discover_tests TARGET) 97 cmake_parse_arguments( 98 "" 99 "" 100 "TEST_PREFIX;TEST_SUFFIX;WORKING_DIRECTORY;TEST_LIST" 101 "TEST_SPEC;EXTRA_ARGS;PROPERTIES" 102 ${ARGN} 103 ) 104 105 if(NOT _WORKING_DIRECTORY) 106 set(_WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}") 107 endif() 108 if(NOT _TEST_LIST) 109 set(_TEST_LIST ${TARGET}_TESTS) 110 endif() 111 112 ## Generate a unique name based on the extra arguments 113 string(SHA1 args_hash "${_TEST_SPEC} ${_EXTRA_ARGS}") 114 string(SUBSTRING ${args_hash} 0 7 args_hash) 115 116 # Define rule to generate test list for aforementioned test executable 117 set(ctest_include_file "${CMAKE_CURRENT_BINARY_DIR}/${TARGET}_include-${args_hash}.cmake") 118 set(ctest_tests_file "${CMAKE_CURRENT_BINARY_DIR}/${TARGET}_tests-${args_hash}.cmake") 119 get_property(crosscompiling_emulator 120 TARGET ${TARGET} 121 PROPERTY CROSSCOMPILING_EMULATOR 122 ) 123 add_custom_command( 124 TARGET ${TARGET} POST_BUILD 125 BYPRODUCTS "${ctest_tests_file}" 126 COMMAND "${CMAKE_COMMAND}" 127 -D "TEST_TARGET=${TARGET}" 128 -D "TEST_EXECUTABLE=$<TARGET_FILE:${TARGET}>" 129 -D "TEST_EXECUTOR=${crosscompiling_emulator}" 130 -D "TEST_WORKING_DIR=${_WORKING_DIRECTORY}" 131 -D "TEST_SPEC=${_TEST_SPEC}" 132 -D "TEST_EXTRA_ARGS=${_EXTRA_ARGS}" 133 -D "TEST_PROPERTIES=${_PROPERTIES}" 134 -D "TEST_PREFIX=${_TEST_PREFIX}" 135 -D "TEST_SUFFIX=${_TEST_SUFFIX}" 136 -D "TEST_LIST=${_TEST_LIST}" 137 -D "CTEST_FILE=${ctest_tests_file}" 138 -P "${_CATCH_DISCOVER_TESTS_SCRIPT}" 139 VERBATIM 140 ) 141 142 file(WRITE "${ctest_include_file}" 143 "if(EXISTS \"${ctest_tests_file}\")\n" 144 " include(\"${ctest_tests_file}\")\n" 145 "else()\n" 146 " add_test(${TARGET}_NOT_BUILT-${args_hash} ${TARGET}_NOT_BUILT-${args_hash})\n" 147 "endif()\n" 148 ) 149 150 if(NOT ${CMAKE_VERSION} VERSION_LESS "3.10.0") 151 # Add discovered tests to directory TEST_INCLUDE_FILES 152 set_property(DIRECTORY 153 APPEND PROPERTY TEST_INCLUDE_FILES "${ctest_include_file}" 154 ) 155 else() 156 # Add discovered tests as directory TEST_INCLUDE_FILE if possible 157 get_property(test_include_file_set DIRECTORY PROPERTY TEST_INCLUDE_FILE SET) 158 if (NOT ${test_include_file_set}) 159 set_property(DIRECTORY 160 PROPERTY TEST_INCLUDE_FILE "${ctest_include_file}" 161 ) 162 else() 163 message(FATAL_ERROR 164 "Cannot set more than one TEST_INCLUDE_FILE" 165 ) 166 endif() 167 endif() 168 169endfunction() 170 171############################################################################### 172 173set(_CATCH_DISCOVER_TESTS_SCRIPT 174 ${CMAKE_CURRENT_LIST_DIR}/CatchAddTests.cmake 175) 176