ctest(1)¶

概要 ¶

Run Tests
 ctest [<options>]

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 生成的构建树可以在同一棵树中有多个构建配置。此选项可用于指定应测试哪一个。示例配置是“调试”和“发布”。

--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 <jobs>, --parallel <jobs>¶

使用给定数量的作业并行运行测试。

此选项告诉 CTest 使用给定数量的作业并行运行测试。此选项也可以通过设置 CTEST_PARALLEL_LEVEL 环境变量来设置。

此选项可与 PROCESSORS 测试属性一起使用。

请参阅“标签和子项目摘要”。

--resource-spec-file <file>¶

使用在 <file> 中指定的:ref:资源规范文件 <ctest-resource-specification-file> 启用资源分配 <ctest-resource-allocation>` 运行 CTest。

当 ctest 作为 Dashboard Client 运行时，这会设置 CTest Test Step 的 ResourceSpecFile 选项。

--test-load <level>¶

在并行运行测试时（例如使用 -j），尽量不要在可能导致 CPU 负载超过给定阈值时开始测试。

当 ctest 作为 Dashboard Client 运行时，这会设置 CTest 测试步骤的 TestLoad 选项。

-Q, --quiet¶

让 CTest 安静下来。

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

-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 时，测试才会被排除关系）。请参阅“标签匹配”。

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

从自动将任何测试添加到测试集中排除匹配``<regex>`` 的装置。

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

-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, :option: -E <ctest -E>、 -LE、 -I 等）。如果 CTest 运行并且没有测试失败，随后使用“--rerun-failed”选项调用 CTest 将运行最近失败的一组测试（如果有）。

--repeat <mode>:<n>¶

根据给定的``<mode>`` 重复运行测试最多``<n>`` 次。这些模式是：

直到失败: 要求每个测试运行 <n> 次而不失败才能通过。这对于查找测试用例中的零星故障很有用。
直到通过: 允许每个测试运行最多 <n> 次才能通过。如果由于任何原因失败，则重复测试。这对于容忍测试用例中的零星故障很有用。
超时后: 允许每个测试运行最多 <n> 次才能通过。仅在超时时重复测试。这对于容忍繁忙机器上测试用例中的零星超时很有用。

--repeat-until-fail <n>¶: 相当于:option:--repeat until-fail:<n> <ctest --repeat>。

--max-width <width>¶

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

设置每个测试名称的最大宽度以显示在输出中。这允许用户加宽输出以避免截断非常烦人的测试名称。

--interactive-debug-mode [0|1]¶

将交互模式设置为“0”或“1”。

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

在 CMake 3.11 之前，Windows 上的交互模式允许出现系统调试弹出窗口。现在，由于 CTest 使用 libuv 启动测试进程，所有系统调试弹出窗口总是被阻止。

--no-label-summary¶

禁用标签的时序摘要信息。

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

请参阅“标签和子项目摘要”。

--no-subproject-summary¶

禁用子项目的时序摘要信息。

此选项告诉 CTest 不要打印与测试运行关联的每个子项目的摘要信息。如果测试中没有子项目，则不会打印任何额外内容。

请参阅“标签和子项目摘要”。

--test-dir <dir>¶: 指定要在其中查找测试的目录。

--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 实例作为新进程运行。

默认情况下，CTest 将在同一进程中运行子 CTest 实例。如果不需要此行为，此参数将为子 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>]¶: 显示程序名称/版本横幅并退出。 |文件|

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

打印使用信息并退出。

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

--help-full [<file>]¶

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

所有手册均以人类可读的文本格式印刷。 |文件|

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

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

指定的手册以人类可读的文本格式打印。 |文件|

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

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

该列表包含所有可以通过使用“--help-manual”选项后跟手册名称来获取帮助的手册。 |文件|

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

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

<cmd> 的 cmake-commands(7) 手册条目以人类可读的文本格式打印。 |文件|

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

列出具有可用帮助的命令并退出。

该列表包含所有可以通过使用“--help-command”选项后跟命令名称来获取帮助的命令。 |文件|

--help-commands [<file>]¶

打印 cmake-commands 手册并退出。

cmake-commands(7) 手册以人类可读的文本格式打印。 |文件|

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

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

<mod> 的 cmake-modules(7) 手册条目以人类可读的文本格式打印。 |文件|

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

列出具有可用帮助的模块并退出。

该列表包含所有可以通过使用“--help-module”选项后跟模块名称来获取帮助的模块。 |文件|

--help-modules [<file>]¶

打印 cmake-modules 手册并退出。

cmake-modules(7) 手册以人类可读的文本格式打印。 |文件|

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

打印一项政策的帮助并退出。

<cmp> 的 cmake-policies(7) 手册条目以人类可读的文本格式打印。 |文件|

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

列出具有可用帮助的策略并退出。

该列表包含所有可以通过使用“--help-policy”选项后跟策略名称来获取帮助的策略。 |文件|

--help-policies [<file>]¶

打印 cmake-policies 手册并退出。

cmake-policies(7) 手册以人类可读的文本格式打印。 |文件|

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

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

<prop> 的 cmake-properties(7) 手册条目以人类可读的文本格式打印。 |文件|

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

列出具有可用帮助的属性并退出。

该列表包含所有可以通过使用“--help-property”选项后跟属性名称来获取帮助的属性。 |文件|

--help-properties [<file>]¶

打印 cmake-properties 手册并退出。

cmake-properties(7) 手册以人类可读的文本格式打印。 |文件|

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

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

<var> 的 cmake-variables(7) 手册条目以人类可读的文本格式打印。 |文件|

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

列出可用帮助的变量并退出。

该列表包含所有变量，可以通过使用“--help-variable”选项后跟变量名来获得帮助。 |文件|

--help-variables [<file>]¶

打印 cmake-variables 手册并退出。

cmake-variables(7) 手册以人类可读的文本格式打印。 |文件|

标签匹配 ¶

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

当使用 -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 打印与测试运行相关的每个“标签”和子项目的时间摘要信息。标签时间摘要将不包括映射到子项目的标签。

在 3.22 版本加入: 在测试执行期间动态添加的标签也会在时序摘要中报告。请参阅:ref:附加标签。

当设置 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 分配大约 10 倍的 CPU/核心时间来运行测试``SubprojectA`` 而不是 SubprojectB``（例如，如果要花费精力来降低整个项目的测试套件成本，那么降低 ``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¶: 用于确定应使用的配置的示例可执行文件。例如``调试``，``发布``等。

--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> 值之一，这将被视为变量定义（参见 :ref:`dashboard-options <Dashboard Options>`下文）。

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

设置仪表板的模型。

此选项告诉 CTest 充当 CDash 客户端，其中 <model> 可以是 Experimental、Nightly 和 Continuous。结合 -M 和 -T 类似于 -D。

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

设置要执行的仪表板操作。

此选项告诉 CTest 充当 CDash 客户端并执行一些操作，例如“开始”、“构建”、“测试”等。有关操作的完整列表，请参阅“仪表板客户端步骤”。组合 -M 和``-T`` 类似于 -D。

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

执行配置的仪表板。

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

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

执行配置的仪表板。

此选项执行与 -S 相同的操作，但它将在单独的进程中执行它们。这主要用于脚本可能修改环境并且您不希望修改后的环境影响其他脚本的情况:option:-S <ctest -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>]¶

将额外的文件提交到仪表板。

此选项会将额外的文件提交到仪表板。

--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 MemCheck Step”部分。
提交: 将其他测试步骤记录的结果提交到软件质量仪表板服务器。请参阅下面的“CTest 提交步骤”部分。

仪表板客户端模式 ¶

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

每晚: 此模式旨在每天调用一次，通常是在晚上。它默认启用“开始”、“更新”、“配置”、“构建”、“测试”、“覆盖”和“提交”步骤。即使 Update 步骤报告源代码树没有变化，选定的步骤也会运行。
连续: 此模式旨在全天重复调用。它默认启用“开始”、“更新”、“配置”、“构建”、“测试”、“覆盖”和“提交”步骤，但是如果报告没有对源代码树进行任何更改，则在“更新”步骤之后退出。
实验性的: 此模式旨在由开发人员调用以测试本地更改。它默认启用“开始”、“配置”、“构建”、“测试”、“覆盖”和“提交”步骤。

通过 CTest 命令行的仪表板客户端 ¶

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

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

<mode> 必须是上述 Dashboard Client Modes 之一，每个 <step> 必须是上述 Dashboard Client Steps 之一。

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> 文件必须调用:ref:CTest 命令命令来显式运行测试步骤，如下所述。这些命令从它们的参数或脚本中设置的变量中获取“仪表板客户端配置”设置。

仪表板客户端配置 ¶

Dashboard Client Steps 可以通过以下部分中记录的命名设置进行配置。

CTest 开始步骤 ¶

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

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

配置设置包括：

构建目录

项目构建树的完整路径。

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

源目录

项目源代码树的完整路径。

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

CVS 命令

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

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

CVSUpdateOptions

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

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

GIT 命令

如果源代码树由 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

SVN 命令

如果源代码树由 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

更新命令

指定在不检测管理源代码树的 VCS 的情况下使用的版本控制命令行工具。

CTest 脚本变量： CTEST_UPDATE_COMMAND
CTest 模块变量：<VCS>COMMAND 当``UPDATE_TYPE`` 是``<vcs>`` 时，UPDATE_COMMAND

更新选项

UpdateCommand 的命令行选项。

CTest 脚本变量： CTEST_UPDATE_OPTIONS
CTest 模块变量：<VCS>_UPDATE_OPTIONS 当 UPDATE_TYPE 是 <vcs> 时，UPDATE_OPTIONS

更新类型

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

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

仅更新版本

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

CTest 脚本变量： CTEST_UPDATE_VERSION_ONLY

更新版本覆盖

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

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

CTest 脚本变量： CTEST_UPDATE_VERSION_OVERRIDE

其他配置设置包括：

每晚开始时间

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

CTest 脚本变量： CTEST_NIGHTLY_START_TIME
CTest 模块变量：NIGHTLY_START_TIME 如果设置，否则为 CTEST_NIGHTLY_START_TIME

CTest 配置步骤 ¶

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

配置设置包括：

配置命令

启动软件配置过程的命令行。它将在 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 Script 中， ctest_build() 命令运行此步骤。命令的参数可以指定一些步骤设置。

配置设置包括：

DefaultCTestConfigurationType

当要启动的构建系统允许构建时选择配置（例如``Debug``，Release），这指定了在没有时构建的默认配置:option:-C <ctest -C> 选项被赋予 ctest 命令。该值将被替换为“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() 命令初始化

使用启动器

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

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

CTest测试步骤 ¶

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

配置设置包括：

ResourceSpecFile

指定资源规范文件。

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

有关详细信息，请参阅:ref:ctest-resource-allocation。

LabelsForSubprojects

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

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

请参阅“标签和子项目摘要”。

测试负载

在并行运行测试时（例如使用 -j），尽量不要在可能导致 CPU 负载超过给定阈值时开始测试。

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

超时

如果 TIMEOUT 测试属性未指定，则每个测试的默认超时。

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

要向 CDash 报告额外的测试值，请参阅额外的测试测量。

CTest 覆盖步骤 ¶

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

配置设置包括：

CoverageCommand

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

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

CoverageExtraFlags

为“CoverageCommand”工具指定命令行选项。

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

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

CTest MemCheck 步骤 ¶

在 CTest Script 中， 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

使用启用清理的构建运行时，指定清理程序的选项。

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

MemoryCheckSuppressionFile

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

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

其他配置设置包括：

BoundsCheckerCommand

指定已知与边界检查器命令行兼容的“MemoryCheckCommand”。

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

净化命令

指定已知与 Purify 命令行兼容的“MemoryCheckCommand”。

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

Valgrind 命令

指定已知与 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 Script 中， 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

指定以分号分隔的选项列表，以控制 CTest 在内部用于连接到服务器的 Curl 库。可能的选项是“CURLOPT_SSL_VERIFYPEER_OFF”和“CURLOPT_SSL_VERIFYHOST_OFF”。

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

DropLocation