discover_tests: Add documentation

Help/command/discover_tests.rst

@@ -0,0 +1,117 @@
+discover_tests
+--------------
+
+Register tests with names and properties discovered at test time by
+:manual:`ctest(1)`.
+
+.. code-block:: cmake
+
+  discover_tests(COMMAND <command> [<arg>...] [COMMAND_EXPAND_LISTS]
+    [CONFIGURATIONS <config>...]
+    DISCOVERY_ARGS <arg>...
+    DISCOVERY_MATCH <regex>
+    [DISCOVERY_PROPERTIES <key> <value> [<key> <value>]...]
+    TEST_NAME <replacement>
+    TEST_ARGS <replacement>...
+    [TEST_PROPERTIES <key> <replacement> [<key> <replacement>]...]
+  )
+
+This command configures test discovery rather than defining a single test at
+configure time.  During test execution, :manual:`ctest(1)` runs the specified
+discovery command, parses its output, and registers one or more tests based on
+the provided regular expression and replacement strings.
+
+``discover_tests`` options are:
+
+``COMMAND``
+  Specify the command-line used for test discovery.
+
+  The command is executed by :manual:`ctest(1)` at test time (not by CMake at
+  configure time).  With ``DISCOVERY_ARGS`` appended, it must print the list of
+  available tests in a format matched by ``DISCOVERY_MATCH``.
+
+  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 target's :prop_tgt:`CROSSCOMPILING_EMULATOR`, if set, will be
+    used to run the command on the host::
+
+      <emulator> <command>
+
+    The emulator is used only when
+    :variable:`cross-compiling <CMAKE_CROSSCOMPILING>`.
+
+  * 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)>`.
+
+``COMMAND_EXPAND_LISTS``
+  Lists in ``COMMAND`` arguments will be expanded, including those created with
+  :manual:`generator expressions <cmake-generator-expressions(7)>`.
+
+``CONFIGURATIONS``
+  Restrict the test discovery only to the named configurations.
+
+``DISCOVERY_ARGS``
+  Additional arguments passed to ``COMMAND`` when performing discovery.
+
+``DISCOVERY_MATCH``
+  Regular expression used to parse each line produced by the discovery command.
+  Capturing groups may be referenced by ``TEST_NAME``, ``TEST_ARGS``, and
+  values in ``TEST_PROPERTIES`` using ``\1``, ``\2``, etc.
+
+``DISCOVERY_PROPERTIES``
+  Specify properties for the discovery run itself.
+
+``TEST_NAME``
+  Replacement string used to generate the test name for each discovered test.
+  It may reference capture groups from ``DISCOVERY_MATCH``.
+
+``TEST_ARGS``
+  Replacement strings used to generate the arguments passed to the discovered
+  test.  Each argument may reference capture groups from ``DISCOVERY_MATCH``.
+
+``TEST_PROPERTIES``
+  Specify test properties to set on each discovered test.  Values are
+  replacement strings and may reference capture groups from
+  ``DISCOVERY_MATCH``.
+
+CTest executes the discovery step to obtain the list of tests and then runs
+each discovered test using the command-line produced by ``COMMAND`` together
+with ``TEST_ARGS``.  The pass/fail behavior of each discovered test follows
+the usual CTest rules (exit code ``0`` indicates success unless inverted by
+the :prop_test:`WILL_FAIL` property). 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.
+
+Example usage:
+
+.. code-block:: cmake
+
+  discover_tests(COMMAND testDriver --exe $<TARGET_FILE:myexe>
+    DISCOVERY_ARGS --list-tests
+    DISCOVERY_MATCH "^([^,]+),([^,]+),([^,]+),(.*)$"
+    TEST_NAME "${PROJECT_NAME}.\\1.\\2"
+    TEST_ARGS --run-test "\\1.\\2"
+    TEST_PROPERTIES
+      PROCESSORS "\\3"
+      LABELS "\\4"
+  )
+
+This example configures discovery by running ``testDriver --list-tests``.
+For each line of output that matches ``DISCOVERY_MATCH``, a test name is
+generated using ``TEST_NAME``, the per-test command-line is generated using
+``TEST_ARGS``, and test properties are populated from the remaining capture
+groups.

Help/manual/cmake-commands.7.rst

@@ -94,6 +94,7 @@ These commands are available only in CMake projects.
    /command/cmake_instrumentation
    /command/create_test_sourcelist
    /command/define_property
+   /command/discover_tests
    /command/enable_language
    /command/enable_testing
    /command/export

Help/release/dev/discover-tests.rst

@@ -0,0 +1,7 @@
+discover-tests
+--------------
+
+* The :command:`discover_tests` command was added to support registering tests
+  discovered at test time by :manual:`ctest(1)`. It runs a user-provided
+  discovery command, parses its output, and generates test names, arguments,
+  and properties from regular-expression captures.