Help/command/add_test.rst

add_test
--------

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

.. code-block:: cmake

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

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

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

Tests added with the ``add_test(NAME)`` signature support using
:manual:`generator expressions <cmake-generator-expressions(7)>`
in test properties set by :command:`set_property(TEST)` or
:command:`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
  :command:`add_executable`:

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

  * .. versionadded:: 3.3

      The target's :prop_tgt:`CROSSCOMPILING_EMULATOR`, if set, will be
      used to run the command on the host::

        <emulator> <command>

      .. versionchanged:: 3.29

        The emulator is used only when
        :variable:`cross-compiling <CMAKE_CROSSCOMPILING>`.
        See policy :policy:`CMP0158`.

  * .. versionadded:: 3.29

      The target's :prop_tgt:`TEST_LAUNCHER`, if set, will be
      used to launch the command::

        <launcher> <command>

      If the :prop_tgt:`CROSSCOMPILING_EMULATOR` is also set, both are used::

        <launcher> <emulator> <command>

  * .. versionadded:: 4.4

      When the :variable:`CMAKE_TEST_BUILD_DEPENDS` variable is enabled,
      the :ref:`Ninja Generators` and :generator:`FASTBuild` generate a
      convenience build target named
      ``test_prep/<name>`` that depends on the test executable target. Building
      this target ensures the executable is up-to-date before the test runs.

      Additionally, targets referenced by the test command via generator
      expressions are added as dependencies of the ``test_prep/<name>`` target.

      If multiple tests in different directories share the same name, their
      dependencies are merged into a single ``test_prep/<name>`` target.

      Tests with names that are not valid target names are excluded from this
      behavior.

      The ``BUILD_DEPENDS`` keyword can be used to add explicit build
      dependencies.

    .. versionchanged:: 4.5

      :generator:`FASTBuild` and the :ref:`Makefile Generators` gained support
      for ``test_prep/<name>`` targets.  With the Makefile generators a
      ``BUILD_DEPENDS`` file is built by building the target whose build
      produces it; a file that is not the unique output of a single target is
      reported with a warning, and a test whose name contains a ``:`` character
      is excluded.

  The command may be specified using
  :manual:`generator expressions <cmake-generator-expressions(7)>`.

``CONFIGURATIONS``
  Restrict execution of the test only to the named configurations.

``WORKING_DIRECTORY``
  Set the test property :prop_test:`WORKING_DIRECTORY` in which to execute the
  test. If not specified, the test will be run in
  :variable:`CMAKE_CURRENT_BINARY_DIR`. The working directory may be specified
  using :manual:`generator expressions <cmake-generator-expressions(7)>`.

``BUILD_DEPENDS``
  .. versionadded:: 4.4

  Specify a list of targets or files that must be built before the test can
  run. Each dependency is added to the ``test_prep/<name>`` build target
  described above when :variable:`CMAKE_TEST_BUILD_DEPENDS` is enabled with the
  :ref:`Ninja Generators`, :generator:`FASTBuild`, or :ref:`Makefile
  Generators`. The test name must be a valid target name in order to list
  build dependencies with this keyword.

  * .. versionchanged:: 4.5

    Build dependencies added by this argument, or referenced in the test
    ``COMMAND`` also enable the :option:`--out-of-date <ctest --out-of-date>`
    behavior of :manual:`ctest(1)`.

``COMMAND_EXPAND_LISTS``
  .. versionadded:: 3.16

  Lists in ``COMMAND`` arguments will be expanded, including those created with
  :manual:`generator expressions <cmake-generator-expressions(7)>`.

If the test command exits with code ``0`` the test passes. Non-zero exit code
is a "failed" test. The test property :prop_test:`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 :manual:`ctest(1)` and only
affects the pass/fail status via the :prop_test:`PASS_REGULAR_EXPRESSION`,
:prop_test:`FAIL_REGULAR_EXPRESSION`, or :prop_test:`SKIP_REGULAR_EXPRESSION`
test properties.

.. versionadded:: 3.16
  Added :prop_test:`SKIP_REGULAR_EXPRESSION` property.

Example usage:

.. code-block:: cmake

  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:

.. code-block:: cmake

  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 :manual:`generator expressions <cmake-generator-expressions(7)>`
in the command-line or test properties, and the :prop_tgt:`TEST_LAUNCHER`
and :prop_tgt:`CROSSCOMPILING_EMULATOR` target properties are not supported.