GoogleTest

版本 3.9 中添加。

此模块提供命令以帮助使用 Google Test 基础设施。

在 CMake 项目中加载此模块，使用

include(GoogleTest)

提供了两种添加测试的机制。gtest_add_tests() 已经存在一段时间了，最初是通过 find_package(GTest)。 gtest_discover_tests() 在 CMake 3.10 中引入。

(较旧的) gtest_add_tests() 会扫描源文件以识别测试。这通常是有效的，但也存在一些注意事项，包括在交叉编译环境中，并且使得对测试设置附加属性更加方便。但是，它对参数化测试的处理不够全面，并且需要重新运行 CMake 来检测测试列表中的更改。

(较新的) gtest_discover_tests() 通过询问已编译的测试可执行文件来枚举其测试，从而发现测试。这更健壮，并且能更好地处理参数化测试，而且在测试发生更改时不需要重新运行 CMake。但是，它可能无法在交叉编译环境中工作，并且设置测试属性不太方便。

更多详细信息可以在各自函数的文档中找到。

这两个命令都旨在取代使用 add_test() 来注册测试，并且将为每个 Google Test 测试用例创建一个单独的 CTest 测试。请注意，在某些情况下效率较低，因为共同的设置和拆卸逻辑无法被同一实例中执行的多个测试用例共享。然而，它为 CTest 提供了更细粒度的通过/失败信息，这通常被认为更有益。默认情况下，CTest 测试名称与 Google Test 名称相同（即 suite.testcase）；另请参阅 TEST_PREFIX 和 TEST_SUFFIX。

gtest_add_tests

通过扫描源代码中的 Google Test 宏，自动将测试添加到 CTest

gtest_add_tests(TARGET target
                [SOURCES src1...]
                [EXTRA_ARGS args...]
                [WORKING_DIRECTORY dir]
                [TEST_PREFIX prefix]
                [TEST_SUFFIX suffix]
                [SKIP_DEPENDENCY]
                [TEST_LIST outVar]
)

gtest_add_tests 尝试通过扫描源文件来识别测试。虽然这通常是有效的，但它只使用基本的正则表达式匹配，这可能会被不寻常的测试声明所绕过，并且无法完全“拆分”参数化测试。此外，它要求重新运行 CMake 来发现任何新添加、删除或重命名的测试（默认情况下，这意味着当任何测试源文件被更改时，CMake 都会被重新运行，但请参阅 SKIP_DEPENDENCY）。然而，它的优点是在 CMake 时声明测试，这在一定程度上简化了对测试设置附加属性的过程，并且在交叉编译环境中始终有效。

选项包括

TARGET target

指定 Google Test 可执行文件，它必须是一个已知的 CMake 可执行目标。CMake 在运行测试时将替换已构建可执行文件的位置。

SOURCES src1...

如果提供了此选项，则仅扫描列出的文件以查找测试用例。如果未提供此选项，则将使用指定 target 的 SOURCES 属性来获取源文件列表。

EXTRA_ARGS args...

传递给每个测试用例的命令行上的任何附加参数。

在版本 3.31 中更改： args... 中的空值将被保留，请参阅 CMP0178。

WORKING_DIRECTORY dir

指定运行发现的测试用例的目录。如果未提供此选项，则使用当前二进制目录。

TEST_PREFIX prefix

指定一个 prefix，该前缀将添加到每个已发现测试用例的名称之前。当使用相同的源文件进行多次 gtest_add_test() 调用但具有不同的 EXTRA_ARGS 时，这可能很有用。

TEST_SUFFIX suffix

与 TEST_PREFIX 类似，只是 suffix 将被附加到每个已发现测试用例的名称之后。可以同时指定 TEST_PREFIX 和 TEST_SUFFIX。

SKIP_DEPENDENCY

通常，该函数会创建一个依赖项，当任何正在扫描的源文件发生更改时，该依赖项将导致 CMake 被重新运行。这是为了确保已发现的测试列表已更新。如果不需要此行为（例如，在实际编写测试用例时），可以使用此选项来防止添加依赖项。

TEST_LIST outVar

