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

  The command may be specified using `generator expressions`.

`CONFIGURATIONS`

  Restrict execution of the test only to the named configurations.

`WORKING_DIRECTORY`

  Set the `WORKING_DIRECTORY` test property to specify the working directory in which to execute the test. If not specified the test will be run with the current working directory set to the build directory corresponding to the current source directory.

  The working directory may be specified using `generator expressions`.

`COMMAND_EXPAND_LISTS`

  New in version 3.16.

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

The given test command is expected to exit with code `0` to pass and non-zero to fail, or vice-versa if the `WILL_FAIL` test property is set. Any output written to stdout or stderr will be captured by `ctest(1)` but does not affect the pass/fail status unless the `PASS_REGULAR_EXPRESSION`, `FAIL_REGULAR_EXPRESSION` or `SKIP_REGULAR_EXPRESSION` test property is used.

New in version 3.16: Added `SKIP_REGULAR_EXPRESSION` property.

Tests added with the `add_test(NAME)` signature support using `generator expressions` in test properties set by `set_property(TEST)` or `set_tests_properties()`.

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

Note

CMake will generate tests only if the `enable_testing()` command has been invoked. The `CTest` module invokes the command automatically unless the `BUILD_TESTING` option is turned `OFF`.

This command also supports a simpler, but less flexible, signature:

    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.