ctest(1)¶

概要 ¶

Run Tests
 ctest [<options>] [--test-dir <path-to-build>]

Build and Test Mode
 ctest --build-and-test <path-to-source> <path-to-build>
       --build-generator <generator> [<options>...]
      [--build-options <opts>...]
      [--test-command <command> [<args>...]]

Dashboard Client
 ctest -D <dashboard>         [-- <dashboard-options>...]
 ctest -M <model> -T <action> [-- <dashboard-options>...]
 ctest -S <script>            [-- <dashboard-options>...]
 ctest -SP <script>           [-- <dashboard-options>...]

View Help
 ctest --help[-<topic>]

描述 ¶

ctest 可执行文件是 CMake 测试驱动程序。为使用 enable_testing() 和 add_test() 命令的项目创建的 CMake 生成树具有测试支持。此程序将运行测试并报告结果。

运行测试 ¶

--preset <preset>, --preset=<preset>¶: 使用测试预设来指定测试选项。项目二进制目录从 configurePreset 键推断。当前工作目录必须包含 CMake 预设文件。有关更多详细信息，请参阅 preset。

--list-presets¶: 列出可用的测试预设。当前工作目录必须包含 CMake 预设文件。

-C <cfg>, --build-config <cfg>¶

选择要测试的配置。

一些 CMake 生成的构建树可以在同一树中具有多个构建配置。此选项可用于指定应测试哪一个。示例配置为 Debug 和 Release。

--progress¶

启用来自测试的简短进度输出。

当 ctest 的输出直接发送到终端时，通过更新同一行而不是在新行上打印每个测试的开始和结束消息来报告测试集的进度。这可以显着减少测试输出的冗长性。测试完成消息仍然在其自己的行上输出，用于失败的测试，并且最终测试摘要也仍将被记录。

也可以通过设置环境变量 CTEST_PROGRESS_OUTPUT 来启用此选项。

-V, --verbose¶

启用来自测试的详细输出。

测试输出通常被抑制，只显示摘要信息。此选项将显示所有测试输出。

-VV, --extra-verbose¶

启用来自测试的更详细的输出。

测试输出通常被抑制，只显示摘要信息。此选项将显示甚至更多的测试输出。

--debug¶

显示 CTest 的更详细的内部信息。

此功能将导致大量输出，这些输出主要用于调试仪表板问题。

--output-on-failure¶: 如果测试失败，则输出测试程序输出的任何内容。也可以通过设置 CTEST_OUTPUT_ON_FAILURE 环境变量来启用此选项

--stop-on-failure¶: 在第一次发生故障时停止运行测试。

-F¶

启用故障转移。

此选项允许 CTest 恢复先前中断的测试集执行。如果未发生中断，则 -F 选项将不起作用。

-j [<level>], --parallel [<level>]¶

并行运行测试，可以选择限制为给定的并行级别。

3.29 版本新增: <level> 可以省略，或者为 0，在这种情况下

在作业服务器集成下，并行性受可用作业令牌的限制。
否则，如果省略该值，则并行性受处理器数量或 2 的限制，以较大者为准。
否则，如果该值为 0，则并行性是无限制的。

此选项也可以通过 CTEST_PARALLEL_LEVEL 环境变量指定。

此选项可以与 PROCESSORS 测试属性一起使用。请参阅标签和子项目摘要。

--resource-spec-file <file>¶

在启用资源分配的情况下运行 CTest，使用 <file> 中指定的资源规范文件。

当 ctest 作为仪表板客户端运行时，这将设置 CTest 测试步骤的 ResourceSpecFile 选项。

--test-load <level>¶

在并行运行测试时（例如，使用 -j），尝试在 CPU 负载可能超过给定阈值时不要启动测试。

当 ctest 作为仪表板客户端运行时，这将设置 CTest 测试步骤的 TestLoad 选项。

-Q, --quiet¶

使 CTest 静默。

此选项将抑制所有输出。如果指定了 --output-log，则仍将生成输出日志文件。如果指定了 --quiet，则会忽略诸如 --verbose、--extra-verbose 和 --debug 之类的选项。

-O <file>, --output-log <file>¶

输出到日志文件。

此选项告诉 CTest 将其所有输出写入 <file> 日志文件。

--output-junit <file>¶

3.21 版本新增。

以 JUnit 格式写入测试结果。

此选项告诉 CTest 以 JUnit XML 格式将测试结果写入 <file>。如果 <file> 已经存在，它将被覆盖。如果使用 -S 选项运行仪表板脚本，请改用带有 ctest_test() 命令的 OUTPUT_JUNIT 关键字。

-N, --show-only[=<format>]¶

禁用测试的实际执行。

此选项告诉 CTest 列出将要运行的测试，但实际上不运行它们。与 -R 和 -E 选项结合使用很有用。

3.14 版本新增: --show-only 选项接受 <format> 值。

<format> 可以是以下值之一。

human
人类友好的输出。这不能保证是稳定的。这是默认值。

json-v1
以 JSON 格式转储测试信息。请参阅显示为 JSON 对象模型。

-L <regex>, --label-regex <regex>¶

运行标签与正则表达式匹配的测试，如 string(REGEX) 中所述。

此选项告诉 CTest 仅运行标签与给定正则表达式匹配的测试。当给出多个 -L 选项时，只有当每个正则表达式都与测试的至少一个标签匹配时，才会运行测试（即，多个 -L 标签形成 AND 关系）。请参阅标签匹配。

-R <regex>, --tests-regex <regex>¶

运行与正则表达式匹配的测试。

此选项告诉 CTest 仅运行名称与给定正则表达式匹配的测试。

-E <regex>, --exclude-regex <regex>¶

排除与正则表达式匹配的测试。

此选项告诉 CTest 不要运行名称与给定正则表达式匹配的测试。

-LE <regex>, --label-exclude <regex>¶

排除标签与正则表达式匹配的测试。