在调用作用域中，将使用已发现的测试用例列表填充名为 outVar 的变量。这允许调用者执行诸如操作已发现测试的测试属性之类的操作。

在版本 3.31 中更改： TEST_LAUNCHER 和 CROSSCOMPILING_EMULATOR 目标属性中的空值将被保留，请参阅策略 CMP0178。

使用示例

include(GoogleTest)
add_executable(FooTest FooUnitTest.cxx)
gtest_add_tests(TARGET      FooTest
                TEST_SUFFIX .noArgs
                TEST_LIST   noArgsTests
)
gtest_add_tests(TARGET      FooTest
                EXTRA_ARGS  --someArg someValue
                TEST_SUFFIX .withArgs
                TEST_LIST   withArgsTests
)
set_tests_properties(${noArgsTests}   PROPERTIES TIMEOUT 10)
set_tests_properties(${withArgsTests} PROPERTIES TIMEOUT 20)

为了向后兼容，也支持以下形式

gtest_add_tests(exe args files...)

exe

测试可执行文件的路径或 CMake 目标的名称。

args

要传递给可执行文件的附加参数的 ;-list。整个列表必须作为单个参数传递。将其括在引号中，或传递 "" 表示无参数。

files...

要搜索测试和测试夹具的源文件列表。或者，使用 AUTO 来指定 exe 是一个 CMake 可执行目标的名称，该目标的源应被扫描。

include(GoogleTest)
set(FooTestArgs --foo 1 --bar 2)
add_executable(FooTest FooUnitTest.cxx)
gtest_add_tests(FooTest "${FooTestArgs}" AUTO)

gtest_discover_tests

通过查询已编译的测试可执行文件以获取可用测试，自动将测试添加到 CTest

gtest_discover_tests(target
                     [EXTRA_ARGS args...]
                     [WORKING_DIRECTORY dir]
                     [TEST_PREFIX prefix]
                     [TEST_SUFFIX suffix]
                     [TEST_FILTER expr]
                     [NO_PRETTY_TYPES] [NO_PRETTY_VALUES]
                     [PROPERTIES name1 value1...]
                     [TEST_LIST var]
                     [DISCOVERY_TIMEOUT seconds]
                     [XML_OUTPUT_DIR dir]
                     [DISCOVERY_MODE <POST_BUILD|PRE_TEST>]
                     [DISCOVERY_EXTRA_ARGS args...]
)

3.10 版本新增。

gtest_discover_tests() 在测试可执行文件上设置一个构建后命令或测试前命令，该命令通过解析运行测试可执行文件与 --gtest_list_tests 参数的输出来生成测试列表。与 gtest_add_tests() 的源解析方法相比，这确保了获得了完整的测试列表，包括参数化测试的实例化。由于测试发现发生在构建或测试时，因此在测试列表发生更改时无需重新运行 CMake。但是，它要求正确设置 CROSSCOMPILING_EMULATOR 以便在交叉编译环境中运行。

此外，为测试设置属性有点不方便，因为测试在 CMake 时不可用。可以使用 PROPERTIES 选项将附加测试属性应用于整个测试集。如果需要更细粒度的测试控制，可以通过外部 CTest 脚本提供自定义内容，使用 TEST_INCLUDE_FILES 目录属性。通过 <target>_TESTS 变量可将已发现的测试集提供给此类脚本（有关进一步讨论和限制，请参阅下面的 TEST_LIST 选项）。

选项包括

目标

指定 Google Test 可执行文件，它必须是一个已知的 CMake 可执行目标。CMake 在运行测试时将替换已构建可执行文件的位置。

EXTRA_ARGS args...

传递给每个测试用例的命令行上的任何附加参数。

在版本 3.31 中更改： args... 中的空值将被保留，请参阅 CMP0178。

WORKING_DIRECTORY dir

指定运行发现的测试用例的目录。如果未提供此选项，则使用当前二进制目录。

TEST_PREFIX prefix

指定一个 prefix，该前缀将添加到每个已发现测试用例的名称之前。当使用相同的测试可执行文件进行多次 gtest_discover_tests() 调用但具有不同的 EXTRA_ARGS 时，这可能很有用。

