ECMAddTests

Convenience functions for adding tests.

ecm_add_tests(<sources>
    [COMPILE_DEFINITIONS <definition> [<definition> [...]]] # Since 6.13.0
    [ENVIRONMENT <list>]  # Since 6.13.0
    LINK_LIBRARIES <library> [<library> [...]]
    [NAME_PREFIX <prefix> (| NO_NAME_PREFIX] # Since 6.22.0)
    [GUI]
    [TARGET_NAMES_VAR <target_names_var>]
    [TEST_NAMES_VAR <test_names_var>]
    [WORKING_DIRECTORY <dir>] #  Since 5.111
)

A convenience function for adding multiple tests, each consisting of a single source file. For each file in <sources>, an executable target is created (whose name is the base name of the source file) with the compiler definitions passed with COMPILE_DEFINITIONS. This will be linked against the libraries given with LINK_LIBRARIES. Each executable will be added as a test with the same name and can have an environment provided by ENVIRONMENT.

If NAME_PREFIX is given, this prefix will be prepended to the test names, but not the target names. As a result, it will not prevent clashes between tests with the same name in different parts of the project, but it can be used to give an indication of where to look for a failing test. If NAME_PREFIX is not set, it will default to a value depending on the strategy as controlled by the variable ECM_TEST_NAME_PREFIX_STRATEGY, if set in the current scope and NO_NAME_PREFIX is not set (since 6.22).

If the flag GUI is passed the test binaries will be GUI executables, otherwise the resulting binaries will be console applications (regardless of the value of CMAKE_WIN32_EXECUTABLE or CMAKE_MACOSX_BUNDLE). Be aware that this changes the executable entry point on Windows (although some frameworks, such as Qt, abstract this difference away).

The tests will be build with -DQT_FORCE_ASSERTS to enable assertions in the test executable even for release builds.

The TARGET_NAMES_VAR and TEST_NAMES_VAR arguments, if given, should specify a variable name to receive the list of generated target and test names, respectively. This makes it convenient to apply properties to them as a whole, for example, using set_target_properties() or set_tests_properties().

The generated target executables will have the effects of ecm_mark_as_test() (from the ECMMarkAsTest module) applied to it.

WORKING_DIRECTORY sets the test property WORKING_DIRECTORY in which to execute the test. By default the test will be run in ${CMAKE_CURRENT_BINARY_DIR}. The working directory can be specified using generator expressions. Since 5.111.

ecm_add_test(
    <sources>
    [COMPILE_DEFINITIONS <definition> [<definition> [...]]] # Since 6.13.0
    [ENVIRONMENT <list>]  # Since 6.13.0
    LINK_LIBRARIES <library> [<library> [...]]
    [TEST_NAME <name>]
    [NAME_PREFIX <prefix> (| NO_NAME_PREFIX] # Since 6.22.0)
    [GUI]
    [TARGET_NAME_VAR <target_name_var>]
    [TEST_NAME_VAR <test_name_var>]
    [WORKING_DIRECTORY <dir>] #  Since 5.111
)

This is a single-test form of ecm_add_tests that allows multiple source files to be used for a single test. If using multiple source files, TEST_NAME must be given; this will be used for both the target and test names.

As with ecm_add_tests(), the NAME_PREFIX argument will be prepended to the test name. If NAME_PREFIX is not set, it will default to a value depending on the strategy as controlled by the variable ECM_TEST_NAME_PREFIX_STRATEGY, if set in the current scope and NO_NAME_PREFIX is not set (since 6.22).

The TARGET_NAME_VAR and TEST_NAME_VAR arguments, if given, should specify a variable name to receive the generated target and test name, respectively. This makes it convenient to apply properties to them as a whole, for example, using set_target_properties() or set_tests_properties().

WORKING_DIRECTORY sets the test property WORKING_DIRECTORY in which to execute the test. By default the test will be run in ${CMAKE_CURRENT_BINARY_DIR}. The working directory can be specified using generator expressions. Since 5.111.

ecm_test_set_dir_properties( # Since 6.22.0
    [DIR <dir>]
    [PREFIX_NAME <name>]
    [PREFIX_NAME_IGNORE | PREFIX_NAME_NOT_IGNORE]
    [FIRST_PREFIX_NAME]
    [LAST_PREFIX_NAME]
)

The function can be used to set properties to individual directories to influence the behaviour of the test functions. The properties will be set to the current source directory. For source directories which themselves do not have a CMakeLists.txt file and thus are not added by any add_subdirectory() calls, the DIR argument can be used to instead set the property to any such subdirectory <dir>.

PREFIX_NAME can be used to override by <name> the name derived from the given directory.

PREFIX_NAME_IGNORE or PREFIX_NAME_NOT_IGNORE can be used to override the filtering done by ECM_TEST_NAME_PREFIX_IGNORE_DIRS for the name of the given directory.

FIRST_PREFIX_NAME and LAST_PREFIX_NAME can be used to limit the range of directories in the path used for deriving the prefix name.

ecm_test_get_name_prefix( # Since 6.22.0
    <name_prefix_var>
)

The name_prefix_var argument should specify a variable name to receive the default test prefix name for the current scope, based on the value of ECM_TEST_NAME_PREFIX_STRATEGY and the respective further setup.

ECM_TEST_NAME_PREFIX_STRATEGY # Since 6.22.0

This variable is specifying the strategy to use when estimating the default test name prefix to use by the macros ecm_add_tests() and ecm_add_test() when no explicit NAME_PREFIX argument is passed. The supported values are:

• VARIABLE: The default name prefix is taken from the value of the variable ECM_TEST_NAME_PREFIX in the scope where the macros are called.

• PATH: The default name prefix is derived from the relative path of the current source directory where the macros are called, by replacing the dir separators with “-“. See also ECM_TEST_NAME_PREFIX_IGNORE_DIRS for skipping some directory names.

When unset, the VARIABLE strategy is used.

ECM_TEST_NAME_PREFIX # Since 6.22.0

When ECM_TEST_NAME_PREFIX_STRATEGY is set to VARIABLE, the current value of the variable is used as default for the test name prefix.

ECM_TEST_NAME_PREFIX_IGNORE_DIRS # Since 6.22.0

When ECM_TEST_NAME_PREFIX_STRATEGY is set to PATH, this variable is used to filter out directory names in the relative path of the current source directory when deriving the name prefix. By default the variable is set to “src”, “test”, “tests”, “autotest”, “autotests” when including the ECMAddTest module, if not already defined.

Example usage:

set(ECM_TEST_NAME_PREFIX_STRATEGY "PATH")
list(APPEND ECM_TEST_NAME_PREFIX_IGNORE_DIRS "plugins")

# Being in subdir "src/plugins/foo" this test will get
# the test name prefix set to "foo-", next to base name "mytest":
ecm_add_test(
    mytest.cpp
    LINK_LIBRARIES mylib
)

Since pre-1.0.0.