lit - LLVM統合テスター

概要

lit [オプション] [テスト]

説明

lit は、LLVMおよびClangスタイルのテストスイートを実行し、その結果を要約し、失敗の兆候を提供するための移植可能なツールです。 lit は、できるだけシンプルなユーザーインターフェースを備えた軽量のテストツールとして設計されています。

lit は、コマンドラインで指定された実行する1つ以上の*テスト*で実行する必要があります。テストは、個々のテストファイルまたはテストを検索するディレクトリのいずれかになります（テストの発見を参照）。

指定された各テストは（潜在的に同時に）実行され、すべてのテストが実行されると、lit は合格または失敗したテストの数に関する概要情報を表示します（テストステータス結果を参照）。いずれかのテストが失敗した場合、lit プログラムはゼロ以外の終了コードで実行されます。

デフォルトでは、lit は簡潔な進行状況表示を使用し、テストの失敗に関する概要情報のみを出力します。 lit の進行状況表示と出力を制御するオプションについては、出力オプションを参照してください。

lit には、テストの実行方法を制御するための多くのオプションも含まれています（特定の機能は、特定のテスト形式によって異なる場合があります）。詳細については、実行オプションを参照してください。

最後に、lit は、コマンドラインで指定されたオプションのサブセットのみを実行するための追加オプションもサポートしています。詳細については、選択オプションを参照してください。

lit は、コマンドラインからオプションを解析した後、環境変数 LIT_OPTS からオプションを解析します。 LIT_OPTS は、主に、プロジェクトのビルドシステムによって lit に提供されるコマンドラインオプションを補完またはオーバーライドするために役立ちます。

lit は、 @path/to/file.rsp 構文を使用して入力として指定されたレスポンスファイルからもオプションを読み取ることができます。ファイルから読み取られた引数は1行につき1つでなければならず、コマンドラインの元のファイル参照引数と同じ場所にあるかのように扱われます。レスポンスファイルは他のレスポンスファイルを参照できます。

lit アーキテクチャに興味があるユーザー、または lit テスト実装を設計するユーザーは、LITインフラストラクチャを参照してください。

一般オプション

-h, --help

lit ヘルプメッセージを表示します。

-j N, --workers=N

N 個のテストを並列に実行します。デフォルトでは、これは検出された使用可能なCPUの数と一致するように自動的に選択されます。

--config-prefix=NAME

lit.cfg および lit.site.cfg の代わりに、 NAME.cfg および NAME.site.cfg を検索してテストスイートを検索します。

-D NAME[=VALUE], --param NAME[=VALUE]

指定された VALUE（指定されていない場合は空の文字列）を使用して、ユーザー定義パラメーター NAME を追加します。 これらのパラメータの意味と使い方はテストスイートによって異なります。

出力オプション

-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」機能も自動的に提供します。

--vg-arg=ARG

--vg が使用されている場合、valgrind 自体に渡す追加の引数を指定します。

--vg-leak

--vg が使用されている場合、メモリリークチェックを有効にします。 このオプションが有効になっている場合、lit は、特定のテストを条件付きで無効にする（または失敗を予期する）ために使用できる「vg_leak」機能も自動的に提供します。

--skip-test-time-recording

個々のテストの実行にかかる時間を追跡しません。

--time-tests

個々のテストの実行にかかる時間を追跡し、その結果をサマリー出力に含めます。これは、テストスイートの中でどのテストの実行に最も時間がかかるかを判断するのに役立ちます。

--ignore-fail

いくつかのテストが失敗しても、ステータスゼロで終了します。

選択オプション

デフォルトでは、lit は最初に失敗したテストを実行し、次に並列処理を最適化するために実行時間の降順でテストを実行します。実行順序は --order オプションを使用して変更できます。

タイミングデータは、test_exec_root に .lit_test_times.txt という名前のファイルに保存されます。このファイルが存在しない場合、lit は test_source_root でファイルをチェックして、クリーンビルドを高速化することができます。

--shuffle

テストを失敗/低速順ではなく、ランダムな順序で実行します。非推奨です。代わりに --order を使用してください。

--per-test-coverage

テストケースごとに分割された、必要なテストカバレッジデータを出力します（各RUNにLLVM_PROFILE_FILEに一意の値を設定することが含まれます）。カバレッジデータファイルは、config.test_exec_root で指定されたディレクトリに出力されます。

--max-failures N

指定された数の失敗 N の後に実行を停止します。実行前にコマンドラインで整数引数を渡す必要があります。

--max-tests=N

最大で N 個のテストを実行し、その後終了します。

--max-time=N

テストの実行に最大 N 秒（約）費やし、その後終了します。これは --timeout のエイリアスではありません。これら2つは異なる種類の最大値です。

--num-shards=M

