CetTest

This module defines the function cet_test() to specify tests, and the related utility functions cet_test_env(), and cet_test_assertion().

cet_test

Define a test target for execution by ctest(1)

See also

add_test().

cet_test([BUILD_EXECUTABLE] <target> <build-options> [<install-options>]
         [NO_AUTO|<test-options>])
cet_test(COMPILE_ONLY <target> <build-options> [NO_AUTO|<test-options>])
cet_test(HANDBUILT <target> [<install-options>] [NO_AUTO|<test-options>])
cet_test(PREBUILT <target> [DEPENDENCIES <dep-target> ...] [<install-options>]
         [NO_AUTO|<test-options>])
cet_test(BUILD_EXECUTABLE <target> <build-options> [...])
cet_test([BUILD_EXECUTABLE] <target> <build-options> [<install-options>]
         [NO_AUTO|<test-options>])

Build the test executable with specified build-options in addition to configuring its invocation as a test.

cet_test(COMPILE_ONLY <target> <build-options> [...])

New in version 3.21.00.

cet_test(COMPILE_ONLY <target> <build-options> [NO_AUTO|<test-options>])

Configure a test to compile and link—but not run—an executable.

Note

  • In the event of a configuration failure of the generated project, the test will be marked by ctest(1) as “skipped” rather than failed.

  • The test compilation is implemented as a separate configuration/build of a generated, dedicated project as part of the test run by ctest(1).

  • The project invoking COMPILE_ONLY tests is located by the generated project with find_package(): the project must therefore be capable of being used in this way without being installed. cet_cmake_config() generates suitable configuration for use from within the build tree, but any path variables defined therein must resolve without requiring the package be installed.

  • If compilation failure is required for test success, the test designer is responsible for preventing unwanted test success due to compilation failure for reasons other than those expected.

See also

WILL_FAIL, PASS_REGULAR_EXPRESSION, FAIL_REGULAR_EXPRESSION, SKIP_REGULAR_EXPRESSION.

cet_test(PREBUILT <target> [...])
cet_test(PREBUILT <target> [DEPENDENCIES <dep-target> ...] [<install-options>]
         [NO_AUTO|<test-options>])

Configure a test to run a script.

cet_test(HANDBUILT <target> [...])
cet_test(HANDBUILT <target> [<install-options>] [NO_AUTO|<test-options>])

Configure a test to run an arbitrary executable.

Options

DEPENDENCIES <dep-target> ...

List of top-level dependencies to consider for a PREBUILT target. “Top-level” implies a target (not file) created with add_executable(), add_library() or add_custom_target().

See also

add_dependencies()

NO_AUTO

Do not configure the test(s) with add_test().

Build options

LIBRARIES <library-specification> ...

Library dependencies (passed to target_link_libraries()).

SOURCE <source> ...

Source files from which to build the test executable.

SOURCES <source> ...

Deprecated since version 2.10.00: use SOURCE.

USE_BOOST_UNIT

The executable uses Boost unit test functions and should be compiled and linked accordingly.

USE_CATCH2_MAIN

The executable uses a generic Catch2 main() function and should be compiled and linked accordingly.

USE_CATCH_MAIN

Deprecated since version 2.10.00: use USE_CATCH2_MAIN

Install options

EXPORT_SET <export-set>

The executable will be exported as part of the specified export set.

INSTALL_BIN

Install the test script/executable into the package’s binary directory.

INSTALL_EXAMPLE

Install the test’s source and data files into the package’s examples area.

INSTALL_SOURCE

Install the source files for the test in the package’s source area.

NO_EXPORT

The executable target will not be exported or installed.

Test options

CONFIGURATIONS <config> ...

The test is valid for the specified CMake configuration(s)

DATAFILES <file> ...

Input and/or reference output files to be copied to the test area in the build tree for use by the test. If there is no path, or a relative path, the file is assumed to be in or under CMAKE_CURRENT_SOURCE_DIR.

DIRTY_WORKDIR

If set, the working directory will not be cleared prior to execution of the test.

NO_OPTIONAL_GROUPS

Do not apply any CMake test labels to the configured test(s). Default behavior is to add the labels, DEFAULT and RELEASE to each test.

OPTIONAL_GROUPS <test-group> ...

Add the specified CMake test labels to the configured test(s).

OUTPUT_FILTER <filter>

Specify a single filter for test output. Specify arguments to same with OUTPUT_FILTER_ARGS. Mutually-exclusive with OUTPUT_FILTERS.

OUTPUT_FILTERS "<filter [<filter-args>]>" ...

Specify one or more filters to apply sequentially to test output. Each specified filter with its arguments must be quoted as a single shell “word.” Mutually-exclusive with OUTPUT_FILTER and OUTPUT_FILTER_ARGS.

