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})
Tests instantiations of the vtkNew class template.
function vtk_module_build()
Build modules and kits
function vtk_test_cxx_executable(exename, _tests)
.md C++ test executable
function vtk_module_test_data()
.md vtkModuleTesting