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 測試套件根目錄的檔案系統路徑。對於外部建置 (out-of-dir build)，這是將掃描以尋找測試的目錄。
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 等。
當使用啟用的 Sanitizer 進行建置時，lit 會自動新增 Sanitizer 的簡短名稱，例如：asan、tsan 等。
要查看可以新增的功能的完整列表，請參閱 llvm/utils/lit/lit/llvm/config.py。
LIT 範例測試¶
lit 發行版在 ExampleTests 目錄中包含多個測試套件的範例實作。
另請參閱¶
valgrind(1)