此选项告诉 CTest 不要运行标签与给定正则表达式匹配的测试。当给出多个 -LE 选项时，只有当每个正则表达式都与测试的至少一个标签匹配时，才会排除测试（即，多个 -LE 标签形成 AND 关系）。请参阅标签匹配。

--tests-from-file <filename>¶

3.29 版本新增。

运行给定文件中列出的测试。

此选项告诉 CTest 运行给定文件中列出的测试。该文件每行必须包含一个确切的测试名称。与任何测试名称都不完全匹配的行将被忽略。此选项可以与 -R、-E、-L 或 -LE 等其他选项组合使用。

--exclude-from-file <filename>¶

3.29 版本新增。

排除给定文件中列出的测试。

此选项告诉 CTest 不要运行给定文件中列出的测试。该文件每行必须包含一个确切的测试名称。与任何测试名称都不完全匹配的行将被忽略。此选项可以与 -R、-E、-L 或 -LE 等其他选项组合使用。

-FA <regex>, --fixture-exclude-any <regex>¶

从自动向测试集添加任何测试中排除与 <regex> 匹配的 fixture。

如果要在执行的测试集中的测试需要特定的 fixture，则该 fixture 的 setup 和 cleanup 测试通常会自动添加到测试集中。此选项阻止为与 <regex> 匹配的 fixture 添加 setup 或 cleanup 测试。请注意，所有其他 fixture 行为都将保留，包括测试依赖项和跳过具有 fixture setup 测试失败的测试。

-FS <regex>, --fixture-exclude-setup <regex>¶: 与 -FA 相同，但仅排除匹配的 setup 测试。

-FC <regex>, --fixture-exclude-cleanup <regex>¶: 与 -FA 相同，但仅排除匹配的 cleanup 测试。

