4 VTK uses the [ExternalData][] CMake module to handle the 
data management 
for 
    5 its test suite. 
Test data is only downloaded when a test which requires it is
 
    6 enabled and it is cached so that every build does not need to redownload the
 
    9 To facilitate 
this workflow, there are a number of CMake functions available in
 
   10 order to indicate that test 
data is required.
 
   16 get_filename_component(_vtkModuleTesting_dir 
"${CMAKE_CURRENT_LIST_FILE}" DIRECTORY)
 
   21 Data may be downloaded manually 
using this function:
 
   27 This will download 
data inside of the input 
data directory 
for the modules
 
   28 being built at that 
time (see the `TEST_INPUT_DATA_DIRECTORY` argument of
 
   31 For supported `PATHSPEC` syntax, see the
 
   32 [associated 
documentation][ExternalData pathspecs] in `ExternalData`. These
 
   33 arguments are already wrapped in the `DATA{}` syntax and are assumed to be
 
   34 relative paths from the input 
data directory.
 
   36 [ExternalData pathspecs]: TODO
 
   40   foreach (arg IN LISTS ARGN)
 
   41     if (IS_ABSOLUTE 
"${arg}")
 
   46         "DATA{${_vtk_build_TEST_INPUT_DATA_DIRECTORY}/${arg}}")
 
   50   ExternalData_Expand_Arguments("${_vtk_build_TEST_DATA_TARGET}
" _ ${data_args}) 
   54 ## Creating test executables 
   56 This function creates an executable from the list of sources passed to it. It 
   57 is automatically linked to the module the tests are intended for as well as any 
   58 declared test dependencies of the module. 
   61 vtk_module_test_executable(<NAME> <SOURCE>...) 
   64 This function is not usually used directly, but instead through the other 
   65 convenience functions. 
   67 function (vtk_module_test_executable name) 
   68   add_executable("${
name}
" ${ARGN}) 
   69   get_property(test_depends GLOBAL 
   70     PROPERTY "_vtk_module_${_vtk_build_test}_test_depends
") 
   71   get_property(test_optional_depends GLOBAL 
   72     PROPERTY "_vtk_module_${_vtk_build_test}_test_optional_depends
") 
   73   set(optional_depends_flags) 
   74   foreach (test_optional_depend IN LISTS test_optional_depends) 
   75     if (TARGET "${test_optional_depend}
") 
   76       list(APPEND test_depends 
   77         "${test_optional_depend}
") 
   78       set(test_optional_depend_flag "1
") 
   80       set(test_optional_depend_flag "0
") 
   82     string(REPLACE "::
" "_
" safe_test_optional_depend "${test_optional_depend}
") 
   83     list(APPEND optional_depends_flags 
   84       "VTK_MODULE_ENABLE_${safe_test_optional_depend}=${test_optional_depend_flag}
") 
   87   target_link_libraries("${
name}
" 
   91   target_compile_definitions("${
name}
" 
   93       ${optional_depends_flags}) 
   97     MODULES "${_vtk_build_test}
" 
  104 Test names default to using the basename of the filename which contains the 
  105 test. Two tests may share the same file by prefixing with a custom name for the 
  108 The two parsed syntaxes are: 
  110   - `CustomTestName,TestFile` 
  113 Note that `TestFile` should already have had its extension stripped (usually 
  114 done by `_vtk_test_parse_args`). 
  116 In general, the name of a test will be `<EXENAME>-<TESTNAME>`, however, by 
  117 setting `vtk_test_prefix`, the test name will instead be 
  118 `<EXENAME>-<PREFIX><TESTNAME>`. 
  122 This function parses the name from a testspec. The calling scope has 
  123 `test_name` and `test_file` variables set in it. 
  126 _vtk_test_parse_name(<TESTSPEC>) 
  129 function (_vtk_test_parse_name name) 
  130   if (name AND name MATCHES "^([^,]*),(.*)$
") 
  131     set(test_name "${CMAKE_MATCH_1}
" PARENT_SCOPE) 
  132     set(test_file "${CMAKE_MATCH_2}
" PARENT_SCOPE) 
  134     set(test_name "${
name}
" PARENT_SCOPE) 
  135     set(test_file "${
name}
" PARENT_SCOPE) 
  140 ## Test function arguments 
  142 Each test is specified  using one of the two following syntaxes 
  144   - `<NAME>.<SOURCE_EXT>` 
  145   - `<NAME>.<SOURCE_EXT>,<OPTIONS>` 
  147 Where `NAME` is a valid test name. If present, the specified `OPTIONS` are only 
  148 for the associated test. The expected extension is specified by the associated 
  153 Given a list of valid "options
", this function will parse out a the following 
  156   - `args`: Unrecognized arguments. These should be interpreted as arguments 
  157     that should be passed on the command line to all tests in this parse group. 
  158   - `options`: Options specified globally (for all tests in this group). 
  159   - `names`: A list containing all named tests. These should be parsed by 
  160     `_vtk_test_parse_name`. 
  161   - `_<NAME>_options`: Options specific to a certain test. 
  164 _vtk_test_parse_args(<OPTIONS> <SOURCE_EXT> <ARG>...) 
  167 In order to be recognized as a source file, the `SOURCE_EXT` must be used. 
  168 Without it, all non-option arguments are placed into `args`. Each test is 
  169 parsed out matching these: 
  171 function (_vtk_test_parse_args options source_ext) 
  176   foreach (arg IN LISTS ARGN) 
  178     foreach (option IN LISTS options) 
  179       if (arg STREQUAL option) 
  180         list(APPEND global_options "${option}
") 
  187     elseif (source_ext AND arg MATCHES "^([^.]*)\\.${source_ext},?(.*)$
") 
  188       set(name "${CMAKE_MATCH_1}
") 
  189       string(REPLACE ",
" ";
" "_${
name}_options
" "${CMAKE_MATCH_2}
") 
  190       list(APPEND names "${
name}
") 
  192       list(APPEND args "${arg}
") 
  196   foreach (name IN LISTS names) 
  197     set("_${
name}_options
" "${_${
name}_options}
" 
  200   set(options "${global_options}
" 
  209 For handling global option settings, this function sets variables in the 
  210 calling scoped named `<PREFIX><OPTION>` to either `0` or `1` if the option is 
  211 present in the remaining argument list. 
  214 _vtk_test_set_options(<OPTIONS> <PREFIX> <ARG>...) 
  217 Additionally, a non-`0` default for a given option may be specified by a 
  218 variable with the same name as the option and specifying a prefix for the 
  221 function (_vtk_test_set_options options prefix) 
  222   foreach (option IN LISTS options) 
  225       set(default "${${option}}
") 
  227     set("${prefix}${option}
" "${
default}
" 
  230   foreach (option IN LISTS ARGN) 
  231     set("${prefix}${option}
" 1 
  236 # If set, use the maximum number of processors for tests. Otherwise, just use 1 
  237 # processor by default. 
  238 set(VTK_MPI_NUMPROCS "2
" CACHE STRING 
  239   "Number of processors available to run parallel tests.
") 
  240 # Hide the variable if we don't have `MPIEXEC_EXECUTABLE` anyways. 
  241 if (MPIEXEC_EXECUTABLE) 
  242   set(_vtk_mpi_max_numprocs_type STRING) 
  244   set(_vtk_mpi_max_numprocs_type INTERNAL) 
  246 set_property(CACHE VTK_MPI_NUMPROCS 
  248     TYPE "${_vtk_mpi_max_numprocs_type}
") 
  253 This function declares C++ tests. Source files are required to use the `cxx` 
  257 vtk_add_test_cxx(<EXENAME> <VARNAME> <ARG>...) 
  260 Each argument should be either an option, a test specification, or it is passed 
  261 as flags to all tests declared in the group. The list of tests is set in the 
  262 `<VARNAME>` variable in the calling scope. 
  266   - `NO_DATA`: The test does not need to know the test input data directory. If 
  267     it does, it is passed on the command line via the `-D` flag. 
  268   - `NO_VALID`: The test does not have a valid baseline image. If it does, the 
  269     baseline is assumed to be in `../Data/Baseline/<NAME>.png` relative to the 
  270     current source directory. If alternate baseline images are required, 
  271     `<NAME>` may be suffixed by `_1`, `_2`, etc. The valid image is passed via 
  273   - `NO_OUTPUT`: The test does not need to write out any data to the 
  274     filesystem. If it does, a directory which may be written to is passed via 
  277 Additional flags may be passed to tests using the `${_vtk_build_test}_ARGS` 
  278 variable or the `<NAME>_ARGS` variable. 
  280 function (vtk_add_test_cxx exename _tests) 
  285   _vtk_test_parse_args("${cxx_options}
" "cxx
" ${ARGN}) 
  286   _vtk_test_set_options("${cxx_options}
" "" ${options}) 
  288   set(_vtk_fail_regex "(\n|^)ERROR: 
" "instance(s)? still around
") 
  290   foreach (name IN LISTS names) 
  291     _vtk_test_set_options("${cxx_options}
" "local_
" ${_${name}_options}) 
  292     _vtk_test_parse_name("${
name}
") 
  295     if (NOT local_NO_DATA) 
  296       set(_D -D "${_vtk_build_TEST_OUTPUT_DATA_DIRECTORY}
") 
  300     if (NOT local_NO_OUTPUT) 
  301       set(_T -T "${_vtk_build_TEST_OUTPUT_DIRECTORY}
") 
  305     if (NOT local_NO_VALID) 
  306       set(_V -V "DATA{${CMAKE_CURRENT_SOURCE_DIR}/../Data/Baseline/${test_name}.png,:}
") 
  309     ExternalData_add_test("${_vtk_build_TEST_DATA_TARGET}
" 
  310       NAME    "${_vtk_build_test}Cxx-${vtk_test_prefix}${test_name}
" 
  314               ${${_vtk_build_test}_ARGS} 
  317     set_tests_properties("${_vtk_build_test}Cxx-${vtk_test_prefix}${test_name}
" 
  319         LABELS "${_vtk_build_test_labels}
" 
  320         FAIL_REGULAR_EXPRESSION "${_vtk_fail_regex}
" 
  321         # This must match VTK_SKIP_RETURN_CODE in vtkTestingObjectFactory.h 
  325     list(APPEND ${_tests} "${test_file}
") 
  328   set("${_tests}
" ${${_tests}} PARENT_SCOPE) 
  334 This function declares C++ tests which should be run under an MPI environment. 
  335 Source files are required to use the `cxx` extension. 
  338 vtk_add_test_mpi(<EXENAME> <VARNAME> <ARG>...) 
  341 Each argument should be either an option, a test specification, or it is passed 
  342 as flags to all tests declared in the group. The list of tests is set in the 
  343 `<VARNAME>` variable in the calling scope. 
  348   - `NO_VALID`: The test does not have a valid baseline image. If it does, the 
  349     baseline is assumed to be in `../Data/Baseline/<NAME>.png` relative to the 
  350     current source directory. If alternate baseline images are required, 
  351     `<NAME>` may be suffixed by `_1`, `_2`, etc. The valid image is passed via 
  354 Each test is run using the number of processors specified by the following 
  355 variables (using the first one which is set): 
  358   - `<EXENAME>_NUMPROCS` 
  359   - `VTK_MPI_NUMPROCS` (defaults to `2`) 
  361 Additional flags may be passed to tests using the `${_vtk_build_test}_ARGS` 
  362 variable or the `<NAME>_ARGS` variable. 
  364 function (vtk_add_test_mpi exename _tests) 
  369   _vtk_test_parse_args("${mpi_options}
" "cxx
" ${ARGN}) 
  370   _vtk_test_set_options("${mpi_options}
" "" ${options}) 
  372   set(_vtk_fail_regex "(\n|^)ERROR: 
" "instance(s)? still around
") 
  374   set(default_numprocs ${VTK_MPI_NUMPROCS}) 
  375   if (${exename}_NUMPROCS) 
  376     set(default_numprocs ${${exename}_NUMPROCS}) 
  379   foreach (name IN LISTS names) 
  380     _vtk_test_set_options("${mpi_options}
" "local_
" ${_${name}_options}) 
  381     _vtk_test_parse_name(${name}) 
  386     if (local_TESTING_DATA) 
  387       set(_D -D "${_vtk_build_TEST_OUTPUT_DATA_DIRECTORY}
") 
  388       set(_T -T "${_vtk_build_TEST_OUTPUT_DIRECTORY}
") 
  390       if (NOT local_NO_VALID) 
  391         set(_V -V "DATA{${CMAKE_CURRENT_SOURCE_DIR}/../Data/Baseline/${
name}.png,:}
") 
  395     set(numprocs ${default_numprocs}) 
  396     if (${name}_NUMPROCS) 
  397       set(numprocs "${${
name}_NUMPROCS}
") 
  400     ExternalData_add_test("${_vtk_build_TEST_DATA_TARGET}
" 
  401       NAME "${_vtk_build_test}Cxx-MPI-${vtk_test_prefix}${test_name}
" 
  402       COMMAND "${MPIEXEC_EXECUTABLE}
" 
  403               "${MPIEXEC_NUMPROC_FLAG}
" "${numprocs}
" 
  405               "$<TARGET_FILE:${exename}>
" 
  409               ${${_vtk_build_test}_ARGS} 
  411               ${MPIEXEC_POSTFLAGS}) 
  412     set_tests_properties("${_vtk_build_test}Cxx-MPI-${vtk_test_prefix}${test_name}
" 
  414         LABELS "${_vtk_build_test_labels}
" 
  415         PROCESSORS "${numprocs}
" 
  416         FAIL_REGULAR_EXPRESSION "${_vtk_fail_regex}
" 
  417         # This must match VTK_SKIP_RETURN_CODE in vtkTestingObjectFactory.h" 
  420     set_property(TEST 
"${_vtk_build_test}Cxx-MPI-${vtk_test_prefix}${test_name}" APPEND
 
  422         REQUIRED_FILES 
"$<TARGET_FILE:${exename}>")
 
  423     list(APPEND ${_tests} 
"${test_file}")
 
  426   set(${_tests} ${${_tests}} PARENT_SCOPE)
 
  430 ### C++ test executable 
  436 Creates an executable named `EXENAME` which contains the tests listed in the
 
  437 variable named in the `VARNAME` argument. The `EXENAME` must match the
 
  438 `EXENAME` passed to the test declarations when building the list of tests.
 
  440 If `RENDERING_FACTORY` is provided, VTK
's rendering factories are initialized 
  443 Any additional arguments are added as additional sources for the executable. 
  445 function (vtk_test_cxx_executable exename _tests) 
  448   _vtk_test_parse_args("${exe_options}" "" ${ARGN}) 
  449   _vtk_test_set_options("${exe_options}" "" ${options}) 
  452     # No tests -> no need for an executable. 
  456   if (RENDERING_FACTORY) 
  457     include("${_vtkModuleTesting_dir}/vtkTestingRenderingDriver.cmake") 
  458     set(test_driver vtkTestingObjectFactory.h) 
  460     include("${_vtkModuleTesting_dir}/vtkTestingDriver.cmake") 
  461     set(test_driver vtkTestDriver.h) 
  464   set(extra_sources ${args}) 
  466   create_test_sourcelist(test_sources "${exename}.cxx" ${${_tests}} 
  467     EXTRA_INCLUDE "${test_driver}") 
  470     vtk_module_test_executable("${exename}" ${test_sources} ${extra_sources}) 
  472     message(FATAL_ERROR "_vtk_build_test is not set!") 
  477 MPI executables used to have their own test executable function. This is no 
  478 longer necessary and is deprecated. Instead, `vtk_test_cxx_executable` should 
  481 function (vtk_test_mpi_executable exename _tests) 
  483     "The `vtk_test_mpi_executable` function is deprecated; use " 
  484     "`vtk_test_cxx_executable` instead.") 
  485   vtk_test_cxx_executable("${exename}" "${_tests}" ${ARGN}) 
  491 This function declares Python tests. Test files are required to use the `py` 
  495 vtk_add_test_python(<EXENAME> <VARNAME> <ARG>...) 
  500 If the `_vtk_testing_python_exe` variable is not set, the `vtkpython` binary is 
  501 used by default. Additional arguments may be passed in this variable as well. 
  513 Each argument should be either an option, a test specification, or it is passed 
  514 as flags to all tests declared in the group. The list of tests is set in the 
  515 `<VARNAME>` variable in the calling scope. 
  519   - `NO_DATA`: The test does not need to know the test input data directory. If 
  520     it does, it is passed on the command line via the `-D` flag. 
  521   - `NO_OUTPUT`: The test does not need to write out any data to the 
  522     filesystem. If it does, a directory which may be written to is passed via 
  524   - `NO_VALID`: The test does not have a valid baseline image. If it does, the 
  525     baseline is assumed to be in `../Data/Baseline/<NAME>.png` relative to the 
  526     current source directory. If alternate baseline images are required, 
  527     `<NAME>` may be suffixed by `_1`, `_2`, etc. The valid image is passed via 
  529   - `NO_RT`: If `NO_RT` is specified, `-B` is passed instead of `-V`, only 
  530      providing a baseline dir, assuming `NO_VALID` is not specified. 
  531   - `DIRECT_DATA` : If `DIRECT_DATA` is specified, the baseline path will be provided 
  532      as is, without the use of ExternalData_add_test. 
  533   - `JUST_VALID`: Only applies when both `NO_VALID` and `NO_RT` are not 
  534     present. If it is not specified, `-A` is passed with path to the directory 
  535     of the `vtkTclTest2Py` Python package and the test is run via the 
  536     `rtImageTest.py` script. Note that this currently only works when building 
  537     against a VTK build tree; the VTK install tree does not include this script 
  538     or its associated Python package. 
  540 Additional flags may be passed to tests using the `${_vtk_build_test}_ARGS` 
  541 variable or the `<NAME>_ARGS` variable. 
  543 Note that the `vtkTclTest2Py` support will eventually be removed. It is a 
  544 legacy of the conversion of many tests from Tcl to Python. 
  546 function (vtk_add_test_python) 
  547   if (NOT _vtk_testing_python_exe) 
  548     set(_vtk_testing_python_exe "$<TARGET_FILE:VTK::vtkpython>") 
  558   _vtk_test_parse_args("${python_options}" "py" ${ARGN}) 
  559   _vtk_test_set_options("${python_options}" "" ${options}) 
  561   set(_vtk_fail_regex "(\n|^)ERROR: " "instance(s)? still around") 
  563   foreach (name IN LISTS names) 
  564     _vtk_test_set_options("${python_options}" "local_" ${_${name}_options}) 
  565     _vtk_test_parse_name(${name}) 
  568     if (NOT local_NO_DATA) 
  569       set(_D -D "${_vtk_build_TEST_OUTPUT_DATA_DIRECTORY}") 
  576     if (NOT local_NO_VALID) 
  578         if (local_DIRECT_DATA) 
  579           set(_B -B "${CMAKE_CURRENT_SOURCE_DIR}/Data/Baseline/") 
  581           set(_B -B "DATA{${CMAKE_CURRENT_SOURCE_DIR}/../Data/Baseline/,REGEX:${test_name}(-.*)?(_[0-9]+)?.png}") 
  584         if (local_DIRECT_DATA) 
  585           set(_V -V "${CMAKE_CURRENT_SOURCE_DIR}/Data/Baseline/${test_name}.png") 
  587           set(_V -V "DATA{${CMAKE_CURRENT_SOURCE_DIR}/../Data/Baseline/${test_name}.png,:}") 
  589         if (NOT local_JUST_VALID) 
  590           # TODO: This should be fixed to also work from an installed VTK. 
  591           set(rtImageTest "${VTK_SOURCE_DIR}/Utilities/vtkTclTest2Py/rtImageTest.py") 
  592           set(_A -A "${VTK_SOURCE_DIR}/Utilities/vtkTclTest2Py") 
  598     if (NOT local_NO_OUTPUT) 
  599       set(_T -T "${_vtk_build_TEST_OUTPUT_DIRECTORY}") 
  602     if (NOT _vtk_build_TEST_FILE_DIRECTORY) 
  603       set(_vtk_build_TEST_FILE_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}) 
  606     set(testArgs NAME "${_vtk_build_test}Python${_vtk_test_python_suffix}-${vtk_test_prefix}${test_name}" 
  607                  COMMAND ${_vtk_test_python_pre_args} 
  608                          "${_vtk_testing_python_exe}" ${_vtk_test_python_args} --enable-bt 
  610                          "${_vtk_build_TEST_FILE_DIRECTORY}/${test_file}.py" 
  612                          ${${_vtk_build_test}_ARGS} 
  614                          ${_D} ${_B} ${_T} ${_V} ${_A}) 
  616     if (local_DIRECT_DATA) 
  617       add_test(${testArgs}) 
  619       ExternalData_add_test("${_vtk_build_TEST_DATA_TARGET}" ${testArgs}) 
  622     set_tests_properties("${_vtk_build_test}Python${_vtk_test_python_suffix}-${vtk_test_prefix}${test_name}" 
  624         LABELS "${_vtk_build_test_labels}" 
  625         FAIL_REGULAR_EXPRESSION "${_vtk_fail_regex}" 
  626         # This must match the skip() function in vtk/test/Testing.py" 
  635 A small wrapper around `vtk_add_test_python` which adds support for running 
  636 MPI-aware tests written in Python. 
  638 The `$<module library name>_NUMPROCS` variable may be used to use a non-default 
  639 number of processors for a test. 
  641 This forces running with the `pvtkpython` executable. 
  643 function (vtk_add_test_python_mpi) 
  644   set(_vtk_test_python_suffix "-MPI") 
  646   set(numprocs "${VTK_MPI_NUMPROCS}") 
  647   _vtk_module_get_module_property("${_vtk_build_test}" 
  648     PROPERTY "library_name" 
  649     VARIABLE _vtk_test_python_library_name) 
  650   if (${_vtk_test_python_library_name}_NUMPROCS) 
  651     set(numprocs "${${_vtk_test_python_library_name}_NUMPROCS}") 
  654   set(_vtk_test_python_pre_args 
  655     "${MPIEXEC_EXECUTABLE}" 
  656     "${MPIEXEC_NUMPROC_FLAG}" "${numprocs}" 
  659   if (NOT _vtk_testing_python_exe) 
  660     set(_vtk_testing_python_exe "$<TARGET_FILE:VTK::pvtkpython>") 
  662   vtk_add_test_python(${ARGN})