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_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
测试属性。