選択されたテストのセットを M 個の等しいサイズのサブセットまたは「シャード」に分割し、そのうちの1つだけを実行します。実行するシャードを選択する --run-shard=N オプションと一緒に使用する必要があります。環境変数 LIT_NUM_SHARDS もこのオプションの代わりに使用できます。これらの2つのオプションは、（大規模なテストファームなどの）別々のマシンで並列実行するために、大規模なテストスイートを分割するための粗いメカニズムを提供します。

--order={lexical,random,smart}

テストを実行する順序を定義します。サポートされている値は次のとおりです。

  • lexical - テストはテストファイルパスに従って辞書順に実行されます。このオプションは、予測可能なテスト順序が必要な場合に役立ちます。

  • random - テストはランダムな順序で実行されます。

  • smart - 以前に失敗したテストが最初に実行され、次に残りのテストがすべて実行時間の降順で実行されます。これは、並列処理を最適化するため、デフォルトです。

--run-shard=N

--num-shards=M オプションが指定されていると仮定して、実行するシャードを選択します。2つのオプションを一緒に使用する必要があり、N の値は 1..M の範囲内である必要があります。環境変数 LIT_RUN_SHARD もこのオプションの代わりに使用できます。

--timeout=N

個々のテストの実行に最大 N 秒（約）費やします。0 は時間制限がないことを意味し、0 がデフォルトです。これは --max-time のエイリアスではありません。これら2つは異なる種類の最大値です。

--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"

この場合、以下のすべてのテストは XFAIL として扱われます

libomp :: 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 バージョンをXFAILとして扱わないようにすることができます

LIT_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

検出されたすべてのテストを一覧表示して終了します。

終了ステータス

lit は、FAILまたはXPASSの結果がある場合、終了コード1で終了します。それ以外の場合、ステータス0で終了します。その他の終了コードは、テストに関連しないエラー（ユーザーエラーや内部プログラムエラーなど）に使用されます。

テストの検出

lit に渡される入力は、個々のテスト、または実行するテストのディレクトリ全体または階層にすることができます。 lit が起動すると、最初に行うことは、入力を*テスト検出*の一部として実行するテストの完全なリストに変換することです。

lit モデルでは、すべてのテストは*テストスイート*内に存在する必要があります。 lit は、lit.cfg または lit.site.cfg ファイルが見つかるまで、入力パスから上方向に検索することで、コマンドラインで指定された入力をテストスイートに解決します。これらのファイルは、テストスイートのマーカーと、lit がテストスイート内のテストを見つけて実行する方法を理解するためにロードする構成ファイルの両方として機能します。

lit が入力をテストスイートにマッピングすると、入力のリストをトラバースし、個々のファイルのテストを追加し、ディレクトリ内のテストを再帰的に検索します。

この動作により、実行するテストのサブセットを簡単に指定できる一方で、テストスイートの構成でテストの解釈方法を正確に制御できます。さらに、lit は常に、テストが存在するテストスイートと、テストスイート内の相対パスによってテストを識別します。適切に構成されたプロジェクトの場合、これにより lit は、ツリー外のビルドに対して便利で柔軟なサポートを提供できます。

テストステータス結果

各テストは最終的に、次の8つの結果のいずれかを生成します。

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モジュールです。構成ファイルが実行されると、2つの重要なグローバル変数が事前に定義されます。

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** 通常、シェルパイプを使用するテストは、パイプ上のコマンドのいずれかが失敗すると失敗します。これが望ましくない場合、この変数を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}

sed の s@@@ コマンドの置換で使用するためにエスケープされた %/s

%{/S:regex_replacement}

sed の s@@@ コマンドの置換で使用するためにエスケープされた %/S

%{/p:regex_replacement}

sed の s@@@ コマンドの置換で使用するためにエスケープされた %/p

%{/t:regex_replacement}

sed の s@@@ コマンドの置換で使用するためにエスケープされた %/t

%{/T:regex_replacement}

sed の s@@@ コマンドの置換で使用するためにエスケープされた %/T

%:s

Windows では、2 番目の文字が : の場合は削除された %/s。それ以外の場合は、先頭の / が 1 つ削除された %s。

%:S

Windows では、2 番目の文字が : の場合は削除された %/S。それ以外の場合は、先頭の / が 1 つ削除された %S。

%:p

Windows では、2 番目の文字が : の場合は削除された %/p。それ以外の場合は、先頭の / が 1 つ削除された %p。

%:t

Windows では、2 番目の文字が : の場合は削除された %/t。それ以外の場合は、先頭の / が 1 つ削除された %t。

%:T

Windows では、2 番目の文字が : の場合は削除された %/T。それ以外の場合は、先頭の / が 1 つ削除された %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> は *at least* 4 文字以上の「*」文字列（推奨の長さは 20）であり、<trailing delineator> は任意の（解析されない）文字列です。

以下は、4 つのテスト 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)