vtkModuleTesting.cmake File Reference

Go to the source code of this file.

Functions
function	vtk_module_test_data ()
	.md
function	vtk_module_test_executable (name)
	.md
function	_vtk_test_parse_name (name, ext)
	.md
function	_vtk_test_parse_args (options, source_ext)
	.md
function	_vtk_test_set_options (options, prefix)
	.md INTERNAL For handling global option settings, this function sets variables in the calling scoped named <PREFIX><OPTION> to either 0 or 1 if the option is present in the remaining argument list.
function	vtk_add_test_cxx (exename, _tests)
	.md
function	vtk_add_test_mpi (exename, _tests)
	.md
function	vtk_test_cxx_executable (exename, _tests)
	.md
function	vtk_test_mpi_executable (exename, _tests)
	.md INTERNAL MPI executables used to have their own test executable function.
function	vtk_add_test_python ()
	.md
function	vtk_add_test_python_mpi ()
	.md

Function Documentation

vtk_module_test_data()

function vtk_module_test_data

(

)

.md

<tt>vtkModuleTesting</tt>

VTK uses the [ExternalData][] CMake module to handle the data management for its test suite. Test data is only downloaded when a test which requires it is enabled and it is cached so that every build does not need to redownload the same data.

To facilitate this workflow, there are a number of CMake functions available in order to indicate that test data is required. .md

Loading data

Data may be downloaded manually using this function:

vtk_module_test_data(<PATHSPEC>...)

This will download data inside of the input data directory for the modules being built at that time (see the TEST_INPUT_DATA_DIRECTORY argument of vtk_module_build).

For supported PATHSPEC syntax, see the [associated documentation][ExternalData pathspecs] in ExternalData. These arguments are already wrapped in the DATA{} syntax and are assumed to be relative paths from the input data directory.

Definition at line 38 of file vtkModuleTesting.cmake.

vtk_module_test_executable()

function vtk_module_test_executable

(

name

)

.md

Creating test executables

This function creates an executable from the list of sources passed to it. It is automatically linked to the module the tests are intended for as well as any declared test dependencies of the module.

vtk_module_test_executable(<NAME> <SOURCE>...)

This function is not usually used directly, but instead through the other convenience functions.

Definition at line 67 of file vtkModuleTesting.cmake.

_vtk_test_parse_name()

function _vtk_test_parse_name	(	name	,
		ext
	)

.md

Test name parsing

Test names default to using the basename of the filename which contains the test. Two tests may share the same file by prefixing with a custom name for the test and a comma.

The two parsed syntaxes are:

• CustomTestName,TestFile
• TestFile

Note that TestFile should already have had its extension stripped (usually done by _vtk_test_parse_args).

In general, the name of a test will be <EXENAME>-<TESTNAME>, however, by setting vtk_test_prefix, the test name will instead be <EXENAME>-<PREFIX><TESTNAME>. .md INTERNAL This function parses the name from a testspec. The calling scope has test_name, test_arg, and test_file variables set in it.

_vtk_test_parse_name(<TESTSPEC>)

Definition at line 132 of file vtkModuleTesting.cmake.

_vtk_test_parse_args()

function _vtk_test_parse_args	(	options	,
		source_ext
	)

.md

Test function arguments

Each test is specified using one of the two following syntaxes

• <NAME>.<SOURCE_EXT>
• <NAME>.<SOURCE_EXT>,<OPTIONS>

Where NAME is a valid test name. If present, the specified OPTIONS are only for the associated test. The expected extension is specified by the associated test function. .md INTERNAL Given a list of valid "options", this function will parse out a the following variables:

• args: Unrecognized arguments. These should be interpreted as arguments that should be passed on the command line to all tests in this parse group.
• options: Options specified globally (for all tests in this group).
• names: A list containing all named tests. These should be parsed by _vtk_test_parse_name.
• _<NAME>_options: Options specific to a certain test.

_vtk_test_parse_args(<OPTIONS> <SOURCE_EXT> <ARG>...)

In order to be recognized as a source file, the SOURCE_EXT must be used. Without it, all non-option arguments are placed into args. Each test is parsed out matching these:

Definition at line 182 of file vtkModuleTesting.cmake.

_vtk_test_set_options()

function _vtk_test_set_options	(	options	,
		prefix
	)

.md INTERNAL For handling global option settings, this function sets variables in the calling scoped named <PREFIX><OPTION> to either 0 or 1 if the option is present in the remaining argument list.

_vtk_test_set_options(<OPTIONS> <PREFIX> <ARG>...)

Additionally, a non-0 default for a given option may be specified by a variable with the same name as the option and specifying a prefix for the output variables.

Definition at line 232 of file vtkModuleTesting.cmake.

vtk_add_test_cxx()

function vtk_add_test_cxx	(	exename	,
		_tests
	)

.md

C++ tests

This function declares C++ tests. Source files are required to use the cxx extension.

vtk_add_test_cxx(<EXENAME> <VARNAME> <ARG>...)

Each argument should be either an option, a test specification, or it is passed as flags to all tests declared in the group. The list of tests is set in the <VARNAME> variable in the calling scope.

Options:

