GoogleTest¶

版本 3.9 中添加。

本模块定义了帮助使用 Google Test 基础设施的函数。提供了两种添加测试的机制。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: 要传递给可执行文件的额外参数的 ;-列表。整个列表必须作为单个参数传递。将其用引号括起来，或者传递""表示没有参数。
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测试属性冲突，后者是通常通过PROPERTIES关键字设置的常见属性之一，通常会导致合法但不预期的行为。TIMEOUT关键字在 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将测试发现延迟到测试执行之前。这样，测试发现发生在目标环境中，测试更有可能找到适当的运行时依赖项。

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

DISCOVERY_EXTRA_ARGS args...

在版本 3.31 中添加。

要为发现命令在命令行上传递的任何额外参数。

3.29 版本新增: TEST_LAUNCHER目标属性在测试发现和测试执行期间都会得到遵守。

3.31 版本更改: TEST_LAUNCHER和CROSSCOMPILING_EMULATOR目标属性中的空值将保留，参见策略CMP0178。

GoogleTest¶

上一主题

下一主题

本页