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> 可以是以下值之一。

人工
人类友好的输出。此输出不保证稳定。这是默认设置。

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> 匹配的 fixtures。

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

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

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

-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¶

使用随机顺序调度测试。

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

--schedule-random-seed¶

在 4.1 版本中新增。

覆盖随机顺序种子

此选项用于通过 --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

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

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

标签和子项目摘要 ¶

CTest 打印与所运行测试关联的每个 LABEL 和子项目的时间摘要信息。标签时间摘要将不包括映射到子项目的标签。

在 3.22 版中新增: 测试执行期间动态添加的标签也将在时间摘要中报告。请参阅附加标签。

当设置了 PROCESSORS 测试属性时，CTest 将在标签和子项目摘要中显示加权测试时间结果。时间报告为 sec * proc 而不仅仅是 sec。

为每个标签或子项目 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 sec*proc，而 SubprojectB 显示 10 sec*proc，则 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> 值之一，则将其视为变量定义（请参阅下面的仪表板选项）。

-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 定义了一个有序的测试步骤列表，其中部分或全部步骤可以作为仪表板客户端运行

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

仪表板客户端模式 ¶

CTest 定义了三种作为仪表板客户端的操作模式

每晚: 此模式旨在每天调用一次，通常在晚上。默认情况下，它启用 Start、Update、Configure、Build、Test、Coverage 和 Submit 步骤。即使 Update 步骤报告源代码树没有变化，也会运行选定的步骤。
持续: 此模式旨在全天重复调用。默认情况下，它启用 Start、Update、Configure、Build、Test、Coverage 和 Submit 步骤，但如果 Update 步骤报告源代码树没有变化，则在 Update 步骤后退出。
实验: 此模式旨在由开发人员调用以测试本地更改。默认情况下，它启用 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 模块变量：无

BZRUpdateOptions

更新源时传递给 BZRCommand 的命令行选项。

CTest 脚本变量：CTEST_BZR_UPDATE_OPTIONS
CTest 模块变量：无

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 模块变量：无

HGUpdateOptions

更新源时传递给 HGCommand 的命令行选项。

CTest 脚本变量：CTEST_HG_UPDATE_OPTIONS
CTest 模块变量：无

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 脚本变量：无
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 则为 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 则为 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

对于使用 Makefile 生成器之一或 Ninja 生成器生成的构建树，指定是否通过 CTestUseLaunchers 模块（也包含在 CTest 模块中）启用 CTEST_USE_LAUNCHERS 功能。启用后，生成的构建系统会将编译器、链接器或自定义命令行的每次调用包装在一个“启动器”中，该启动器通过环境变量和文件与 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

指定在启用 sanitize 的构建中运行时传递给 sanitize 工具的选项。

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 脚本变量：无
CTest 模块变量：无

PurifyCommand

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

CTest 脚本变量：无
CTest 模块变量：PURIFYCOMMAND

ValgrindCommand

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

CTest 脚本变量：无
CTest 模块变量：VALGRIND_COMMAND

ValgrindCommandOptions

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

CTest 脚本变量：无
CTest 模块变量：VALGRIND_COMMAND_OPTIONS

DrMemoryCommand

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

CTest 脚本变量：无
CTest 模块变量：DRMEMORY_COMMAND

DrMemoryCommandOptions

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

CTest 脚本变量：无
CTest 模块变量：DRMEMORY_COMMAND_OPTIONS

CudaSanitizerCommand

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

CTest 脚本变量：无
CTest 模块变量：CUDA_SANITIZER_COMMAND

CudaSanitizerCommandOptions

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

CTest 脚本变量：无
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