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变量,然后检查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_SIZECTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZECTEST_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_FILESATTACHED_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测试属性。