mirror of
https://github.com/Kitware/CMake.git
synced 2026-08-13 17:07:57 +00:00
ba6b6fbc24
Add `test_prep/<test_name>` convenience targets to the ninja generator to build dependencies of tests, and `test_prep/all` to build the dependencies of all tests. Build dependencies of a test include: - Executables directly invoked by test `COMMAND`. - Targets mentioned in generator expressionf os test `COMMAND`. - Anything explicitly listed with the new `BUILD_DEPENDS` argument of `add_test`. Issue: #27613
148 lines
5.3 KiB
ReStructuredText
148 lines
5.3 KiB
ReStructuredText
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` 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.
|
|
|
|
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`. The test name must be a valid target name
|
|
in order to list build dependencies with this keyword.
|
|
|
|
``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.
|