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 中添加。

如果要执行的测试集中某个测试需要特定的固定装置，则该固定装置的设置和清理测试通常会自动添加到测试集。此选项阻止为匹配 <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 变量，将检查该变量，然后再检查 --test-load 命令行参数 ctest(1)。另请参阅 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。

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

查看 CDash 测试度量文档了解有关 CDash 识别的测试度量类型的信息。

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

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¶

其他测试度量¶

图像度量¶

附加文件¶

自定义详情¶

其他标签¶

目录

前一主题

下一主题

此页面