# discover_tests

Added in version 4.4.

Register tests with names and properties discovered at test time by `ctest(1)`.

    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, `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 `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 `add_executable()`:

  - It will automatically be replaced by the location of the executable created at build time.

  - The target's `CROSSCOMPILING_EMULATOR`, if set, will be used to run the command on the host:

        <emulator> <command>

    The emulator is used only when `cross-compiling`.

  - The target's `TEST_LAUNCHER`, if set, will be used to launch the command:

        <launcher> <command>

    If the `CROSSCOMPILING_EMULATOR` is also set, both are used:

        <launcher> <emulator> <command>

  The command may be specified using `generator expressions`.

`COMMAND_EXPAND_LISTS`

  Lists in `COMMAND` arguments will be expanded, including those created with `generator expressions`.

`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 `WILL_FAIL` property). Output written to stdout or stderr is captured by `ctest(1)` and only affects the pass/fail status via the `PASS_REGULAR_EXPRESSION`, `FAIL_REGULAR_EXPRESSION`, or `SKIP_REGULAR_EXPRESSION` test properties.

Example usage:

    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.