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，则通常会自动将该 fixture 的 setup 和 cleanup 测试添加到测试集中。此选项阻止为与 <regex> 匹配的 fixture 添加 setup 或 cleanup 测试。请注意，所有其他 fixture 行为都将保留，包括测试依赖关系和跳过具有 fixture setup 测试失败的测试。

EXCLUDE_FIXTURE_SETUP <regex>

在 3.7 版本中添加。

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

EXCLUDE_FIXTURE_CLEANUP <regex>

在 3.7 版本中添加。

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

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 的额外度量。

当作为仪表盘客户端运行时，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¶

其他测试度量¶

图像度量¶

附加文件¶

自定义详细信息¶

其他标签¶

目录

上一个主题

下一个主题

本页