ctest_test¶

执行 CTest 测试步骤，作为仪表板客户端。

ctest_test([BUILD <build-dir>] [APPEND]
           [START <start-number>]
           [END <end-number>]
           [STRIDE <stride-number>]
           [EXCLUDE <exclude-regex>]
           [INCLUDE <include-regex>]
           [EXCLUDE_LABEL <label-exclude-regex>]
           [INCLUDE_LABEL <label-include-regex>]
           [EXCLUDE_FROM_FILE <filename>]
           [INCLUDE_FROM_FILE <filename>]
           [EXCLUDE_FIXTURE <regex>]
           [EXCLUDE_FIXTURE_SETUP <regex>]
           [EXCLUDE_FIXTURE_CLEANUP <regex>]
           [PARALLEL_LEVEL [<level>]]
           [RESOURCE_SPEC_FILE <file>]
           [TEST_LOAD <threshold>]
           [SCHEDULE_RANDOM <ON|OFF>]
           [STOP_ON_FAILURE]
           [STOP_TIME <time-of-day>]
           [RETURN_VALUE <result-var>]
           [CAPTURE_CMAKE_ERROR <result-var>]
           [REPEAT <mode>:<n>]
           [OUTPUT_JUNIT <file>]
           [QUIET]
           )

在项目构建树中运行测试，并将结果存储在 Test.xml 中，以便使用 ctest_submit() 命令提交。

选项包括

BUILD <build-dir>

指定顶级构建目录。如果未给出，则使用 CTEST_BINARY_DIRECTORY 变量。

APPEND

将 Test.xml 标记为追加到自上次 ctest_start() 调用以来已提交到仪表板服务器的结果中。追加语义由所使用的仪表板服务器定义。这并不会导致结果被追加到由该命令之前调用所产生的 .xml 文件中。

START <start-number>

指定测试编号范围的起始值。

END <end-number>

指定测试编号范围的结束值。

STRIDE <stride-number>

指定跨越测试编号范围的步长。

EXCLUDE <exclude-regex>

指定匹配要排除的测试名称的正则表达式。

INCLUDE <include-regex>

指定匹配要包含的测试名称的正则表达式。不匹配此表达式的测试将被排除。

EXCLUDE_LABEL <label-exclude-regex>

指定匹配要排除的测试标签的正则表达式。

INCLUDE_LABEL <label-include-regex>

指定匹配要包含的测试标签的正则表达式。不匹配此表达式的测试将被排除。

EXCLUDE_FROM_FILE <filename>

在版本 3.29 中添加。

不要运行给定文件中精确列出的测试。

INCLUDE_FROM_FILE <filename>

在版本 3.29 中添加。

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

EXCLUDE_FIXTURE <regex>

3.7 版本中新增。

如果待执行测试集中的某个测试需要特定的测试夹具（fixture），该夹具的设置（setup）和清理（cleanup）测试通常会自动添加到测试集中。此选项可防止为匹配 <regex> 的夹具添加设置或清理测试。请注意，所有其他夹具行为均会被保留，包括测试依赖关系以及跳过那些具有失败夹具设置测试的测试。

EXCLUDE_FIXTURE_SETUP <regex>

3.7 版本中新增。

与 EXCLUDE_FIXTURE 相同，但仅排除匹配的设置测试。

EXCLUDE_FIXTURE_CLEANUP <regex>

3.7 版本中新增。

与 EXCLUDE_FIXTURE 相同，但仅排除匹配的清理测试。

PARALLEL_LEVEL [<level>]

并行运行测试，并限制并行级别。

3.29 版本新增：可以省略 <level> 或将其设为 0，分别表示让 ctest 使用默认的并行级别或不限制并行度，具体如 ctest --parallel 选项所述。

RESOURCE_SPEC_FILE <file>

3.16 版新增。

指定一个资源规范文件。有关更多信息，请参阅资源分配。

TEST_LOAD <threshold>

3.4 版本新增。

在并行运行测试时，尽量避免在可能导致 CPU 负载超过给定阈值时启动测试。如果未指定，将检查 CTEST_TEST_LOAD 变量，然后检查 ctest(1) 的 --test-load 命令行参数。另请参阅 CTest 测试步骤中的 TestLoad 设置。

REPEAT <mode>:<n>

在 3.17 版本中添加。

基于给定的 <mode> 重复运行测试，最多 <n> 次。模式包括：

UNTIL_FAIL: 要求每个测试运行 <n> 次且均不失败才算通过。这对于发现测试用例中的偶发性失败非常有用。
UNTIL_PASS: 允许每个测试运行最多 <n> 次以使其通过。如果测试因任何原因失败则会重复运行。这对于容忍测试用例中的偶发性失败非常有用。
AFTER_TIMEOUT: 允许每个测试运行最多 <n> 次以使其通过。仅在测试超时时重复运行。这对于在高负载机器上容忍测试用例的偶发性超时非常有用。

SCHEDULE_RANDOM <ON|OFF>

以随机顺序启动测试。这对于检测隐含的测试依赖关系可能很有用。

STOP_ON_FAILURE

在 3.18 版本中新增。

一旦有测试失败，即停止执行测试。

