echo/CMake
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Help:add_test: emphasize important points

Browse Source 
* enable_testing must be called to enable testing
* can only set properties on tests created in same directory
* WILL_FAIL still fails on segfault and similar
* compact wording
This commit is contained in:
scivision 2023-02-15 16:09:09 -05:00
parent 37f068083b
commit 6e71c31afd
3 changed files with 35 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

65
Help/command/add_test.rst
View File

@ -12,13 +12,24 @@ Add a test to the project to be run by :manual:`ctest(1)`.
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:
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 ``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.
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.
The command may be specified using
:manual:`generator expressions <cmake-generator-expressions(7)>`.
@ -27,38 +38,29 @@ if necessary. See policy :policy:`CMP0110`. The options are:
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.
The working directory may be specified using
:manual:`generator expressions <cmake-generator-expressions(7)>`.
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)>`.
``COMMAND_EXPAND_LISTS``
.. versionadded:: 3.16
Lists in ``COMMAND`` arguments will be expanded, including those
created with
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.
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_FALL`` 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.
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`.
Example usage:
.. code-block:: cmake
@ -71,16 +73,9 @@ 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``.
---------------------------------------------------------------------
This command also supports a simpler, but less flexible, signature:
The command syntax above is recommended over the older, less flexible form:
.. code-block:: cmake

4
Help/command/set_property.rst
View File

@ -82,8 +82,8 @@ It must be one of the following:
to the installation prefix.
``TEST``
Scope may name zero or more existing tests.
See also the :command:`set_tests_properties` command.
Scope is limited to the directory the command is called in. It may name zero
or more existing tests. See also command :command:`set_tests_properties`.
Test property values may be specified using
:manual:`generator expressions <cmake-generator-expressions(7)>`

5
Help/prop_test/WILL_FAIL.rst
View File

@ -3,5 +3,6 @@ WILL_FAIL
If set to true, this will invert the pass/fail flag of the test.
This property can be used for tests that are expected to fail and
return a non zero return code.
This property can be used for tests that are expected to fail and return a
non-zero return code. Note that system-level test failures such as segmentation
faults or heap errors will still fail the test even if ``WILL_FALL`` is true.