# 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.