STOP_TIME <time-of-day>

指定所有测试停止运行的具体时间。

RETURN_VALUE <result-var>

如果所有测试均通过，则在 <result-var> 变量中存储 0。如果出现任何问题，则存储非零值。

CAPTURE_CMAKE_ERROR <result-var>

3.7 版本中新增。

如果运行命令时有任何错误，则在 <result-var> 变量中存储 -1，并防止 ctest 在发生错误时返回非零值。

OUTPUT_JUNIT <file>

3.21 版本新增。

以 JUnit XML 格式将测试结果写入 <file>。如果 <file> 是相对路径，它将被放置在构建目录中。如果 <file> 已存在，则会被覆盖。请注意，生成的 JUnit XML 文件不会上传到 CDash，因为它与 CTest 的 Test.xml 文件内容重复。

QUIET

3.3 版本中新增。

抑制任何本应打印到控制台的 CTest 特有的非错误消息。底层测试命令的输出不受影响。详细说明测试通过百分比的摘要信息也不受 QUIET 选项的影响。

另请参阅 CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE、CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE 和 CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION 变量，以及它们对应的 ctest(1) 命令行选项 --test-output-size-passed、--test-output-size-failed 和 --test-output-truncation。

附加测试度量¶

CTest 可以解析您的测试输出，以获取向 CDash 报告的额外度量。

当作为仪表板客户端运行时，CTest 会将这些自定义度量包含在上传到 CDash 的 Test.xml 文件中。

查看 CDash 测试度量文档，了解更多关于 CDash 可识别的测试度量类型的信息。

3.22 版本新增：CTest 可以从名为 <CTestMeasurement> 或 <CTestMeasurementFile> 的标签中解析自定义度量。旧名称 <DartMeasurement> 和 <DartMeasurementFile> 仍然受支持。

以下示例演示了如何输出各种自定义测试度量。

std::cout <<
  "<CTestMeasurement type=\"numeric/double\" name=\"score\">28.3</CTestMeasurement>"
  << std::endl;

std::cout <<
  "<CTestMeasurement type=\"text/string\" name=\"color\">red</CTestMeasurement>"
  << std::endl;

std::cout <<
  "<CTestMeasurement type=\"text/link\" name=\"CMake URL\">https://cmake.com.cn</CTestMeasurement>"
  << std::endl;

std::cout <<
  "<CTestMeasurement type=\"text/preformatted\" name=\"Console Output\">" <<
  "line 1.\n" <<
  "  \033[31;1m line 2. Bold red, and indented!\033[0;0ml\n" <<
  "line 3. Not bold or indented...\n" <<
  "</CTestMeasurement>" << std::endl;

图像度量¶

以下示例演示了如何将测试图像上传到 CDash。

std::cout <<
  "<CTestMeasurementFile type=\"image/jpg\" name=\"TestImage\">" <<
  "/dir/to/test_img.jpg</CTestMeasurementFile>" << std::endl;

std::cout <<
  "<CTestMeasurementFile type=\"image/gif\" name=\"ValidImage\">" <<
  "/dir/to/valid_img.gif</CTestMeasurementFile>" << std::endl;

std::cout <<
  "<CTestMeasurementFile type=\"image/png\" name=\"AlgoResult\">" <<
  "/dir/to/img.png</CTestMeasurementFile>"
  << std::endl;

如果图像提供了以下两个或多个名称，它们将在 CDash 的交互式比较模式中一起显示。

TestImage
ValidImage
BaselineImage
DifferenceImage2

按照惯例，TestImage 是您的测试生成的图像，而 ValidImage（或 BaselineImage）是用于确定测试通过或失败的比较基准。

如果使用了其他图像名称，它将作为静态图像显示在 CDash 上，与交互式比较 UI 分开。

附加文件¶

3.21 版本新增。

以下示例演示了如何将非图像文件上传到 CDash。

std::cout <<
  "<CTestMeasurementFile type=\"file\" name=\"TestInputData1\">" <<
  "/dir/to/data1.csv</CTestMeasurementFile>\n"                   <<
  "<CTestMeasurementFile type=\"file\" name=\"TestInputData2\">" <<
  "/dir/to/data2.csv</CTestMeasurementFile>"                     << std::endl;

如果在配置时已知要上传的文件名，则可以使用 ATTACHED_FILES 或 ATTACHED_FILES_ON_FAIL 测试属性。

自定义详情¶

3.21 版本新增。

以下示例演示了如何为 CDash 上显示的 Test Details 字段指定自定义值。

std::cout <<
  "<CTestDetails>My Custom Details Value</CTestDetails>" << std::endl;

附加标签¶

3.22 版本新增。

以下示例演示了如何在运行时为测试添加额外标签。

std::cout <<
  "<CTestLabel>Custom Label 1</CTestLabel>\n" <<
  "<CTestLabel>Custom Label 2</CTestLabel>"   << std::endl;

对于可以在配置时确定的标签，请使用 LABELS 测试属性。

ctest_test¶

附加测试度量¶

图像度量¶

附加文件¶

自定义详情¶

附加标签¶

目录

上一主题

下一主题

本页