Note

If no output filters are specified, a default output filter is run to remove dates, times, pointer values and other sources of distinction-without-a-difference. If you wish to invoke this filter in addition to your own, use the alias DEFAULT as a <filter> to specify its position in the filter invocation sequence.

OUTPUT_FILTER_ARGS <arg> ...

Specify arguments to <filter> as specified by OUTPUT_FILTER. Mutually-exclusive with OUTPUT_FILTERS.

PARG_<label> <opt>[=] <opt-val> ...

Specify a parameter axis <label> with values to configure a combinatoric family of tests. <label> must be unique within a single cet_test() invocation. If <opt> is specified with a trailing = then tests will be executed with arguments <opt>=<opt-val> rather than <opt> <opt-val>.

Note

  • Test target names will have _<num> appended, where <num> is zero-padded to ensure the same number of digits are appended to each target name.

  • Permuted arguments will precede TEST_ARGS.

  • In the case of multiple PARG... options, permuted arguments will be combined linearly rather than multiplicatively, with shorter parameter lists being repeated cyclically as necessary.

REF <output-ref> [<error-ref>]

Specify an output and optional error-output reference file with which to compare the (possibly filtered) output of the configured test(s). Incompatible with the CMake test properties PASS_REGULAR_EXPRESSION and FAIL_REGULAR_EXPRESSION.

REMOVE_ON_FAILURE <file-or-dir> ...

Upon TEST_EXEC failure, these files and/or directories shall be removed if they exist.

REQUIRED_FILES <file> ...

These files are required to be present before the test will be executed. If any are missing, ctest will record NOT RUN for this test.

REQUIRED_FIXTURES <test-target> ...

Each specified <test-target> must be run prior to the test(s) currently being configured. If <test-target> is missing from the test selection for a given ctest, it will be added.

REQUIRED_TESTS <test-target> ...

As per REQUIRED_FIXTURES, except that the test selection will only be amended if <PROJECT-NAME>_TEST_DEPS_AS_FIXTURES is TRUE.

*SAN_OPTIONS <val>

Specify the desired value of the corresponding sanitizer control environment variable for the configured test(s).

SCOPED

Test target names will have CETMODULES_CURRENT_PROJECT_NAME: prepended.

TEST_ARGS <arg> ...

Specify arguments to the test executable for the configured test(s).

TEST_EXEC <test-exec>

Specify the executable to be run by the configured test(s). Valid only for HANDBUILT tests.

TEST_PROPERTIES <prop>=<val> ...

Properties to be added to the test.

Note

Properties must be properly escaped to avoid unwanted interpolation by CMake.

See also

set_tests_properties(), CMake target properties.

TEST_WORKDIR <dir>

Test to execute (and support files to be copied to) <dir>. If not specified, ${CMAKE_CURRENT_BINARY_DIR}/<target>.d will be created and used. If relative or not qualified, <dir> is assumed to be releative to ${CMAKE_CURRENT_BINARY_DIR}.

Non-option arguments

<target>

The name of the test target, and/or the build target if one is generated.

cet_test_assertion

Look for the specified assertion failure in test output for the specified targets.

cet_test_assertion(<condition> <target> ...)

Non-option arguments

<condition>

Look for the string Assertion failed: (<condition>), (Darwin) or Assertion `<condition>' failed. (Linux).

<target>

One or more targets to be subject to this test.

See also

PASS_REGULAR_EXPRESSION.

cet_test_env

Add environment variables to the test environment for tests defined in and below the current directory.

See also

CET_TEST_ENV.

cet_test_env([CLEAR] <var>=<val> ...)

Options

CLEAR

Clear the test environment in the current directory scope prior to setting <var>=<val>, including any environment modifications.

See also

cet_test_env_prepend(), CET_TEST_ENV_MODIFICATION.

Details

If the current test environment already has an entry for <var>, it will be superseded by <val>.

cet_test_env_mod

Add environment modifications to the test environment for tests defined in and below the current directory.

See also

CET_TEST_ENV_MODIFICATION, prop_test:ENVIRONMENT_MODIFICATION.

cet_test_env_mod(<var> <op> [CLEAR] [REMOVE_DUPLICATES] <dir> ...)

Options

CLEAR

Clear any existing test environment modifications in the current directory scope.

REMOVE_DUPLICATES

Remove any duplicate <dir> ...; for a given duplicate, only the first entry will be kept.

cet_test_env_prepend

Prepend to path-like environment variables in the test environment for tests defined in and below the current directory.

cet_test_env_prepend(<var> ...)

Functionally identical to cet_test_env_mod(<var> path_list_prepend ...)