lit - LLVM 集成测试器¶
语法¶
lit [选项] [测试]
描述¶
lit 是一款可移植的工具，用于执行 LLVM 和 Clang 风格的测试套件，汇总其结果并指示失败情况。lit 旨在成为一个轻量级的测试工具，并尽可能提供简单的用户界面。
应使用命令行上指定的至少一个测试来运行lit。测试可以是单个测试文件，也可以是用于搜索测试的目录（请参阅测试发现）。
每个指定的测试都将（可能并行）执行，并且一旦所有测试都已运行，lit 将打印有关通过或失败的测试数量的摘要信息（请参阅测试状态结果）。如果任何测试失败，lit 程序将以非零退出代码退出。
默认情况下，lit 将使用简洁的进度显示，并且仅打印测试失败的摘要信息。有关控制lit 进度显示和输出的选项，请参阅输出选项。
lit 还包含许多用于控制测试执行方式的选项（特定功能可能取决于特定的测试格式）。有关更多信息，请参阅执行选项。
最后，lit 还支持其他选项，仅运行命令行上指定的部分选项，有关更多信息，请参阅选择选项。
lit 在解析命令行中的选项后，会从环境变量LIT_OPTS中解析选项。LIT_OPTS主要用于补充或覆盖项目构建系统定义的check目标提供给lit的命令行选项。
lit 还可以从响应文件中读取选项，这些响应文件作为使用@path/to/file.rsp语法输入的输入指定。从文件中读取的参数必须每行一个，并且被视为与命令行上引用参数的原始文件位于相同位置。响应文件可以引用其他响应文件。
有兴趣了解lit 架构或设计lit 测试实现的用户应该参阅LIT 基础设施。
常规选项¶
- -h, --help¶
显示lit 帮助消息。
- -j N, --workers=N¶
并行运行
N个测试。默认情况下，会自动选择此值以匹配检测到的可用 CPU 数量。
- --config-prefix=NAME¶
在搜索测试套件时，搜索
NAME.cfg和NAME.site.cfg，而不是lit.cfg和lit.site.cfg。
- -D NAME[=VALUE], --param NAME[=VALUE]¶
添加一个用户定义的参数
NAME，并使用给定的VALUE（如果未给出，则使用空字符串）。这些参数的含义和用途取决于测试套件。
输出选项¶
- -q, --quiet¶
抑制除测试失败之外的所有输出。
- -s, --succinct¶
显示更少的输出，例如，不显示通过测试的信息。还显示进度条，除非指定了
--no-progress-bar。
- -v, --verbose¶
显示有关测试失败的更多信息，例如整个测试输出，而不仅仅是测试结果。
在执行每个命令之前都会打印该命令。这对于调试测试失败很有价值，因为最后一个打印的命令是失败的命令。此外，lit 在输出中的每个命令管道之前插入
'RUN: at line N'，以帮助您找到失败命令的源代码行。
- -vv, --echo-all-commands¶
-v 的已弃用别名。
- -a, --show-all¶
启用 -v，但用于所有测试，而不仅仅是失败的测试。
- --no-progress-bar¶
不要使用基于 curses 的进度条。
- --show-unsupported¶
显示不受支持的测试的名称。
- --show-xfail¶
显示预期失败的测试的名称。
执行选项¶
- --path=PATH¶
指定在测试中搜索可执行文件时要使用的其他
PATH。
- --vg¶
在 valgrind（使用 memcheck 工具）下运行单个测试。使用 valgrind 的
--error-exitcode参数，以便 valgrind 失败会导致程序以非零状态退出。启用此选项后，lit 还将自动提供一个“
valgrind”功能，该功能可用于有条件地禁用（或预期失败）某些测试。
- --skip-test-time-recording¶
禁用跟踪单个测试执行所花费的挂钟时间。
- --time-tests¶
跟踪单个测试执行所花费的挂钟时间，并在摘要输出中包含结果。这对于确定测试套件中哪些测试执行时间最长很有用。
- --ignore-fail¶
即使某些测试失败，也以状态零退出。
选择选项¶
默认情况下，lit 将首先运行失败的测试，然后按执行时间降序运行测试以优化并发性。可以使用--order选项更改执行顺序。
时间数据存储在test_exec_root目录下的名为.lit_test_times.txt的文件中。如果此文件不存在，则lit会检查test_source_root目录中是否存在该文件，以可选地加速干净构建。
- --per-test-coverage¶
发出必要的测试覆盖率数据，每个测试用例分开（涉及为每个RUN设置LLVM_PROFILE_FILE的唯一值）。覆盖率数据文件将输出到config.test_exec_root指定的目录中。
- --max-failures N¶
在发生指定数量
N的失败后停止执行。在执行前应在命令行上传递一个整数参数。
- --max-tests=N¶
最多运行
N个测试，然后终止。
- --num-shards=M¶
将选定的测试集分成
M个大小相等子集或“分片”，并仅运行其中一个。必须与--run-shard=N选项一起使用，该选项选择要运行的分片。环境变量LIT_NUM_SHARDS也可以代替此选项使用。这两个选项提供了一种粗略的机制来划分大型测试套件，以便在单独的机器上（例如在大型测试场中）并行执行。
- --order={lexical,random,smart}¶
定义测试运行的顺序。支持的值为
lexical - 测试将根据测试文件路径按字典顺序运行。当需要可预测的测试顺序时，此选项很有用。
random - 测试将以随机顺序运行。
smart - 之前失败的测试将首先运行，然后是其余测试，所有测试都按执行时间从高到低排序。这是默认设置，因为它优化了并发性。
- --run-shard=N¶
选择要运行的分片，假设提供了
--num-shards=M选项。这两个选项必须一起使用，并且N的值必须在1..M范围内。环境变量LIT_RUN_SHARD也可以代替此选项使用。
- --timeout=N¶
每个单独测试最多花费
N秒（大约）运行。0表示没有时间限制，0是默认值。请注意，这不是--max-time的别名；两者是不同类型的最大值。
- --filter=REGEXP¶
仅运行名称与
REGEXP中指定的正则表达式匹配的测试。环境变量LIT_FILTER也可以代替此选项使用，这在间接调用lit的环境中尤其有用。
- --filter-out=REGEXP¶
过滤掉名称与
REGEXP中指定的正则表达式匹配的测试。环境变量LIT_FILTER_OUT也可以代替此选项使用，这在间接调用lit的环境中尤其有用。
- --xfail=LIST¶
将名称位于以分号分隔的列表
LIST中的测试视为XFAIL。当不想修改测试套件时，这很有用。环境变量LIT_XFAIL也可以代替此选项使用，这在间接调用lit的环境中尤其有用。测试名称可以指定为相对于测试套件目录的文件名。例如
LIT_XFAIL="affinity/kmp-hw-subset.c;offloading/memory_manager.cpp"
在这种情况下，以下所有测试都将被视为
XFAILlibomp :: affinity/kmp-hw-subset.c libomptarget :: nvptx64-nvidia-cuda :: offloading/memory_manager.cpp libomptarget :: x86_64-pc-linux-gnu :: offloading/memory_manager.cpp
或者，测试名称可以指定为LIT输出中报告的完整测试名称。例如，我们可以调整前面的示例，不要将
offloading/memory_manager.cpp的nvptx64-nvidia-cuda版本视为XFAILLIT_XFAIL="affinity/kmp-hw-subset.c;libomptarget :: x86_64-pc-linux-gnu :: offloading/memory_manager.cpp"
- --xfail-not=LIST¶
不要将指定的测试视为
XFAIL。环境变量LIT_XFAIL_NOT也可以代替此选项使用。语法与--xfail和LIT_XFAIL相同。--xfail-not和LIT_XFAIL_NOT始终覆盖所有其他XFAIL规范，包括命令行后面出现的--xfail。主要目的是抑制XPASS结果，而无需修改使用XFAIL指令的测试用例。
其他选项¶
- --debug¶
在调试模式下运行lit，用于调试配置问题和lit本身。
- --show-suites¶
列出发现的测试套件并退出。
- --show-tests¶
列出所有发现的测试并退出。
退出状态¶
如果存在任何FAIL或XPASS结果，lit将以退出代码1退出。否则，它将以状态0退出。其他退出代码用于与测试无关的失败（例如用户错误或内部程序错误）。
测试发现¶
传递给lit的输入可以是单个测试，也可以是整个目录或要运行的测试层次结构。当lit启动时，它首先要做的事情是将输入转换为要作为测试发现一部分运行的完整测试列表。
在lit模型中，每个测试都必须存在于某个测试套件中。lit通过从输入路径向上搜索，直到找到lit.cfg或lit.site.cfg文件，从而将命令行上指定的输入解析为测试套件。这些文件既用作测试套件的标记，也用作配置文件，lit加载这些文件以了解如何查找和运行测试套件中的测试。
一旦lit将输入映射到测试套件，它就会遍历输入列表，为单个文件添加测试，并递归搜索目录中的测试。
这种行为使得指定要运行的测试子集变得很容易，同时仍然允许测试套件配置精确控制如何解释测试。此外，lit始终通过测试所属的测试套件及其在测试套件中的相对路径来识别测试。对于配置正确的项目，这允许lit为树外构建提供方便且灵活的支持。
测试状态结果¶
每个测试最终都会产生以下八个结果之一
PASS
测试成功。
FLAKYPASS
测试在重新运行多次后成功。这仅适用于包含
ALLOW_RETRIES:注释的测试。
XFAIL
测试失败，但这在预期之中。这用于允许指定测试当前无法工作但希望将其保留在测试套件中的测试格式。
XPASS
测试成功，但预期会失败。这用于指定为预期失败但现在成功的测试（通常是因为它们测试的功能已损坏并已修复）。
FAIL
测试失败。
UNRESOLVED
无法确定测试结果。例如，当测试无法运行、测试本身无效或测试被中断时，就会发生这种情况。
UNSUPPORTED
此环境不支持该测试。这由可以报告不受支持测试的测试格式使用。
TIMEOUT
测试已运行，但在能够完成之前超时。这被视为失败。
根据测试格式的不同，测试可能会产生关于其状态的额外信息（通常仅针对失败的情况）。有关更多信息，请参阅输出选项部分。
LIT 基础设施¶
本节介绍了lit测试架构，供那些有兴趣创建新的lit测试实现或扩展现有测试实现的用户参考。
lit本身主要是一个用于发现和运行任意测试，并为这些测试提供单一便捷接口的基础设施。lit本身不知道如何运行测试，而是由测试套件定义了此逻辑。
测试套件¶
如测试发现中所述，测试始终位于测试套件内。测试套件用于定义其包含的测试的格式、查找这些测试的逻辑以及运行测试的任何其他信息。
lit将包含lit.cfg或lit.site.cfg文件的目录识别为测试套件（另请参见--config-prefix）。通过递归搜索命令行传递的所有输入文件所在的目录层次结构，可以最初发现测试套件。可以使用--show-suites在启动时显示已发现的测试套件。
一旦发现测试套件，就会加载其配置文件。配置文件本身是将被执行的Python模块。执行配置文件时，会预定义两个重要的全局变量
lit_config
全局lit配置对象（一个LitConfig实例），它定义了内置测试格式、全局配置参数以及用于实现测试配置的其他辅助例程。
config
这是测试套件的配置对象（一个TestingConfig实例），配置文件需要填充此对象。以下变量也可在config对象上使用，其中一些必须由配置设置，而另一些则为可选或预定义的
name [必需] 测试套件的名称，用于报告和诊断。
test_format [必需] 将用于发现和运行测试套件中测试的测试格式对象。通常，这将是来自lit.formats模块的内置测试格式。
test_source_root 测试套件根目录的文件系统路径。对于目录外构建，这是将扫描测试的目录。
test_exec_root 对于目录外构建，对象目录内测试套件根目录的路径。测试将在此处运行，并放置临时输出文件。
environment 表示在套件中执行测试时使用的环境的字典。
standalone_tests 为真时，标记一个包含预期独立运行的测试的目录。对于该目录，将禁用测试发现。当此变量为真时，lit.suffixes和lit.excludes必须为空。
suffixes 对于扫描目录以查找测试的lit测试格式，此变量是用于识别测试文件的后缀列表。用于：ShTest。
substitutions 对于将变量替换到测试脚本中的lit测试格式，要执行的替换列表。用于：ShTest。
unsupported 标记不支持的目录，其中的所有测试都将报告为不支持。用于：ShTest。
parent 父配置，这是包含测试套件的目录的配置对象，或None。
root 根配置。这是项目中最顶层的lit配置。
pipefail 通常，使用shell管道进行测试，如果管道上的任何命令失败，则测试将失败。如果不需要，则将此变量设置为false将使测试仅在管道中的最后一个命令失败时才失败。
available_features 可用于XFAIL、REQUIRES和UNSUPPORTED指令的功能集。
测试发现¶
找到测试套件后，lit会递归遍历源目录（遵循test_source_root）以查找测试。当lit进入子目录时，它首先检查该目录中是否定义了嵌套测试套件。如果是，则递归加载该测试套件，否则它会为该目录实例化一个本地测试配置（请参阅本地配置文件）。
测试由其包含的测试套件以及该套件内的相对路径来标识。请注意，相对路径可能不引用磁盘上的实际文件；某些测试格式（例如GoogleTest）定义了“虚拟测试”，其路径包含实际测试文件的路径以及用于标识虚拟测试的子路径。
本地配置文件¶
当lit加载测试套件中的子目录时，它会通过克隆父目录的配置来实例化本地测试配置——此配置链的根始终是测试套件。克隆测试配置后，lit会在子目录中检查lit.local.cfg文件。如果存在，则将加载此文件，并可用于专门化每个单独目录的配置。此功能可用于定义可选测试的子目录，或更改其他配置参数——例如，更改测试格式或识别测试文件的后缀。
替换¶
lit允许在RUN命令内替换模式。它还提供了以下基本替换集，这些替换集在TestRunner.py中定义
宏
替换
%s
源路径（当前正在运行的文件的路径）
%S
源目录（当前正在运行的文件的目录）
%p
与%S相同
%{pathsep}
路径分隔符
%{fs-src-root}
指向LLVM检出的文件系统路径的根组件
%{fs-tmp-root}
指向测试临时目录的文件系统路径的根组件
%{fs-sep}
文件系统路径分隔符
%t
对测试唯一的临时文件名
%basename_t
%t的最后一个路径组件，但不带
.tmp扩展名%T
%t的父目录（不唯一，已弃用，请勿使用）
%%
%
%/s
%s，但
\被/替换%/S
%S，但
\被/替换%/p
%p，但
\被/替换%/t
%t，但
\被/替换%/T
%T，但
\被/替换%{s:real}
扩展所有符号链接和替换驱动器后的%s
%{S:real}
扩展所有符号链接和替换驱动器后的%S
%{p:real}
扩展所有符号链接和替换驱动器后的%p
%{t:real}
扩展所有符号链接和替换驱动器后的%t
%{T:real}
扩展所有符号链接和替换驱动器后的%T
%{/s:real}
扩展所有符号链接和替换驱动器后的%/s
%{/S:real}
扩展所有符号链接和替换驱动器后的%/S
%{/p:real}
扩展所有符号链接和替换驱动器后的%/p
%{/t:real}
扩展所有符号链接和替换驱动器后的%/t
%{/T:real}
扩展所有符号链接和替换驱动器后的%/T
%{/s:regex_replacement}
%/s，但已转义以在sed的
s@@@命令的替换中使用%{/S:regex_replacement}
%/S，但已转义以在sed的
s@@@命令的替换中使用%{/p:regex_replacement}
%/p，但已转义以在sed的
s@@@命令的替换中使用%{/t:regex_replacement}
%/t，但已转义以在sed的
s@@@命令的替换中使用%{/T:regex_replacement}
%/T，但已转义以在sed的
s@@@命令的替换中使用%:s
在Windows上，%/s，但如果它是第二个字符，则会删除
:。否则，%s，但删除了单个前导/。%:S
在Windows上，%/S，但如果它是第二个字符，则会删除
:。否则，%S，但删除了单个前导/。%:p
在Windows上，%/p，但如果它是第二个字符，则会删除
:。否则，%p，但删除了单个前导/。%:t
在Windows上，%/t，但如果它是第二个字符，则会删除
:。否则，%t，但删除了单个前导/。%:T
在Windows上，%/T，但如果它是第二个字符，则会删除
:。否则，%T，但删除了单个前导/。
提供了其他替换，这些替换是此基本集的变体，并且每个测试模块都可以进一步定义替换模式。请参阅模块本地配置文件。
有关替换的更多详细信息，请参阅LLVM 测试基础设施指南。
测试运行输出格式¶
测试运行的lit输出符合以下模式，无论是在简短模式还是详细模式下（尽管在简短模式下不会显示任何PASS行）。此模式的选择是为了相对容易地被机器可靠地解析（例如，在buildbot日志抓取中），以及供其他工具生成。
每个测试结果都应出现在与以下匹配的行上
<result code>: <test name> (<progress info>)
其中<result-code>是标准测试结果，例如PASS、FAIL、XFAIL、XPASS、UNRESOLVED或UNSUPPORTED。还允许使用IMPROVED和REGRESSED的性能结果代码。
<test name>字段可以包含任意不包含换行符的字符串。
<progress info>字段可用于报告进度信息，例如(1/300)，或可以为空，但即使为空，也需要括号。
每个测试结果可能包含以下格式的额外（多行）日志信息
<log delineator> TEST '(<test name>)' <trailing delineator>
... log message ...
<log delineator>
其中 <test name> 应为前面已报告测试的名称，<log delineator> 是由“*”字符组成的字符串，其长度**至少**为四个字符（建议长度为 20），而 <trailing delineator> 是一个任意（未解析）的字符串。
以下是一个测试运行输出示例，其中包含四个测试 A、B、C 和 D，以及对于失败测试 C 的日志消息。
PASS: A (1 of 4)
PASS: B (2 of 4)
FAIL: C (3 of 4)
******************** TEST 'C' FAILED ********************
Test 'C' failed as a result of exit code 1.
********************
PASS: D (4 of 4)
默认特性¶
为了方便起见，lit 会自动为一些常见用例添加 **available_features**。
lit 根据正在构建的操作系统添加特性，例如：system-darwin、system-linux 等。lit 还根据当前架构自动添加特性，例如 target-x86_64、target-aarch64 等。
在启用编译器运行时检查工具的情况下构建时，lit 会自动添加编译器运行时检查工具的简称，例如：asan、tsan 等。
要查看可以添加的完整特性列表，请参阅 llvm/utils/lit/lit/llvm/config.py。
LIT 示例测试¶
lit 发行版在 ExampleTests 目录中包含几个测试套件示例实现。
另请参阅¶
valgrind(1)