add_test

Add a test to the project to be run by ctest(1).

add_test(NAME <name> COMMAND <command> [<arg>...]
         [CONFIGURATIONS <config>...]
         [WORKING_DIRECTORY <dir>]
         [COMMAND_EXPAND_LISTS])

Adds a test called <name>. The test name may contain arbitrary characters, expressed as a Quoted Argument or Bracket Argument if necessary. See policy CMP0110.

CMake only generates tests if the enable_testing() command has been invoked. The CTest module invokes enable_testing automatically unless BUILD_TESTING is set to OFF.

Tests added with the add_test(NAME) signature support using generator expressions in test properties set by set_property(TEST) or set_tests_properties(). Test properties may only be set in the directory the test is created in.

add_test options are:

COMMAND

Specify the test command-line.

If <command> specifies an executable target created by add_executable():

• It will automatically be replaced by the location of the executable created at build time.

• Added in version 3.3: The target's CROSSCOMPILING_EMULATOR, if set, will be used to run the command on the host:

  <emulator> <command>
  

  Changed in version 3.29: The emulator is used only when cross-compiling. See policy CMP0158.

• Added in version 3.29: The target's TEST_LAUNCHER, if set, will be used to launch the command:

  <launcher> <command>
  

  If the CROSSCOMPILING_EMULATOR is also set, both are used:

  <launcher> <emulator> <command>
  

The command may be specified using generator expressions.

CONFIGURATIONS

Restrict execution of the test only to the named configurations.

WORKING_DIRECTORY

Set the test property WORKING_DIRECTORY in which to execute the test. If not specified, the test will be run in CMAKE_CURRENT_BINARY_DIR. The working directory may be specified using generator expressions.

COMMAND_EXPAND_LISTS

Added in version 3.16.

Lists in COMMAND arguments will be expanded, including those created with generator expressions.

If the test command exits with code 0 the test passes. Non-zero exit code is a "failed" test. The test property WILL_FAIL inverts this logic. Note that system-level test failures such as segmentation faults or heap errors will still fail the test even if WILL_FAIL is true. Output written to stdout or stderr is captured by ctest(1) and only affects the pass/fail status via the PASS_REGULAR_EXPRESSION, FAIL_REGULAR_EXPRESSION, or SKIP_REGULAR_EXPRESSION test properties.

Added in version 3.16: Added SKIP_REGULAR_EXPRESSION property.

Example usage:

add_test(NAME mytest
         COMMAND testDriver --config $<CONFIG>
                            --exe $<TARGET_FILE:myexe>)

This creates a test mytest whose command runs a testDriver tool passing the configuration name and the full path to the executable file produced by target myexe.

---

The command syntax above is recommended over the older, less flexible form:

add_test(<name> <command> [<arg>...])

Add a test called <name> with the given command-line.

Unlike the above NAME signature, target names are not supported in the command-line. Furthermore, tests added with this signature do not support generator expressions in the command-line or test properties.