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 在輸出中每個指令 pipeline 前插入
'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。主要目的是在不修改使用XFAIL指令的測試案例的情況下隱藏XPASS結果。
其他選項¶
- --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 如果為 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
%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>)
其中 <結果代碼> 是標準測試結果，例如 PASS、FAIL、XFAIL、XPASS、UNRESOLVED 或 UNSUPPORTED。也允許使用效能結果代碼 IMPROVED 和 REGRESSED。
<測試 名稱> 欄位可以包含不含換行符號的任意字串。
<進度 資訊> 欄位可用於報告進度資訊，例如 (1/300)，也可以為空，但即使為空，也需要括號。
每個測試結果可以使用以下格式包含額外的（多行）日誌資訊
<log delineator> TEST '(<test name>)' <trailing delineator>
... log message ...
<log delineator>
其中 <測試 名稱> 應該是先前報告的測試的名稱，<日誌 分隔符號> 是「*」字元組成的字串，至少 四個字元長（建議長度為 20），<結尾 分隔符號> 是任意的（未解析的）字串。
以下是一個測試執行輸出範例，其中包含四個測試 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)