mirror of
https://github.com/Kitware/CMake.git
synced 2026-11-06 05:16:58 +00:00
Matthew Woehlke
4bbdabae74
Enable test preparation targets by default. Add (better named) `CMAKE_SKIP_TEST_PREP_TARGETS` variable to control generation of the same, mirroring `CMAKE_SKIP_INSTALL_PREP_TARGETS`. Remove support for old `CMAKE_TEST_BUILD_DEPENDS` variable. Update and improve documentation. This improves consistency between test and install preparation targets. It also modifies the descriptions of preparation targets in the documentation of generators which support them to be consistent. (Previously, each generator described preparation targets in a manner unique to each generator.) Fixes: #28050
149 lines
5.2 KiB
ReStructuredText
149 lines
5.2 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.
|
|
|
|
.. versionadded:: 4.4
|
|
Some generators provide ``test_prep/`` build targets that build only the
|
|
prerequisites of tests. See :ref:`Test Preparation Targets`.
|
|
|
|
``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>
|
|
|
|
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 targets or files that need to be built before the test runs.
|
|
They are added as dependencies of the corresponding
|
|
:ref:`Test Preparation Target <Test Preparation Targets>`. This is intended
|
|
for dependencies that CMake cannot infer.
|
|
|
|
Each entry naming an existing target or alias is a target dependency.
|
|
Any other entry names a file, which must exist or be generated by the build.
|
|
|
|
* .. 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)`.
|
|
|
|
Tests with missing build dependencies will not be run.
|
|
|
|
* .. versionchanged:: 4.5
|
|
|
|
A relative file path is interpreted with respect to the current source
|
|
directory if the file exists there, and otherwise with respect to the
|
|
current binary directory.
|
|
|
|
``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.
|