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 的设置和清理测试添加到测试集中。此选项可防止添加与 <regex> 匹配的 fixture 的设置或清理测试。请注意，所有其他 fixture 行为都保留，包括测试依赖关系和跳过 fixture 设置测试失败的测试。

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>

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

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¶

附加测试测量¶

图像测量¶

附加文件¶

自定义详细信息¶

附加标签¶

目录

上一主题

下一主题

本页