TEST_SUFFIX suffix

与 TEST_PREFIX 类似，只是 suffix 将被附加到每个已发现测试用例的名称之后。可以同时指定 TEST_PREFIX 和 TEST_SUFFIX。

TEST_FILTER expr

3.22 版本新增。

过滤表达式，将在测试发现期间作为 --gtest_filter 参数传递。请注意，该表达式是基于通配符的格式，用于匹配 gtest 使用的原始测试名称。对于类型或值参数化测试，这些名称可能与 ctest 使用的可能被美化打印的测试名称不同。

NO_PRETTY_TYPES

默认情况下，类型参数化测试的类型索引将被实际类型名称替换，作为 CTest 测试名称的一部分。如果此行为不受欢迎（例如，因为类型名称很笨重），此选项将禁止此行为。

NO_PRETTY_VALUES

默认情况下，值参数化测试的值索引将被实际值替换，作为 CTest 测试名称的一部分。如果此行为不受欢迎（例如，因为值字符串很笨重），此选项将禁止此行为。

PROPERTIES name1 value1...

指定要在此 gtest_discover_tests() 调用发现的所有测试上设置的附加属性。

TEST_LIST var

使测试列表在变量 var 中可用，而不是默认的 <target>_TESTS。当使用相同的测试可执行文件进行多次 gtest_discover_tests() 调用时，这会很有用。请注意，此变量仅在 CTest 中可用。

由于 CMake 解析规则的限制，名称中包含方括号的任何测试都将被从存储在此变量中的测试列表中省略。然而，此类测试仍将被 ctest 正常定义和执行。

DISCOVERY_TIMEOUT num

已在版本 3.10.3 中添加。

指定 CMake 将等待测试枚举可用测试的时间（以秒为单位）。如果测试花费的时间超过此时间，则发现（以及您的构建）将失败。大多数测试可执行文件会非常快地枚举其测试，但在某些特殊情况下，测试可能需要更长的超时时间。默认为 5。另请参阅 execute_process() 的 TIMEOUT 选项。

注意

在 CMake 版本 3.10.1 和 3.10.2 中，此选项名为 TIMEOUT。这与 TIMEOUT 测试属性发生冲突，而 TIMEOUT 测试属性是使用 PROPERTIES 关键字设置的常见属性之一，通常会导致合法但非预期的行为。在 CMake 3.10.3 中，该关键字已更改为 DISCOVERY_TIMEOUT 以解决此问题。3.10.1 和 3.10.2 中 TIMEOUT 关键字的含糊行为未被保留。

XML_OUTPUT_DIR dir

在 3.18 版本中新增。

如果指定，参数将与 --gtest_output=xml: 一起传递给测试可执行文件。实际文件名与测试目标相同，包括前缀和后缀。应使用此选项而不是 EXTRA_ARGS --gtest_output=xml 来避免在使用并行测试执行时写入 XML 结果输出的竞争条件。

DISCOVERY_MODE

在 3.18 版本中新增。

提供对 gtest_discover_tests() 执行测试发现时间的更大控制。默认情况下，POST_BUILD 设置一个构建后命令以在构建时执行测试发现。在某些情况下，例如交叉编译，这种 POST_BUILD 行为是不受欢迎的。相比之下，PRE_TEST 会将测试发现延迟到测试执行之前。这样，测试发现将在目标环境中进行，测试在该环境中更有可能找到适当的运行时依赖项。

DISCOVERY_MODE 默认为 CMAKE_GTEST_DISCOVER_TESTS_DISCOVERY_MODE 变量的值（如果调用 gtest_discover_tests() 时未传递）。这提供了一种机制，可以全局选择首选的测试发现行为，而无需修改每个调用站点。

DISCOVERY_EXTRA_ARGS args...

在版本 3.31 中添加。

为发现命令传递到命令行上的任何附加参数。

已在版本 3.29 中添加： TEST_LAUNCHER 目标属性在测试发现和测试执行期间会被考虑。

在版本 3.31 中更改： TEST_LAUNCHER 和 CROSSCOMPILING_EMULATOR 目标属性中的空值将被保留，请参阅策略 CMP0178。