mirror of
https://github.com/Kitware/CMake.git
synced 2026-01-23 23:18:38 -06:00
c705279bae
This change ony concerns directives that appear in the document body. The guidelines for inserting version directives: * Baseline version is CMake 3.0, i.e. directives start at 3.1. * Always use `.. versionadded::` directive, avoid ad-hoc version references. Exception: policy pages. * For new command signatures, put `versionadded` on a separate line after the signature. * For a group of new signatures in a new document section, a single version note at the beginning of the section is sufficient. * For new options, put `versionadded` on a separate line before option description. * If all the option descriptions in the list are short one-liners, it's fine to put `versionadded` on the same line as the description. * If multiple option descriptions in close proximity would have the same ..versionadded directive, consider adding a single directive after the list, mentioning all added options. * For compact value lists and sub-option lists, put a single `versionadded` directive after the list mentioning all additions. * When a change is described in a single paragraph, put `versionadded` into that paragraph. * When only part of the paragraph has changed, separate the changed part if it doesn't break the flow. Otherwise, write a follow-up clarification paragraph and apply version directive to that. * When multiple version directives are close by, order earlier additions before later additions. * Indent related lists and code blocks to include them in the scope of `versionadded` directive. Issue: #19715
83 lines
2.8 KiB
ReStructuredText
83 lines
2.8 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])
|
|
|
|
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`. The 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.
|
|
|
|
``CONFIGURATIONS``
|
|
Restrict execution of the test only to the named configurations.
|
|
|
|
``WORKING_DIRECTORY``
|
|
Set the :prop_test:`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.
|
|
|
|
``COMMAND_EXPAND_LISTS``
|
|
.. versionadded:: 3.16
|
|
|
|
Lists in ``COMMAND`` arguments will be expanded, including those
|
|
created with
|
|
:manual:`generator expressions <cmake-generator-expressions(7)>`.
|
|
|
|
The given test command is expected to exit with code ``0`` to pass and
|
|
non-zero to fail, or vice-versa if the :prop_test:`WILL_FAIL` test
|
|
property is set. Any output written to stdout or stderr will be
|
|
captured by :manual:`ctest(1)` but does not affect the pass/fail status
|
|
unless the :prop_test:`PASS_REGULAR_EXPRESSION`,
|
|
:prop_test:`FAIL_REGULAR_EXPRESSION` or
|
|
:prop_test:`SKIP_REGULAR_EXPRESSION` test property is used.
|
|
|
|
.. versionadded:: 3.16
|
|
Added :prop_test:`SKIP_REGULAR_EXPRESSION` property.
|
|
|
|
The ``COMMAND`` and ``WORKING_DIRECTORY`` options may use "generator
|
|
expressions" with the syntax ``$<...>``. See the
|
|
:manual:`cmake-generator-expressions(7)` manual for available expressions.
|
|
|
|
Example usage:
|
|
|
|
.. code-block:: cmake
|
|
|
|
add_test(NAME mytest
|
|
COMMAND testDriver --config $<CONFIGURATION>
|
|
--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 :command:`enable_testing`
|
|
command has been invoked. The :module:`CTest` module invokes the
|
|
command automatically unless the ``BUILD_TESTING`` option is turned
|
|
``OFF``.
|
|
|
|
---------------------------------------------------------------------
|
|
|
|
.. code-block:: cmake
|
|
|
|
add_test(<name> <command> [<arg>...])
|
|
|
|
Add a test called ``<name>`` with the given command-line. Unlike
|
|
the above ``NAME`` signature no transformation is performed on the
|
|
command-line to support target names or generator expressions.
|