1add_test
2--------
3
4Add a test to the project to be run by :manual:`ctest(1)`.
5
6.. code-block:: cmake
7
8  add_test(NAME <name> COMMAND <command> [<arg>...]
9           [CONFIGURATIONS <config>...]
10           [WORKING_DIRECTORY <dir>]
11           [COMMAND_EXPAND_LISTS])
12
13Adds a test called ``<name>``.  The test name may contain arbitrary
14characters, expressed as a :ref:`Quoted Argument` or :ref:`Bracket Argument`
15if necessary.  See policy :policy:`CMP0110`.  The options are:
16
17``COMMAND``
18  Specify the test command-line.  If ``<command>`` specifies an
19  executable target (created by :command:`add_executable`) it will
20  automatically be replaced by the location of the executable created
21  at build time.
22
23``CONFIGURATIONS``
24  Restrict execution of the test only to the named configurations.
25
26``WORKING_DIRECTORY``
27  Set the :prop_test:`WORKING_DIRECTORY` test property to
28  specify the working directory in which to execute the test.
29  If not specified the test will be run with the current working
30  directory set to the build directory corresponding to the
31  current source directory.
32
33``COMMAND_EXPAND_LISTS``
34  .. versionadded:: 3.16
35
36  Lists in ``COMMAND`` arguments will be expanded, including those
37  created with
38  :manual:`generator expressions <cmake-generator-expressions(7)>`.
39
40The given test command is expected to exit with code ``0`` to pass and
41non-zero to fail, or vice-versa if the :prop_test:`WILL_FAIL` test
42property is set.  Any output written to stdout or stderr will be
43captured by :manual:`ctest(1)` but does not affect the pass/fail status
44unless the :prop_test:`PASS_REGULAR_EXPRESSION`,
45:prop_test:`FAIL_REGULAR_EXPRESSION` or
46:prop_test:`SKIP_REGULAR_EXPRESSION` test property is used.
47
48.. versionadded:: 3.16
49  Added :prop_test:`SKIP_REGULAR_EXPRESSION` property.
50
51The ``COMMAND`` and ``WORKING_DIRECTORY`` options may use "generator
52expressions" with the syntax ``$<...>``.  See the
53:manual:`cmake-generator-expressions(7)` manual for available expressions.
54
55Example usage:
56
57.. code-block:: cmake
58
59  add_test(NAME mytest
60           COMMAND testDriver --config $<CONFIG>
61                              --exe $<TARGET_FILE:myexe>)
62
63This creates a test ``mytest`` whose command runs a ``testDriver`` tool
64passing the configuration name and the full path to the executable
65file produced by target ``myexe``.
66
67.. note::
68
69  CMake will generate tests only if the :command:`enable_testing`
70  command has been invoked.  The :module:`CTest` module invokes the
71  command automatically unless the ``BUILD_TESTING`` option is turned
72  ``OFF``.
73
74---------------------------------------------------------------------
75
76.. code-block:: cmake
77
78  add_test(<name> <command> [<arg>...])
79
80Add a test called ``<name>`` with the given command-line.  Unlike
81the above ``NAME`` signature no transformation is performed on the
82command-line to support target names or generator expressions.
83