• NO_DATA: The test does not need to know the test input data directory. If it does, it is passed on the command line via the -D flag.
• NO_VALID: The test does not have a valid baseline image. If it does, the baseline is assumed to be in ../Data/Baseline/<NAME>.png relative to the current source directory. If alternate baseline images are required, <NAME> may be suffixed by _1, _2, etc. The valid image is passed via the -V flag.
• NO_OUTPUT: The test does not need to write out any data to the filesystem. If it does, a directory which may be written to is passed via the -T flag.

Additional flags may be passed to tests using the ${_vtk_build_test}_ARGS variable or the <NAME>_ARGS variable.

Definition at line 291 of file vtkModuleTesting.cmake.

vtk_add_test_mpi()

function vtk_add_test_mpi	(	exename	,
		_tests
	)

.md

MPI tests

This function declares C++ tests which should be run under an MPI environment. Source files are required to use the cxx extension.

vtk_add_test_mpi(<EXENAME> <VARNAME> <ARG>...)

Each argument should be either an option, a test specification, or it is passed as flags to all tests declared in the group. The list of tests is set in the <VARNAME> variable in the calling scope.

Options:

• TESTING_DATA
• NO_VALID: The test does not have a valid baseline image. If it does, the baseline is assumed to be in ../Data/Baseline/<NAME>.png relative to the current source directory. If alternate baseline images are required, <NAME> may be suffixed by _1, _2, etc. The valid image is passed via the -V flag.

Each test is run using the number of processors specified by the following variables (using the first one which is set):

• <NAME>_NUMPROCS
• <EXENAME>_NUMPROCS
• VTK_MPI_NUMPROCS (defaults to 2)

Additional flags may be passed to tests using the ${_vtk_build_test}_ARGS variable or the <NAME>_ARGS variable.

Definition at line 402 of file vtkModuleTesting.cmake.

vtk_test_cxx_executable()

function vtk_test_cxx_executable	(	exename	,
		_tests
	)

.md

C++ test executable

vtk_test_cxx_executable(<EXENAME> <VARNAME> [RENDERING_FACTORY] [<SRC>...])

Creates an executable named EXENAME which contains the tests listed in the variable named in the VARNAME argument. The EXENAME must match the EXENAME passed to the test declarations when building the list of tests.

If RENDERING_FACTORY is provided, VTK's rendering factories are initialized during the test.

By default, VTK's rendering tests enable FP exceptions to find floating point errors in debug builds. If DISABLE_FLOATING_POINT_EXCEPTIONS is provided, FP exceptions are not enabled for the test. This is useful when testing against external libraries to ignore exceptions in third-party code.

Any additional arguments are added as additional sources for the executable.

Definition at line 500 of file vtkModuleTesting.cmake.

vtk_test_mpi_executable()

function vtk_test_mpi_executable	(	exename	,
		_tests
	)

.md INTERNAL MPI executables used to have their own test executable function.

This is no longer necessary and is deprecated. Instead, vtk_test_cxx_executable should be used instead.

Definition at line 538 of file vtkModuleTesting.cmake.

vtk_add_test_python()

function vtk_add_test_python

(

)

.md

Python tests

This function declares Python tests. Test files are required to use the py extension.

vtk_add_test_python(<EXENAME> <VARNAME> <ARG>...)

.md INTERNAL If the _vtk_testing_python_exe variable is not set, the vtkpython binary is used by default. Additional arguments may be passed in this variable as well. .md Options:

• NO_DATA
• NO_VALID
• NO_OUTPUT
• NO_RT
• JUST_VALID

Each argument should be either an option, a test specification, or it is passed as flags to all tests declared in the group. The list of tests is set in the <VARNAME> variable in the calling scope.

Options:

• NO_DATA: The test does not need to know the test input data directory. If it does, it is passed on the command line via the -D flag.
• NO_OUTPUT: The test does not need to write out any data to the filesystem. If it does, a directory which may be written to is passed via the -T flag.
• NO_VALID: The test does not have a valid baseline image. If it does, the baseline is assumed to be in ../Data/Baseline/<NAME>.png relative to the current source directory. If alternate baseline images are required, <NAME> may be suffixed by _1, _2, etc. The valid image is passed via the -V flag.
• NO_RT: If NO_RT is specified, -B is passed instead of -V, only providing a baseline dir, assuming NO_VALID is not specified.
• DIRECT_DATA : If DIRECT_DATA is specified, the baseline path will be provided as is, without the use of ExternalData_add_test.
• JUST_VALID: Only applies when both NO_VALID and NO_RT are not present. If it is not specified, -A is passed with path to the directory of the vtkTclTest2Py Python package and the test is run via the rtImageTest.py script. Note that this currently only works when building against a VTK build tree; the VTK install tree does not include this script or its associated Python package.

Additional flags may be passed to tests using the ${_vtk_build_test}_ARGS variable or the <NAME>_ARGS variable.

Note that the vtkTclTest2Py support will eventually be removed. It is a legacy of the conversion of many tests from Tcl to Python.

Definition at line 603 of file vtkModuleTesting.cmake.

vtk_add_test_python_mpi()

function vtk_add_test_python_mpi

(

)

.md

MPI tests

A small wrapper around vtk_add_test_python which adds support for running MPI-aware tests written in Python.

The $<module library name>_NUMPROCS variable may be used to use a non-default number of processors for a test.

This forces running with the pvtkpython executable.

Definition at line 726 of file vtkModuleTesting.cmake.