-I [Start,End,Stride,test#,test#|Test file], --tests-information¶

按编号运行特定数量的测试。

此选项使 CTest 运行从编号 Start 开始，到编号 End 结束，并以 Stride 递增的测试。 Stride 之后的任何其他数字都被视为单独的测试编号。 Start、End 或 Stride 可以为空。可选地，可以给出包含与命令行相同语法的文件。

-U, --union¶

取 -I 和 -R 的并集。

当同时指定 -R 和 -I 时，默认情况下运行测试的交集。通过指定 -U，将运行测试的并集。

--rerun-failed¶

仅运行先前失败的测试。

此选项告诉 CTest 仅执行上次运行时失败的测试。当指定此选项时，CTest 会忽略所有其他旨在修改要运行的测试列表的选项（-L、-R、-E、-LE、-I 等）。如果 CTest 运行且没有测试失败，则后续调用带有 --rerun-failed 选项的 CTest 将运行最近失败的测试集（如果有）。

--repeat <mode>:<n>¶

根据给定的 <mode> 重复运行测试，最多 <n> 次。模式为

until-fail: 要求每个测试运行 <n> 次而没有失败才能通过。这对于查找测试用例中偶尔发生的故障很有用。
until-pass: 允许每个测试最多运行 <n> 次才能通过。如果测试因任何原因失败，则重复测试。这对于容忍测试用例中偶尔发生的故障很有用。
after-timeout: 允许每个测试最多运行 <n> 次才能通过。仅当测试超时时才重复测试。这对于容忍繁忙机器上偶尔发生的超时很有用。

--repeat-until-fail <n>¶: 等效于 --repeat until-fail:<n>。

--max-width <width>¶

设置要输出的测试名称的最大宽度。

设置输出中显示的每个测试名称的最大宽度。这允许用户加宽输出以避免裁剪测试名称，这可能会非常烦人。

--interactive-debug-mode <0|1>¶

禁用 (0) 或启用 (1) 交互式调试模式。

此选项使 CTest 在交互模式或非交互模式下运行测试。在仪表板模式（Experimental、Nightly、Continuous）下，默认设置为非交互模式。在非交互模式下，设置环境变量 DASHBOARD_TEST_FROM_CTEST。

交互模式允许 Windows 错误报告 (WER) 显示调试弹出窗口并创建核心转储。要在测试中启用核心转储，请使用交互模式，并遵循有关收集用户模式转储的 Windows 文档。

在 4.0 版本中更改: Windows 错误报告 (WER) 在交互模式下启用，因此测试进程可能会显示调试弹出窗口并创建核心转储。这是通过更新到 libuv 实现的。

在 3.11 版本中更改: Windows 错误报告 (WER) 在交互模式和非交互模式下均被禁用，因此测试进程不会显示弹出窗口或创建核心转储。这是由于使用 libuv 启动测试进程。

--no-label-summary¶

禁用标签的定时总结信息。

此选项告诉 CTest 不要打印与运行测试相关的每个标签的总结信息。如果测试上没有标签，则不会打印任何额外信息。

请参阅标签和子项目总结。

--no-subproject-summary¶

禁用子项目的定时总结信息。

此选项告诉 CTest 不要打印与运行测试相关的每个子项目的总结信息。如果测试上没有子项目，则不会打印任何额外信息。

请参阅标签和子项目总结。

--test-dir <dir>¶: 在 3.20 版本中添加。

指定在其中查找测试的目录，通常是 CMake 项目构建目录。如果未指定，则使用当前目录。

--test-output-size-passed <size>¶: 在 3.4 版本中添加。

限制通过测试的输出大小为 <size> 字节。

--test-output-size-failed <size>¶: 在 3.4 版本中添加。

限制失败测试的输出大小为 <size> 字节。

--test-output-truncation <mode>¶: 在 3.24 版本中添加。

达到最大输出大小后，截断测试输出的 tail（默认）、middle 或 head。

--overwrite¶

覆盖 CTest 配置选项。

默认情况下，CTest 使用配置文件中的配置选项。此选项将覆盖配置选项。

--force-new-ctest-process¶: 已忽略。此选项曾经禁用了一个现已移除的优化，用于运行 ctest 自身的测试。

--schedule-random¶

使用随机顺序调度测试。

此选项将以随机顺序运行测试。它通常用于检测测试套件中的隐式依赖关系。

--submit-index¶: 旧 Dart2 仪表板服务器功能的遗留选项。请勿使用。

--timeout <seconds>¶

设置默认的测试超时时间。

此选项有效地为所有尚未通过 TIMEOUT 属性设置超时的测试设置超时。

--stop-time <time>¶

设置所有测试应停止运行的时间。

设置所有测试应超时的实际时间。示例：7:00:00 -0400。接受 curl 日期解析器理解的任何时间格式。如果未指定时区，则假定为本地时间。

--print-labels¶

打印所有可用的测试标签。

此选项不会运行任何测试，它只会打印与测试集关联的所有标签的列表。

--no-tests=<action>¶

将未找到测试视为错误（当 <action> 设置为 error 时）或忽略它（当 <action> 设置为 ignore 时）。

如果未找到任何测试，CTest 的默认行为是始终记录错误消息，但仅在脚本模式下返回错误代码。此选项通过在未找到任何测试时返回错误代码或忽略它来统一 CTest 的行为。

在 3.26 版本中添加。

也可以通过设置 CTEST_NO_TESTS_ACTION 环境变量来设置此选项。

查看帮助 ¶

要打印版本详细信息或从 CMake 文档中选择的页面，请使用以下选项之一

-version [<file>], --version [<file>], /V [<file>]¶: 显示程序名称/版本横幅并退出。如果给定，输出将打印到名为 <file> 的文件中。

-h, -H, --help, -help, -usage, /?¶

打印用法信息并退出。

用法描述了基本的命令行界面及其选项。

--help <keyword> [<file>]¶

打印一个 CMake 关键字的帮助。

<keyword> 可以是属性、变量、命令、策略、生成器或模块。

以人类可读的文本格式打印 <keyword> 的相关手册条目。如果给定，输出将打印到名为 <file> 的文件中。

在 3.28 版本中更改：在 CMake 3.28 之前的版本中，此选项仅支持命令名称。

--help-full [<file>]¶

打印所有帮助手册并退出。

以人类可读的文本格式打印所有手册。如果给定，输出将打印到名为 <file> 的文件中。

--help-manual <man> [<file>]¶

打印一个帮助手册并退出。

以人类可读的文本格式打印指定的手册。如果给定，输出将打印到名为 <file> 的文件中。

--help-manual-list [<file>]¶

列出可用的帮助手册并退出。

该列表包含所有可以使用 --help-manual 选项后跟手册名称来获取帮助的手册。如果给定，输出将打印到名为 <file> 的文件中。

--help-command <cmd> [<file>]¶

打印一个命令的帮助并退出。

以人类可读的文本格式打印 <cmd> 的 cmake-commands(7) 手册条目。如果给定，输出将打印到名为 <file> 的文件中。

--help-command-list [<file>]¶

列出提供帮助的命令并退出。

该列表包含所有可以使用 --help-command 选项后跟命令名称来获取帮助的命令。如果给定，输出将打印到名为 <file> 的文件中。

--help-commands [<file>]¶

打印 cmake-commands 手册并退出。

以人类可读的文本格式打印 cmake-commands(7) 手册。如果给定，输出将打印到名为 <file> 的文件中。

--help-module <mod> [<file>]¶

打印一个模块的帮助并退出。

以人类可读的文本格式打印 <mod> 的 cmake-modules(7) 手册条目。如果给定，输出将打印到名为 <file> 的文件中。

--help-module-list [<file>]¶

列出提供帮助的模块并退出。

该列表包含所有可以使用 --help-module 选项后跟模块名称来获取帮助的模块。如果给定，输出将打印到名为 <file> 的文件中。

--help-modules [<file>]¶

打印 cmake-modules 手册并退出。

以人类可读的文本格式打印 cmake-modules(7) 手册。如果给定，输出将打印到名为 <file> 的文件中。

--help-policy <cmp> [<file>]¶

打印一个策略的帮助并退出。

以人类可读的文本格式打印 <cmp> 的 cmake-policies(7) 手册条目。如果给定，输出将打印到名为 <file> 的文件中。

--help-policy-list [<file>]¶

列出提供帮助的策略并退出。

该列表包含所有可以使用 --help-policy 选项后跟策略名称来获取帮助的策略。如果给定，输出将打印到名为 <file> 的文件中。

--help-policies [<file>]¶

打印 cmake-policies 手册并退出。

以人类可读的文本格式打印 cmake-policies(7) 手册。如果给定，输出将打印到名为 <file> 的文件中。

--help-property <prop> [<file>]¶

打印一个属性的帮助并退出。

以人类可读的文本格式打印 <prop> 的 cmake-properties(7) 手册条目。如果给定，输出将打印到名为 <file> 的文件中。

--help-property-list [<file>]¶

列出提供帮助的属性并退出。

该列表包含所有可以使用 --help-property 选项后跟属性名称来获取帮助的属性。如果给定，输出将打印到名为 <file> 的文件中。

--help-properties [<file>]¶

打印 cmake-properties 手册并退出。

以人类可读的文本格式打印 cmake-properties(7) 手册。如果给定，输出将打印到名为 <file> 的文件中。

--help-variable <var> [<file>]¶

打印一个变量的帮助并退出。

以人类可读的文本格式打印 <var> 的 cmake-variables(7) 手册条目。如果给定，输出将打印到名为 <file> 的文件中。

--help-variable-list [<file>]¶

列出提供帮助的变量并退出。

该列表包含所有可以使用 --help-variable 选项后跟变量名称来获取帮助的变量。如果给定，输出将打印到名为 <file> 的文件中。

--help-variables [<file>]¶

打印 cmake-variables 手册并退出。

以人类可读的文本格式打印 cmake-variables(7) 手册。如果给定，输出将打印到名为 <file> 的文件中。

标签匹配 ¶

测试可以附加标签。可以通过标签过滤来包含或排除测试运行中的测试。每个单独的过滤器都是应用于附加到测试的标签的正则表达式。

当使用 -L 时，为了使测试包含在测试运行中，每个正则表达式必须至少匹配一个标签。使用多个 -L 选项意味着“匹配所有这些”。

-LE 选项的工作方式与 -L 类似，但排除测试而不是包含它们。如果每个正则表达式至少匹配一个标签，则排除测试。

如果测试没有附加任何标签，那么 -L 永远不会包含该测试，而 -LE 永远不会排除该测试。作为带有标签的测试示例，考虑五个测试，具有以下标签

test1 具有标签 tuesday 和 production
test2 具有标签 tuesday 和 test
test3 具有标签 wednesday 和 production
test4 具有标签 wednesday
test5 具有标签 friday 和 test

运行 ctest 和 -L tuesday -L test 将选择 test2，它同时具有这两个标签。运行 CTest 和 -L test 将选择 test2 和 test5，因为它们都具有与该正则表达式匹配的标签。

由于匹配使用正则表达式，请注意运行 CTest 和 -L es 将匹配所有五个测试。要一起选择 tuesday 和 wednesday 测试，请使用单个正则表达式来匹配其中任何一个，例如 -L "tue|wed"。

标签和子项目总结 ¶

CTest 打印与运行测试相关的每个 LABEL 和子项目的定时总结信息。标签时间总结将不包括映射到子项目的标签。

在 3.22 版本中添加：在测试执行期间动态添加的标签也会在定时总结中报告。请参阅附加标签。

当设置 PROCESSORS 测试属性时，CTest 将在标签和子项目总结中显示加权测试定时结果。时间以 秒 * 处理器 而不是仅 秒 报告。

为每个标签或子项目 j 报告的加权时间总结计算为

Weighted Time Summary for Label/Subproject j =
    sum(raw_test_time[j,i] * num_processors[j,i], i=1...num_tests[j])

for labels/subprojects j=1...total

其中

raw_test_time[j,i]：j 标签或子项目的第 i 个测试的实际运行时间
num_processors[j,i]：j 标签或子项目的第 i 个测试的 CTest PROCESSORS 属性的值
num_tests[j]：与 j 标签或子项目关联的测试数量
total：至少运行一个测试的标签或子项目总数

因此，每个标签或子项目的加权时间总结表示 CTest 为运行每个标签或子项目的测试分配的时间量，并很好地表示了每个标签或子项目的测试总开销与其他标签或子项目相比的情况。

例如，如果 SubprojectA 显示 100 秒*处理器，而 SubprojectB 显示 10 秒*处理器，则 CTest 分配给运行 SubprojectA 测试的 CPU/核心时间大约是 SubprojectB 测试的 10 倍（例如，如果要努力降低整个项目的测试套件成本，那么降低 SubprojectA 的测试套件成本可能比努力降低 SubprojectB 的测试套件成本产生更大的影响）。

构建和测试模式 ¶

CTest 提供了一个命令行签名来配置（即运行 cmake）、构建和/或执行测试

ctest --build-and-test <path-to-source> <path-to-build>
      --build-generator <generator>
      [<options>...]
      [--build-options <opts>...]
      [--test-command <command> [<args>...]]

配置和测试步骤是可选的。此命令行的参数是源目录和二进制目录。必须提供 --build-generator 选项才能使用 --build-and-test。如果指定了 --test-command，则将在构建完成后运行它。影响此模式的其他选项包括

--build-and-test¶: 切换到构建和测试模式。

--build-target¶

指定要构建的特定目标。可以多次提供此选项，并使用不同的目标，在这种情况下，每个目标将依次构建。在构建每个目标之前将执行清理，除非给出了 --build-noclean 选项。

如果未指定 --build-target，则构建 all 目标。

--build-nocmake¶

在不首先运行 cmake 的情况下运行构建。

跳过 cmake 步骤。

--build-run-dir¶

指定运行程序的目录。

编译后程序所在的目录。

--build-two-config¶: 运行两次 CMake。

--build-exe-dir¶: 指定可执行文件的目录。

--build-generator¶: 指定要使用的生成器。请参阅 cmake-generators(7) 手册。

--build-generator-platform¶: 指定生成器特定的平台。

--build-generator-toolset¶: 指定生成器特定的工具集。

--build-project¶: 指定要构建的项目名称。

--build-makeprogram¶: 指定 CMake 在配置和构建项目时要使用的显式 make 程序。仅适用于基于 Make 和 Ninja 的生成器。

--build-noclean¶: 跳过 make clean 步骤。

--build-config-sample¶: 用于确定应使用的配置的示例可执行文件。例如，Debug、Release 等。

--build-options¶: 用于配置构建的其他选项（即用于 CMake，而不是用于构建工具）。请注意，如果指定了此选项，则 --build-options 关键字及其参数必须是命令行中给出的最后一个选项，除了 --test-command 之外。

--test-command¶: 要作为 --build-and-test 选项的测试步骤运行的命令。此关键字后面的所有参数都将被假定为测试命令行的一部分，因此它必须是给出的最后一个选项。

--test-timeout¶: 以秒为单位的时间限制

仪表板客户端 ¶

CTest 可以作为 CDash 软件质量仪表盘应用程序的客户端运行。作为仪表盘客户端，CTest 执行一系列步骤来配置、构建和测试软件，然后将结果提交到 CDash 服务器。用于提交到 CDash 的命令行签名是

ctest -D <dashboard>         [-- <dashboard-options>...]
ctest -M <model> -T <action> [-- <dashboard-options>...]
ctest -S <script>            [-- <dashboard-options>...]
ctest -SP <script>           [-- <dashboard-options>...]

仪表盘客户端的选项包括

-D <dashboard>, --dashboard <dashboard>¶

执行仪表盘测试。

此选项告诉 CTest 充当 CDash 客户端并执行仪表盘测试。所有测试均为 <Mode><Test>，其中 <Mode> 可以是 Experimental (实验性), Nightly (每夜构建), 和 Continuous (持续集成), 并且 <Test> 可以是 Start (开始), Update (更新), Configure (配置), Build (构建), Test (测试), Coverage (覆盖率), 和 Submit (提交)。

如果 <dashboard> 不是已识别的 <Mode><Test> 值之一，则这将被视为变量定义（请参阅下面的 dashboard-options）。

-M <model>, --test-model <model>¶

设置仪表盘的模型。

此选项告诉 CTest 充当 CDash 客户端，其中 <model> 可以是 Experimental (实验性), Nightly (每夜构建), 和 Continuous (持续集成)。组合 -M 和 -T 类似于 -D。

-T <action>, --test-action <action>¶

设置要执行的仪表盘动作。

此选项告诉 CTest 充当 CDash 客户端并执行某些动作，例如 start (开始), build (构建), test (测试) 等。有关完整动作列表，请参阅仪表盘客户端步骤。组合 -M 和 -T 类似于 -D。

-S <script>, --script <script>¶

为配置执行仪表盘。

此选项告诉 CTest 加载配置脚本，该脚本设置许多参数，例如二进制文件和源目录。然后 CTest 将执行创建和运行仪表盘所需的操作。此选项基本上设置一个仪表盘，然后使用适当的选项运行 ctest -D。

-SP <script>, --script-new-process <script>¶

为配置执行仪表盘。

此选项执行与 -S 相同的操作，但它将在单独的进程中执行这些操作。这主要在脚本可能修改环境，并且您不希望修改后的环境影响其他 -S 脚本的情况下非常有用。

可用的 <dashboard-options> 是以下内容

-D <var>:<type>=<value>¶

为脚本模式定义变量。

在命令行中传入变量值。与 -S 结合使用，将变量值传递给仪表盘脚本。仅当 -D 后面的值与任何已知的仪表盘类型都不匹配时，才会尝试将 -D 参数解析为变量值。

--group <group>¶

指定您要将结果提交到的组

将仪表盘提交到指定的组，而不是默认组。默认情况下，仪表盘提交到 Nightly (每夜构建)、Experimental (实验性) 或 Continuous (持续集成) 组，但通过指定此选项，组可以是任意的。

这取代了已弃用的选项 --track。尽管名称已更改，但其行为保持不变。

-A <file>, --add-notes <file>¶

添加带有提交的注释文件。

此选项告诉 CTest 在提交仪表盘时包含注释文件。

--tomorrow-tag¶

Nightly (每夜构建) 或 Experimental (实验性) 从第二天的标签开始。

如果构建不会在一天内完成，这将非常有用。

--extra-submit <file>[;<file>]¶: 向仪表盘提交额外的 .xml 部分文件。请参阅 ctest_submit() 命令的 PARTS ExtraFiles 选项。

--http-header <header>¶

3.29 版本新增。

提交到仪表盘时，附加 HTTP 标头。

此选项将导致 CTest 在提交到仪表盘时附加指定的标头。此选项可以指定多次。

--http1.0¶

使用 HTTP 1.0 提交。

此选项将强制 CTest 使用 HTTP 1.0 将文件提交到仪表盘，而不是 HTTP 1.1。

--no-compress-output¶

提交时不要压缩测试输出。

此标志将关闭测试输出的自动压缩。使用此选项以保持与不支持压缩测试输出的旧版本 CDash 的兼容性。

仪表盘客户端步骤 ¶

CTest 定义了测试步骤的有序列表，其中一些或全部可以作为仪表盘客户端运行

开始 (Start): 启动新的仪表盘提交，该提交由以下步骤记录的结果组成。请参阅下面的 CTest 开始步骤部分。
更新 (Update): 从其版本控制存储库更新源树。记录旧版本和新版本以及更新的源文件列表。请参阅下面的 CTest 更新步骤部分。
配置 (Configure): 通过在构建树中运行命令来配置软件。记录配置输出日志。请参阅下面的 CTest 配置步骤部分。
构建 (Build): 通过在构建树中运行命令来构建软件。记录构建输出日志并检测警告和错误。请参阅下面的 CTest 构建步骤部分。
测试 (Test): 通过从构建树加载 CTestTestfile.cmake 并执行定义的测试来测试软件。记录每个测试的输出和结果。请参阅下面的 CTest 测试步骤部分。
覆盖率 (Coverage): 通过运行覆盖率分析工具并记录其输出来计算源代码的覆盖率。请参阅下面的 CTest 覆盖率步骤部分。
内存检查 (MemCheck): 通过内存检查工具运行软件测试套件。记录测试输出、结果和工具报告的问题。请参阅下面的 CTest 内存检查步骤部分。
提交 (Submit): 将从其他测试步骤记录的结果提交到软件质量仪表盘服务器。请参阅下面的 CTest 提交步骤部分。

仪表盘客户端模式 ¶

CTest 定义了作为仪表盘客户端运行的三种模式

每夜构建 (Nightly): 此模式旨在每天调用一次，通常在晚上。默认情况下，它启用 Start (开始), Update (更新), Configure (配置), Build (构建), Test (测试), Coverage (覆盖率), 和 Submit (提交) 步骤。即使 Update (更新) 步骤报告源树没有更改，选定的步骤也会运行。
持续集成 (Continuous): 此模式旨在在一天中重复调用。默认情况下，它启用 Start (开始), Update (更新), Configure (配置), Build (构建), Test (测试), Coverage (覆盖率), 和 Submit (提交) 步骤，但如果在 Update (更新) 步骤报告源树没有更改后退出。
实验性 (Experimental): 此模式旨在由开发人员调用以测试本地更改。默认情况下，它启用 Start (开始), Configure (配置), Build (构建), Test (测试), Coverage (覆盖率), 和 Submit (提交) 步骤。

通过 CTest 命令行使用仪表盘客户端 ¶

CTest 可以在已生成的构建树上执行测试。运行 ctest 命令，并将当前工作目录设置为构建树，并使用以下签名之一

ctest -D <mode>[<step>]
ctest -M <mode> [-T <step>]...

<mode> 必须是上述仪表盘客户端模式之一，并且每个 <step> 必须是上述仪表盘客户端步骤之一。

CTest 从构建树中名为 CTestConfiguration.ini 或 DartConfiguration.tcl 的文件（名称是历史遗留的）读取仪表盘客户端配置设置。文件的格式是

# Lines starting in '#' are comments.
# Other non-blank lines are key-value pairs.
<setting>: <value>

其中 <setting> 是设置名称，<value> 是设置值。

在 CMake 生成的构建树中，如果项目包含 CTest 模块，则此配置文件由该模块生成。该模块使用变量来获取每个设置的值，如下面的设置文档中所述。

通过 CTest 脚本使用仪表盘客户端 ¶

CTest 可以执行由 cmake-language(7) 脚本驱动的测试，该脚本创建和维护源树和构建树，以及执行测试步骤。运行 ctest 命令，并将当前工作目录设置在任何构建树之外，并使用以下签名之一

ctest -S <script>
ctest -SP <script>

<script> 文件必须调用 CTest 命令命令来显式运行测试步骤，如下面的文档所述。这些命令从其参数或脚本中设置的变量获取仪表盘客户端配置设置。

仪表盘客户端配置 ¶

仪表盘客户端步骤可以通过命名的设置进行配置，如下面的部分中所述。

CTest 开始步骤 ¶

启动新的仪表盘提交，该提交由以下步骤记录的结果组成。

在 CTest 脚本中，ctest_start() 命令运行此步骤。该命令的参数可以指定一些步骤设置。该命令首先运行 CTEST_CHECKOUT_COMMAND 变量（如果已设置）指定的命令行，以初始化源目录。

配置设置包括

BuildDirectory (构建目录)

项目构建树的完整路径。

CTest 脚本变量: CTEST_BINARY_DIRECTORY
CTest 模块变量: PROJECT_BINARY_DIR

SourceDirectory (源目录)

项目源树的完整路径。

CTest 脚本变量: CTEST_SOURCE_DIRECTORY
CTest 模块变量: PROJECT_SOURCE_DIR

CTest 更新步骤 ¶

在 CTest 脚本中，ctest_update() 命令运行此步骤。该命令的参数可以指定一些步骤设置。

配置设置，用于指定版本控制工具，包括

BZRCommand

如果源树由 Bazaar 管理，则使用的 bzr 命令行工具。

CTest 脚本变量: CTEST_BZR_COMMAND
CTest 模块变量: none

BZRUpdateOptions

更新源时，BZRCommand 的命令行选项。

CTest 脚本变量: CTEST_BZR_UPDATE_OPTIONS
CTest 模块变量: none

CVSCommand

如果源树由 CVS 管理，则使用的 cvs 命令行工具。

CTest 脚本变量: CTEST_CVS_COMMAND
CTest 模块变量: CVSCOMMAND

CVSUpdateOptions

更新源时，CVSCommand 的命令行选项。

CTest 脚本变量: CTEST_CVS_UPDATE_OPTIONS
CTest 模块变量: CVS_UPDATE_OPTIONS

GITCommand

如果源树由 Git 管理，则使用的 git 命令行工具。

CTest 脚本变量: CTEST_GIT_COMMAND
CTest 模块变量: GITCOMMAND

源树通过 git fetch 更新，然后通过 git reset --hard 重置为 FETCH_HEAD。结果与 git pull 相同，只是任何本地修改都会被覆盖。使用 GITUpdateCustom 指定不同的方法。

GITInitSubmodules

如果设置，CTest 将在更新之前更新存储库的子模块。

CTest 脚本变量: CTEST_GIT_INIT_SUBMODULES
CTest 模块变量: CTEST_GIT_INIT_SUBMODULES

GITUpdateCustom

指定要在源树（Git 工作树）中运行的自定义命令行（作为分号分隔的列表）以更新它，而不是运行 GITCommand。

CTest 脚本变量: CTEST_GIT_UPDATE_CUSTOM
CTest 模块变量: CTEST_GIT_UPDATE_CUSTOM

GITUpdateOptions

更新源时，GITCommand 的命令行选项。

CTest 脚本变量: CTEST_GIT_UPDATE_OPTIONS
CTest 模块变量: GIT_UPDATE_OPTIONS

HGCommand

如果源树由 Mercurial 管理，则使用的 hg 命令行工具。

CTest 脚本变量: CTEST_HG_COMMAND
CTest 模块变量: none

HGUpdateOptions

更新源时，HGCommand 的命令行选项。

CTest 脚本变量: CTEST_HG_UPDATE_OPTIONS
CTest 模块变量: none

P4Client

P4Command 的 -c 选项的值。

CTest 脚本变量: CTEST_P4_CLIENT
CTest 模块变量: CTEST_P4_CLIENT

P4Command

如果源树由 Perforce 管理，则使用的 p4 命令行工具。

CTest 脚本变量: CTEST_P4_COMMAND
CTest 模块变量: P4COMMAND

P4Options

所有调用 P4Command 的命令行选项。

CTest 脚本变量: CTEST_P4_OPTIONS
CTest 模块变量: CTEST_P4_OPTIONS

P4UpdateCustom

指定要在源树（Perforce 树）中运行的自定义命令行（作为分号分隔的列表）以更新它，而不是运行 P4Command。

CTest 脚本变量: none
CTest 模块变量: CTEST_P4_UPDATE_CUSTOM

P4UpdateOptions

更新源时，P4Command 的命令行选项。

CTest 脚本变量: CTEST_P4_UPDATE_OPTIONS
CTest 模块变量: CTEST_P4_UPDATE_OPTIONS

SVNCommand

如果源树由 Subversion 管理，则使用的 svn 命令行工具。

CTest 脚本变量: CTEST_SVN_COMMAND
CTest 模块变量: SVNCOMMAND

SVNOptions

所有调用 SVNCommand 的命令行选项。

CTest 脚本变量: CTEST_SVN_OPTIONS
CTest 模块变量: CTEST_SVN_OPTIONS

SVNUpdateOptions

更新源时，SVNCommand 的命令行选项。

CTest 脚本变量: CTEST_SVN_UPDATE_OPTIONS
CTest 模块变量: SVN_UPDATE_OPTIONS

UpdateCommand

指定要使用的版本控制命令行工具，而无需检测管理源树的 VCS。

CTest 脚本变量: CTEST_UPDATE_COMMAND
CTest 模块变量：当 UPDATE_TYPE 为 <vcs> 时，使用 <VCS>COMMAND，否则使用 UPDATE_COMMAND

UpdateOptions

UpdateCommand 的命令行选项。

CTest 脚本变量： CTEST_UPDATE_OPTIONS
CTest 模块变量：当 UPDATE_TYPE 为 <vcs> 时，使用 <VCS>_UPDATE_OPTIONS，否则使用 UPDATE_OPTIONS

UpdateType

指定管理源代码树的版本控制系统（如果无法自动检测到）。值可以是 bzr、cvs、git、hg、p4 或 svn。

CTest 脚本变量：无，从源代码树中检测
CTest 模块变量：如果设置了 UPDATE_TYPE，则使用它，否则使用 CTEST_UPDATE_TYPE

UpdateVersionOnly

指定您希望版本控制更新命令仅发现当前检出的版本，而不更新到不同的版本。

CTest 脚本变量： CTEST_UPDATE_VERSION_ONLY

UpdateVersionOverride

指定源代码树的当前版本。

当此变量设置为非空字符串时，CTest 将报告您指定的值，而不是使用更新命令来发现当前检出的版本。使用此变量将取代 UpdateVersionOnly。与 UpdateVersionOnly 类似，使用此变量告诉 CTest 不要将源代码树更新到不同的版本。

CTest 脚本变量： CTEST_UPDATE_VERSION_OVERRIDE

其他配置设置包括

NightlyStartTime

在 Nightly 仪表板模式下，指定“每晚开始时间”。对于集中式版本控制系统（cvs 和 svn），Update 步骤会检出截至此时的软件版本，以便多个客户端选择一个共同的版本进行测试。这在分布式版本控制系统中没有明确定义，因此该设置将被忽略。

CTest 脚本变量： CTEST_NIGHTLY_START_TIME
CTest 模块变量：如果设置了 NIGHTLY_START_TIME，则使用它，否则使用 CTEST_NIGHTLY_START_TIME

CTest 配置步骤 ¶

在 CTest 脚本中，ctest_configure() 命令运行此步骤。命令的参数可以指定一些步骤设置。

配置设置包括

ConfigureCommand

启动软件配置过程的命令行。它将在 BuildDirectory 设置指定的位置执行。

CTest 脚本变量： CTEST_CONFIGURE_COMMAND
CTest 模块变量： CMAKE_COMMAND，后跟 PROJECT_SOURCE_DIR

LabelsForSubprojects

指定以分号分隔的标签列表，这些标签将被视为子项目。当提交配置、测试或构建结果时，此映射将传递到 CDash。

CTest 脚本变量： CTEST_LABELS_FOR_SUBPROJECTS
CTest 模块变量： CTEST_LABELS_FOR_SUBPROJECTS

请参阅标签和子项目总结。

CTest 构建步骤 ¶

在 CTest 脚本中，ctest_build() 命令运行此步骤。命令的参数可以指定一些步骤设置。

配置设置包括

DefaultCTestConfigurationType

当要启动的构建系统允许在构建时选择配置（例如，Debug，Release）时，这将指定在没有为 ctest 命令提供 -C 选项时要构建的默认配置。该值将被替换到 MakeCommand 的值中，以替换其中出现的文字字符串 ${CTEST_CONFIGURATION_TYPE}。

CTest 脚本变量： CTEST_CONFIGURATION_TYPE
CTest 模块变量： DEFAULT_CTEST_CONFIGURATION_TYPE，由 CMAKE_CONFIG_TYPE 环境变量初始化

LabelsForSubprojects

指定以分号分隔的标签列表，这些标签将被视为子项目。当提交配置、测试或构建结果时，此映射将传递到 CDash。

CTest 脚本变量： CTEST_LABELS_FOR_SUBPROJECTS
CTest 模块变量： CTEST_LABELS_FOR_SUBPROJECTS

请参阅标签和子项目总结。

MakeCommand

启动软件构建过程的命令行。它将在 BuildDirectory 设置指定的位置执行。

CTest 脚本变量： CTEST_BUILD_COMMAND
CTest 模块变量： MAKECOMMAND，由 build_command() 命令初始化

UseLaunchers

对于 CMake 使用 Makefile 生成器或 Ninja 生成器生成的构建树，指定是否启用 CTEST_USE_LAUNCHERS 功能，该功能由 CTestUseLaunchers 模块（也包含在 CTest 模块中）启用。启用后，生成的构建系统会使用“launcher”包装编译器、链接器或自定义命令行的每次调用，launcher 通过环境变量和文件与 CTest 通信，以报告细粒度的构建警告和错误信息。否则，CTest 必须“抓取”构建输出日志以获取诊断信息。

CTest 脚本变量： CTEST_USE_LAUNCHERS
CTest 模块变量： CTEST_USE_LAUNCHERS

CTest 测试步骤 ¶

在 CTest 脚本中，ctest_test() 命令运行此步骤。命令的参数可以指定一些步骤设置。

配置设置包括

ResourceSpecFile

指定资源规范文件。

CTest 脚本变量： CTEST_RESOURCE_SPEC_FILE
CTest 模块变量： CTEST_RESOURCE_SPEC_FILE

有关更多信息，请参见资源分配。

LabelsForSubprojects

指定以分号分隔的标签列表，这些标签将被视为子项目。当提交配置、测试或构建结果时，此映射将传递到 CDash。

CTest 脚本变量： CTEST_LABELS_FOR_SUBPROJECTS
CTest 模块变量： CTEST_LABELS_FOR_SUBPROJECTS

请参阅标签和子项目总结。

TestLoad

在并行运行测试时（例如，使用 -j），尝试在 CPU 负载可能超过给定阈值时不要启动测试。

CTest 脚本变量： CTEST_TEST_LOAD
CTest 模块变量： CTEST_TEST_LOAD

TimeOut

每个测试的默认超时时间（如果未通过 TIMEOUT 测试属性或 --timeout 标志指定）。

CTest 脚本变量： CTEST_TEST_TIMEOUT
CTest 模块变量： DART_TESTING_TIMEOUT

要向 CDash 报告额外的测试值，请参见其他测试度量。

CTest 覆盖率步骤 ¶

在 CTest 脚本中，ctest_coverage() 命令运行此步骤。命令的参数可以指定一些步骤设置。

配置设置包括

CoverageCommand

执行软件覆盖率分析的命令行工具。它将在 BuildDirectory 设置指定的位置执行。

CTest 脚本变量： CTEST_COVERAGE_COMMAND
CTest 模块变量： COVERAGE_COMMAND

CoverageExtraFlags

指定 CoverageCommand 工具的命令行选项。

CTest 脚本变量： CTEST_COVERAGE_EXTRA_FLAGS
CTest 模块变量： COVERAGE_EXTRA_FLAGS

这些选项是传递给 CoverageCommand 的第一个参数。

CTest 内存检查步骤 ¶

在 CTest 脚本中，ctest_memcheck() 命令运行此步骤。命令的参数可以指定一些步骤设置。

配置设置包括

MemoryCheckCommand

执行动态分析的命令行工具。测试命令行将通过此工具启动。

CTest 脚本变量： CTEST_MEMORYCHECK_COMMAND
CTest 模块变量： MEMORYCHECK_COMMAND

MemoryCheckCommandOptions

指定 MemoryCheckCommand 工具的命令行选项。它们将放在测试命令行之前。

CTest 脚本变量： CTEST_MEMORYCHECK_COMMAND_OPTIONS
CTest 模块变量： MEMORYCHECK_COMMAND_OPTIONS

MemoryCheckType

指定要执行的内存检查类型。

CTest 脚本变量： CTEST_MEMORYCHECK_TYPE
CTest 模块变量： MEMORYCHECK_TYPE

MemoryCheckSanitizerOptions

指定在使用启用 sanitizers 的构建运行时，传递给 sanitizers 的选项。

CTest 脚本变量： CTEST_MEMORYCHECK_SANITIZER_OPTIONS
CTest 模块变量： MEMORYCHECK_SANITIZER_OPTIONS

MemoryCheckSuppressionFile

指定一个包含 MemoryCheckCommand 工具的抑制规则的文件。它将与适合该工具的选项一起传递。

CTest 脚本变量： CTEST_MEMORYCHECK_SUPPRESSIONS_FILE
CTest 模块变量： MEMORYCHECK_SUPPRESSIONS_FILE

其他配置设置包括

BoundsCheckerCommand

指定一个已知与 Bounds Checker 命令行兼容的 MemoryCheckCommand。

CTest 脚本变量: none
CTest 模块变量：无

PurifyCommand

指定一个已知与 Purify 命令行兼容的 MemoryCheckCommand。

CTest 脚本变量: none
CTest 模块变量： PURIFYCOMMAND

ValgrindCommand

指定一个已知与 Valgrind 命令行兼容的 MemoryCheckCommand。

CTest 脚本变量: none
CTest 模块变量： VALGRIND_COMMAND

ValgrindCommandOptions

指定 ValgrindCommand 工具的命令行选项。它们将放在测试命令行之前。

CTest 脚本变量: none
CTest 模块变量： VALGRIND_COMMAND_OPTIONS

DrMemoryCommand

指定一个已知与 DrMemory 命令行兼容的 MemoryCheckCommand。

CTest 脚本变量: none
CTest 模块变量： DRMEMORY_COMMAND

DrMemoryCommandOptions

指定 DrMemoryCommand 工具的命令行选项。它们将放在测试命令行之前。

CTest 脚本变量: none
CTest 模块变量： DRMEMORY_COMMAND_OPTIONS

CudaSanitizerCommand

指定一个已知与 cuda-memcheck 或 compute-sanitizer 命令行兼容的 MemoryCheckCommand。

CTest 脚本变量: none
CTest 模块变量： CUDA_SANITIZER_COMMAND

CudaSanitizerCommandOptions

指定 CudaSanitizerCommand 工具的命令行选项。它们将放在测试命令行之前。

CTest 脚本变量: none
CTest 模块变量： CUDA_SANITIZER_COMMAND_OPTIONS

CTest 提交步骤 ¶

在 CTest 脚本中，ctest_submit() 命令运行此步骤。命令的参数可以指定一些步骤设置。

配置设置包括

BuildName

用简短的字符串描述仪表板客户端平台。（操作系统、编译器等）

CTest 脚本变量： CTEST_BUILD_NAME
CTest 模块变量： BUILDNAME

CDashVersion

遗留选项。未使用。

CTest 脚本变量：无，从服务器检测
CTest 模块变量： CTEST_CDASH_VERSION

CTestSubmitRetryCount

指定在网络故障时重试提交的尝试次数。

CTest 脚本变量：无，使用 ctest_submit() RETRY_COUNT 选项。
CTest 模块变量： CTEST_SUBMIT_RETRY_COUNT

CTestSubmitRetryDelay

指定在网络故障时重试提交之前的延迟。

CTest 脚本变量：无，使用 ctest_submit() RETRY_DELAY 选项。
CTest 模块变量： CTEST_SUBMIT_RETRY_DELAY

CurlOptions

3.30 版本后已弃用: 请使用 TLSVerify 代替。

指定以分号分隔的选项列表，以控制 CTest 内部用于连接到服务器的 Curl 库。

CTest 脚本变量： CTEST_CURL_OPTIONS
CTest 模块变量： CTEST_CURL_OPTIONS

可能的选项是

CURLOPT_SSL_VERIFYPEER_OFF: 禁用 CURLOPT_SSL_VERIFYPEER curl 选项。
CURLOPT_SSL_VERIFYHOST_OFF: 禁用 CURLOPT_SSL_VERIFYHOST curl 选项。

DropLocation