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 帮助消息并退出。
- --version¶
显示 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，但适用于所有测试，而不仅仅是失败的测试。
- -o PATH, --output PATH¶
将测试结果写入提供的路径。
- --no-progress-bar¶
不使用基于 curses 的进度条。
- --show-excluded¶
显示排除的测试。
- --show-skipped¶
显示跳过的测试。
- --show-unsupported¶
显示不支持的测试。
- --show-pass¶
显示通过的测试。
- --show-flakypass¶
显示重试后通过的测试。
- --show-xfail¶
显示预期失败的测试。
执行选项¶
- --gtest-sharding¶
为 GoogleTest 格式启用分片。
- --no-gtest-sharding¶
为 GoogleTest 格式禁用分片。
- --path=PATH¶
指定在测试中搜索可执行文件时使用的附加
PATH。
- --vg¶
在 valgrind 下（使用 memcheck 工具）运行单个测试。valgrind 使用
--error-exitcode参数，以便 valgrind 失败将导致程序以非零状态退出。启用此选项后，lit 还会自动提供一个 “
valgrind” 功能，该功能可用于有条件地禁用（或预期失败）某些测试。
- --no-execute¶
不执行任何测试（假设它们通过）。
- --xunit-xml-output XUNIT_XML_OUTPUT¶
将 XUnit 兼容的 XML 测试报告写入到指定的文件。
- --report-failures-only¶
仅在报告中包含未解决、超时、失败和意外通过的测试。
- --resultdb-output RESULTDB_OUTPUT¶
将 LuCI ResultDB 兼容的 JSON 写入到指定的文件。
- --time-trace-output TIME_TRACE_OUTPUT¶
将 Chrome 跟踪兼容的 JSON 写入到指定的文件
- --timeout MAXINDIVIDUALTESTTIME¶
运行单个测试的最长时间（以秒为单位）。0 表示没有时间限制。[默认值：0]
- --timeout=N¶
最多花费
N秒（大约）运行每个单独的测试。0表示没有时间限制，0是默认值。请注意，这不是--max-time的别名；两者是不同类型的最大值。
- --max-failures MAX_FAILURES¶
在给定数量的失败后停止执行。
- --allow-empty-runs¶
如果所有测试都被过滤掉，则不使运行失败。
- --per-test-coverage¶
发出必要的测试覆盖率数据，按测试用例划分（涉及为每个 RUN 设置一个唯一值给 LLVM_PROFILE_FILE）。覆盖率数据文件将会在
config.test_exec_root指定的目录中发出。
- --ignore-fail¶
即使某些测试失败，也以状态零退出。
- --skip-test-time-recording¶
不跟踪每个测试经过的挂钟时间。
- --time-tests¶
跟踪单个测试执行所花费的挂钟时间，并将结果包含在摘要输出中。这对于确定测试套件中哪些测试花费最多时间执行非常有用。
选择选项¶
默认情况下，lit 将首先运行失败的测试，然后按降序执行时间顺序运行测试，以优化并发性。可以使用 --order 选项更改执行顺序。
计时数据存储在 test_exec_root 中的名为 .lit_test_times.txt 的文件中。如果此文件不存在，则 lit 检查 test_source_root 中的文件，以可选地加速干净构建。
- --max-tests=N¶
最多运行
N个测试，然后终止。
- --order={lexical,random,smart}¶
定义测试运行的顺序。支持的值为
lexical - 测试将按照测试文件路径的词汇顺序运行。当需要可预测的测试顺序时，此选项很有用。
random - 测试将以随机顺序运行。
smart - 先运行之前失败的测试，然后运行剩余的测试，所有测试都按降序执行时间顺序排列。这是默认设置，因为它优化了并发性。
- -i, --incremental¶
首先运行失败的测试（已弃用：使用
--order=smart）。
- --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指令的测试用例。
- --num-shards=M¶
将选定的测试集划分为
M个大小相等的子集或 “分片”，并且仅运行其中一个。必须与--run-shard=N选项一起使用，该选项选择要运行的分片。环境变量LIT_NUM_SHARDS也可以用来代替此选项。这两个选项提供了一种粗略的机制，用于划分大型测试套件，以便在单独的机器上并行执行（例如在大型测试场中）。
- --run-shard=N¶
假设提供了
--num-shards=M选项，则选择要运行的分片。这两个选项必须一起使用，并且N的值必须在1..M范围内。环境变量LIT_RUN_SHARD也可以用来代替此选项。
附加选项¶
- --debug¶
在调试模式下运行 lit，用于调试配置问题和 lit 本身。
- --show-suites¶
列出发现的测试套件并退出。
- --show-tests¶
列出所有发现的测试并退出。
- --show-used-features¶
显示测试套件中使用的所有功能（在
XFAIL、UNSUPPORTED和REQUIRES中）并退出。
退出状态¶
如果有任何 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 如果为 true，则标记一个包含预期独立运行的测试的目录。禁用该目录的测试发现。当此变量为 true 时，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:stem}）%T
%t 的父目录（非唯一，已弃用，请勿使用）
%%
%
%/s
与 %s 相同，但
\替换为/%/S
与 %S 相同，但
\替换为/%/p
与 %p 相同，但
\替换为/%/t
与 %t 相同，但
\替换为/%/T
与 %T 相同，但
\替换为/%{s:basename}
%s 的最后一个路径组件
%{t:stem}
%t 的最后一个路径组件，但不带
.tmp扩展名（%basename_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 等。
当使用启用的 sanitizers 进行构建时，lit 会自动添加 sanitizer 的短名称，例如：asan、tsan 等。
要查看可以添加的功能的完整列表，请参阅 llvm/utils/lit/lit/llvm/config.py。
LIT 示例测试¶
lit 发行版在 ExampleTests 目录中包含几个测试套件的示例实现。
另请参阅¶
valgrind(1)