百科事典をテストする

問題を報告 ソースを表示 Nightly · 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

テスト実行環境の詳細な仕様。

背景

Bazel BUILD 言語には、多くの言語で自動テストプログラムを定義するために使用できるルールが含まれています。

テストは bazel test を使用して実行されます。

テストバイナリを直接実行することもできます。こうした行為は許可されていますが、支持されているわけではありません。 以下に説明する要件を遵守するものではありません。

テストは気密性が保たれている必要があります。つまり、宣言された依存関係があるリソースにのみアクセスする必要があります。テストが密閉型でなければ 再現性のある結果が得られませんこれは、原因の特定（どの変更がテストを破壊したかの特定）、リリース エンジニアリングの監査可能性、テストのリソース分離にとって重大な問題になる可能性があります（自動テスト フレームワークは、一部のテストがサーバーと通信するため、サーバーを DDoS してはなりません）。

目標

このページの目標は、Google Compute Engine アプリケーションのランタイム環境を Bazel テストで想定される動作を再現しました。また、テストに関する要件も課されます。 ビルドシステムを定義します。

テスト環境仕様により、テスト作成者は未指定の動作に依存しなくて済むため、テスト インフラストラクチャで実装の変更をより自由に行えます。この仕様では、現在、適切に完全性、確定性、再入性を備えていないにもかかわらず、多くのテストが合格しているいくつかの穴を締めています。

このページは規範的で信頼できるものであることを意図しています。もし テストランナーの仕様と実装された動作が一致しない場合、 指定が優先されます。

提案された仕様

キーワード「MUST」、「MUST NOT」、「REQUIRED」、「SHALL」、「SHALL NOT」、「SHOULD」、「SHOULD NOT」、「RECOMMENDED」、「MAY」、「OPTIONAL」は、IETF RFC 2119 に記載されているように解釈されます。

テストの目的

Bazel テストの目的は、リポジトリにチェックインされたソースファイルのプロパティを確認することです。（このページの「ソースファイル」には、テストデータ、 サンプル出力、バージョン管理下にあるものなど）です。あるユーザーが 維持が期待される不変条件をアサートできます。その他のユーザー 後でテストを実行して、不変条件が壊れているかどうかを確認します。テストがソースファイル以外の変数に依存している場合（非完全性）、テストが合格しなくなったときに、後続のユーザーが変更が原因であると確信できないため、その価値は低下します。

したがって、テストの結果は次のものにのみ依存する必要があります。

  • テストで依存関係が宣言されているソースファイル
  • テストで依存関係が宣言されているビルドシステムのプロダクト
  • テストランナーによって動作が一定に保たれることが保証されているリソース

現在のところ、このような動作は適用されていません。ただし、テストランナーは、今後このような適用を追加する権利を留保します。

ビルドシステムの役割

テストルールは、それぞれが実行可能プログラムを生成しなければならないという点で、バイナリルールに似ています。言語によっては、これは言語固有のハーネスとテストコードを組み合わせたスタブ プログラムです。テストルールでは、 出力です。テストランナーは、メインのテスト実行可能ファイルに加えて、runfiles のマニフェスト（実行時にテストで使用できる入力ファイル）が必要になります。また、テストのタイプ、サイズ、タグに関する情報が必要になる場合があります。

ビルドシステムは、ランファイルを使用してコードとデータを配信する場合があります。（ 最適化として使用して、各テストバイナリのサイズを （ダイナミック リンクを使用するなど）。ビルドシステムは、生成された実行可能ファイルが、ソースツリーまたは出力ツリー内の絶対的な場所へのハードコードされた参照ではなく、テストランナーから提供される runfiles イメージを介してこれらのファイルを読み込むようにする必要があります。

テストランナーのロール

テストランナーの観点から見ると、各テストは execve() で呼び出されます。テストを実行する方法は他にもあります。たとえば IDE では Java テストをプロセス内で実行できます。しかし、結果 プロセスが信頼できるものと見なされなければなりません。条件 テストプロセスは完了するまで実行され、終了コードで正常に終了します。 テストは合格です。その他の結果はテストの不合格と見なされます。イン 特に、文字列 PASS または FAIL のいずれかを stdout に書き込んでも テストランナーに通知されます。

テストの実行に時間がかかりすぎた場合、なんらかのリソース上限を超えた場合、または 禁止されている動作を検出した場合は、テストを強制終了し、 実行は失敗として処理されますランナーは、テストプロセスまたはその子プロセスにシグナルを送信した後に、テストが合格したと報告してはなりません。

（個々のメソッドやテストではなく）テスト ターゲット全体には、 完了するまでにかかる時間です。テストの制限時間は、次の表に従って timeout 属性に基づいています。

timeout 制限時間（秒）
short 60
中 300
long 900
永遠 3600

タイムアウトを明示的に指定していないテストには、次のようにテストの size に基づいてタイムアウトが暗黙的に設定されます。

サイズ 暗黙的なタイムアウトのラベル
小 short
中 中
大 long
膨大な 永遠

「大」明示的なタイムアウト設定がないテストには、900 が割り当てられる 実行に時間がかかります。「ミディアム」タイムアウトを「short」に設定してテストする60 日割り当てられ 秒です。

timeout とは異なり、size は、一般的な定義で説明されているように、ローカルでテストを実行する際の他のリソース（RAM など）のピーク使用量を推定します。

size ラベルと timeout ラベルの組み合わせはすべて有効であるため、「非常に大きい」テストに「短い」タイムアウトを宣言できます。おそらく、データ アナリストは 恐ろしいことがすぐに見つかる

タイムアウトに関係なく、テストが任意の速さで返される場合があります。テストにペナルティはない 過剰なタイムアウトが発生しますが、警告が発行されることがあります。 通常は、不具合が発生することなく、タイムアウトをできるだけ厳しく設定します。

テストのタイムアウトは、次の場合に --test_timeout bazel フラグでオーバーライドできます。 手動で実行する場合です。「 --test_timeout の値は秒単位です。たとえば、--test_timeout=120 はテストのタイムアウトを 2 分に設定します。

また、テストのタイムアウトには下限があります。

timeout 最小時間（秒）
short 0
中 30
long 300
永遠 900

たとえば「moderate」オプションが5.5 秒でテストが完了するので、timeout = "short" または size = "small" の設定を検討してください。bazel --test_verbose_timeout_warnings の使用 コマンドライン オプションを使用すると、指定したサイズが大きすぎるテストが表示されます。

テストサイズとタイムアウトは、こちらの仕様に従って BUILD ファイルで指定します。条件 指定しない場合、テストのサイズはデフォルトで「medium」になります。

テストのメインプロセスが終了しても、その子プロセスの一部が実行中の場合、 テストランナーは実行が完了したと見なし、成功または メインプロセスから観測された終了コードに基づいて、テストランナーは、不要なプロセスを強制終了することがあります。この方法でテストでプロセスをリークしてはなりません。

テストのシャーディング

テストは、テスト シャーディングを使用して並列化できます。テスト シャーディングを有効にするには、--test_sharding_strategy と shard_count をご覧ください。シャーディングを有効にすると、テストランナーが 1 回起動 シャードあたり約 100 倍です環境変数 TEST_TOTAL_SHARDS はシャードの数で、TEST_SHARD_INDEX はシャード インデックス（0 から始まる）です。ランナーはこの情報を使用して、 たとえば、ラウンドロビン戦略を使用できます。すべてのテストランナーがシャーディングをサポートしているわけではありません。ランナーがシャーディングをサポートしている場合、 ファイルの更新日時を TEST_SHARD_STATUS_FILE。それ以外の場合、--incompatible_check_sharding_support が有効になっていると、テストがシャーディングされている場合、Bazel はテストを失敗させます。

初期条件

テストの実行時、テストランナーは特定の初期状態を あります。

テストランナーは、argv[0] にあるテスト実行可能ファイルのパスで各テストを呼び出す必要があります。このパスは、テストの現在のディレクトリ（runfiles ツリー内、後述）の下にある相対パスにする必要があります。テストランナーは ユーザーが明示的に要求しない限り、他の引数はテストに渡されません。

初期環境ブロックは次のように構成します。

変数 値 ステータス
HOME $TEST_TMPDIR の値 推奨
LANG 未設定 必須
LANGUAGE 未設定 必須
LC_ALL 未設定 必須
LC_COLLATE 未設定 必須
LC_CTYPE 未設定 必須
LC_MESSAGES 未設定 必須
LC_MONETARY 未設定 必須
LC_NUMERIC 未設定 必須
LC_TIME 未設定 必須
LD_LIBRARY_PATH 共有ライブラリを含むディレクトリをコロンで区切ったリスト 省略可
JAVA_RUNFILES $TEST_SRCDIR の値 廃止
LOGNAME $USER の値 必須
PATH /usr/local/bin:/usr/local/sbin:/usr/bin:/usr/sbin:/bin:/sbin:. 推奨
PWD $TEST_SRCDIR/workspace-name 推奨
SHLVL 2 推奨
TEST_INFRASTRUCTURE_FAILURE_FILE 書き込み可能なディレクトリにある非公開ファイルへの絶対パス（このファイルは、 テストで生じたエラーを報告する目的でのみ使用してください。 不安定な障害を報告するための一般的なメカニズムではなく、 含まれています。このコンテキストでは、テスト インフラストラクチャは、テスト固有ではないが、誤動作によってテストの失敗を引き起こす可能性があるシステムまたはライブラリと定義されます。1 行目は、テスト用インフラストラクチャの名前 2 つ目のコンポーネントは人が読める形式の エラーの説明が返されます。余分な行は無視されます）。 省略可
TEST_LOGSPLITTER_OUTPUT_FILE 書き込み可能なディレクトリ内の非公開ファイルへの絶対パス（Logsplitter protobuffer ログの書き込みに使用） 省略可
TEST_PREMATURE_EXIT_FILE 書き込み可能なディレクトリにあるプライベート ファイルへの絶対パス（ exit() への呼び出しのキャッチ） 省略可
TEST_RANDOM_SEED --runs_per_test オプションを使用すると、 TEST_RANDOM_SEED が run number に設定されている （1 から始まります）。 省略可
TEST_RUN_NUMBER --runs_per_test オプションを使用すると、 TEST_RUN_NUMBER が run number に設定されている （1 から始まります）。 省略可
TEST_TARGET テスト対象のターゲットの名前 省略可
TEST_SIZE テスト size 省略可
TEST_TIMEOUT テスト timeout（秒） 省略可
TEST_SHARD_INDEX シャード インデックス（sharding が使用されている場合） 省略可
TEST_SHARD_STATUS_FILE sharding のサポートを示すために接触するファイルのパス 省略可
TEST_SRCDIR runfiles ツリーのベースへの絶対パス 必須
TEST_TOTAL_SHARDS 合計 shard count sharding が使用されている場合 省略可
TEST_TMPDIR 書き込み可能なプライベート ディレクトリへの絶対パス 必須
TEST_WORKSPACE ローカル リポジトリのワークスペース名 省略可
TEST_UNDECLARED_OUTPUTS_DIR 書き込み可能なプライベート ディレクトリへの絶対パス（宣言されていないファイルを書き込むために使用 テスト出力）。TEST_UNDECLARED_OUTPUTS_DIR ディレクトリに書き込まれたファイルはすべて、圧縮されて bazel-testlogs の outputs.zip ファイルに追加されます。 省略可
TEST_UNDECLARED_OUTPUTS_ANNOTATIONS_DIR 書き込み可能な非公開ディレクトリの絶対パス（宣言されていないテスト出力アノテーション .part ファイルと .pb ファイルを書き込むために使用されます）。 省略可
TEST_WARNINGS_OUTPUT_FILE 書き込み可能なディレクトリ内の非公開ファイルへの絶対パス（テスト対象の警告の書き込みに使用） 省略可
TESTBRIDGE_TEST_ONLY 値 --test_filter （指定されている場合） 省略可
TZ UTC 必須
USER getpwuid(getuid())->pw_name の値 必須
XML_OUTPUT_FILE テストアクションがテスト結果の XML 出力ファイルを書き込む場所。それ以外の場合、Bazel はテストアクションの一部としてテストログをラップするデフォルトの XML 出力ファイルを生成します。XML スキーマは JUnit テスト結果スキーマに基づいています。 省略可
BAZEL_TEST テスト実行可能ファイルが bazel test によって実行されていることを示します 必須

環境には追加のエントリが含まれている場合があります。テストは、Terraform 言語コードや 上記以外の環境変数の有無、値。

最初の作業ディレクトリは $TEST_SRCDIR/$TEST_WORKSPACE とします。

現在のプロセス ID、プロセス グループ ID、セッション ID、親プロセス ID は指定されていません。プロセスは、プロセス グループ リーダーまたはセッション リーダーである場合とそうでない場合があります。プロセスには制御ターミナルが存在する場合と存在しない場合がある。このプロセスは 子プロセスがゼロ個以上で、実行されていない、または未処理の子プロセスが存在する。このプロセスでは、 複数のスレッドを持たせる必要があります。

ファイル記述子 0（stdin）は読み取り用にオープンされますが、アタッチされるもの は指定されていません。テストで読み取ってはなりません。ファイル記述子 1（stdout）と 2 （stderr）は書面で公開しますが、添付されるものは 指定されていません。ターミナル、パイプ、通常のファイルなど、 定義できます。開いているファイル テーブルのエントリを共有する （つまり、個別にシークすることはできません）。テストは、他の開いているファイル記述子を継承しないでください。

最初の umask は 022 または 027 にします。

アラームまたはインターバルタイマーは、保留状態になりません。

ブロックされたシグナルの初期マスクは空とします。すべてのシグナルを できます。

初期リソースの上限（ソフトとハード）は、次のように設定する必要があります。

リソース 上限
RLIMIT_AS 無制限
RLIMIT_CORE 指定なし
RLIMIT_CPU 無制限
RLIMIT_DATA 無制限
RLIMIT_FSIZE 無制限
RLIMIT_LOCKS 無制限
RLIMIT_MEMLOCK 無制限
RLIMIT_MSGQUEUE 指定なし
RLIMIT_NICE 指定なし
RLIMIT_NOFILE 1,024 以上
RLIMIT_NPROC 指定なし
RLIMIT_RSS 無制限
RLIMIT_RTPRIO 指定なし
RLIMIT_SIGPENDING 指定なし
RLIMIT_STACK 無制限、または 2,044 KB <= rlim <= 8,192 KB

初期プロセス時間（times() によって返される）とリソース使用率 （getrusage() によって返される）は指定されていません。

最初のスケジューリング ポリシーと優先度は指定されていません。

ホストシステムの役割

テスト実行の有効性を確保するには、テストランナーの直接制御下にあるユーザー コンテキストの要素に加えて、テストを実行するオペレーティング システムが特定のプロパティを満たしている必要があります。

ファイルシステム

テストで観測されるルート ディレクトリは、実際のルート ディレクトリである場合もあれば、そうでない場合もあります。

/proc をマウントします。

すべてのビルドツールは、SDK によって使用される /usr 配下の絶対パスに存在する ローカルにインストールします。

/home で始まるパスは使用できない場合があります。テストでアクセスすべきでないものは、 制限します。

/tmp は書き込み可能ですが、テストではこれらのパスの使用を避ける必要があります。

テストでは、定数パスが排他的に使用可能であると想定しない。

テストでは、マウントされたファイルシステムに対して atime が有効になっていることを前提としないでください。

ユーザーとグループ

ユーザー root、nobody、unittest が存在している必要があります。グループ root、nobody、eng が存在している必要があります。

テストは root 以外のユーザーとして実行する必要があります。実質のユーザー ID と有効なユーザー ID は、 等しいグループ ID についても同様です。さらに、現在のユーザー ID、グループ ID、 ユーザー名、グループ名は指定されていません補助グループ ID のセットは、 指定されていません。

現在のユーザー ID とグループ ID には、対応する名前が必要です。名前には、 getpwuid() と getgrgid() で取得します。同じことが 補助グループ ID を指定します。

現在のユーザーにホーム ディレクトリが必要です。書き込みできない可能性があります。テストで書き込みを試みないようにしてください。

ネットワーキング

ホスト名が指定されていません。ドットを含む場合と含まない場合があります。ホスト名を解決すると、現在のホストの IP アドレスが返されます。ホスト名のカットの解決 機能します。ホスト名 localhost を解決する必要があります。

その他のリソース

テストには少なくとも 1 つの CPU コアが付与されます。他のフォーマットを利用できる可能性はありますが、 保証されています。このコアのその他のパフォーマンス要素は指定されていません。テストルールにタグ「cpu:n」（n は正の整数）を追加すると、予約をより多くの CPU コアに増やすことができます。マシンの CPU コア数がリクエストされた数より少ない場合でも、Bazel はテストを実行します。テストでシャーディングを使用する場合、各シャードはここで指定された CPU コア数を予約します。

テストではサブプロセスを作成できますが、プロセス グループやセッションは作成できません。

テストで使用できる入力ファイルの数には上限があります。この上限は変更される可能性がありますが、現在は数万個の入力の範囲内です。

日時

現在の日時が指定されていません。システムのタイムゾーンが指定されていません。

X Windows は、利用できる場合と利用できない場合があります。X サーバーを必要とするテストを開始する必要がある Xvfb。

ファイルシステムとのやり取りをテストする

テスト環境変数で指定されたファイルパスは、特に指定しない限り、ローカル ファイル システム上のどこかを指しています。

テストでは、terraform plan または terraform apply で指定された $TEST_TMPDIR と $TEST_UNDECLARED_OUTPUTS_DIR（設定されている場合）。

これらのディレクトリは最初は空です。

テストでは、これらのディレクトリの削除、chmod、その他の変更を試みてはなりません。

これらのディレクトリはシンボリック リンクである可能性があります。

$TEST_TMPDIR/. のファイル システム タイプは指定されません。

テストでは、宣言されていない出力ファイルにアノテーションを付けるために、.part ファイルを $TEST_UNDECLARED_OUTPUTS_ANNOTATIONS_DIR に書き込むこともあります。

まれに、テストで /tmp にファイルの作成が強制されることがあります。たとえば、Unix ドメイン ソケットのパスの長さの上限がある場合は、通常、/tmp の下にソケットを作成する必要があります。Bazel はこのようなファイルを追跡できません。テスト自体は、他のテストやテスト以外のプロセスと同時に実行されて衝突しないように一意のパスを使い、/tmp に作成したファイルをクリーンアップするように注意する必要があります。

JUnit4 TemporaryFolder や Go TempDir などの一般的なテスト フレームワークには、/tmp の下に一時ディレクトリを作成する独自の方法があります。これらのテスト フレームワークには、/tmp 内のファイルをクリーンアップする機能が含まれているため、TEST_TMPDIR の外部にファイルを作成しても使用できます。

テストは、runfiles メカニズムなど、Terraform のその他の部分を通じて入力にアクセスする必要があります。 入力ファイルを作成することを目的とする実行環境 できます。

テストは、独自の実行可能ファイルのロケーションから推測されたパスにあるビルドシステムの他の出力にアクセスしてはなりません。

runfiles ツリーに通常のファイル、シンボリック リンク、またはその両方が含まれているかどうかは指定されていません。runfiles ツリーには、ディレクトリへのシンボリック リンクが含まれている場合があります。テストでは、ランファイル ツリー内に .. コンポーネントを含むパスを使用しないでください。

runfiles ツリー内のディレクトリ、ファイル、シンボリック リンク（シンボリック リンクを移動するパスを含む）は、書き込み可能にする必要があります。（したがって、最初の作業ディレクトリは書き込み可能にする必要があります）。テストでは、インフラストラクチャのいかなる部分も runfile が書き込み可能であるか、または現在のユーザーが所有していること（たとえば、chmod と chgrp は 失敗します）。

テストの実行中に、runfiles ツリー（シンボリック リンクを移動するパスを含む）が変更されてはなりません。親ディレクトリとファイルシステムのマウントは変更しないでください runfile 内のパスの解決結果に影響を及ぼす 表示されます。

早期終了をキャッチするために、テストは開始時に TEST_PREMATURE_EXIT_FILE で指定されたパスにファイルを作成し、終了時に削除することがあります。Bazel で以下が確認された場合、 ファイルが予期せず終了した場合は、テストが早期に終了したと見なされ、 失敗としてマークします

タグの規則

テストルール内のタグの中には、特別な意味を持つものがあります。関連ドキュメント: tags 属性に関する Bazel ビルド エンサイクロペディア。

タグ 意味
exclusive 他のテストを同時に実行しない
external テストに外部依存関係があるため、テスト キャッシュを無効にする
large test_suite 規則: 大規模なテストスイート
manual * ワイルドカードのターゲット パターンにテスト ターゲットを含めない :...、:*、または :all
medium test_suite 規則: 中程度のテストスイート
small test_suite 規則: 一連の小規模なテスト
smoke test_suite 規則:コンテナを実行する前に コードの変更をバージョン管理システムに commit する

Runfiles

以下では、*_binary() ルールにラベルが付けられていると仮定します。 //foo/bar:unittest（ラベル付きのルールに対するランタイム依存関係あり） //deps/server:server。

場所

ターゲット //foo/bar:unittest の runfiles ディレクトリは、 $(WORKSPACE)/$(BINDIR)/foo/bar/unittest.runfiles。このパスは runfiles_dir と呼ばれます。

依存関係

runfiles ディレクトリは、 *_binary() ルール。runfiles ディレクトリ自体は、*_binary() ルールまたはそのコンパイル時または実行時の依存関係に影響する BUILD ファイルのセットに依存します。ソースファイルを変更しても、インフラストラクチャの構造には そのため、再ビルドはトリガーされません。

目次

runfiles ディレクトリには次のものが含まれます。

  • 実行時の依存関係へのシンボリック リンク: 各 OutputFile と CommandRule が *_binary() ルールのランタイム依存関係は、 runfiles ディレクトリのシンボリック リンクです。シンボリック リンクの名前は、 $(WORKSPACE)/package_name/rule_name。たとえば、サーバーのシンボリック リンクの名前は $(WORKSPACE)/deps/server/server で、フルパスは $(WORKSPACE)/foo/bar/unittest.runfiles/$(WORKSPACE)/deps/server/server になります。シンボリック リンクの宛先は OutputFile の OutputFileName() または CommandRule。絶対パスで表されます。したがって、シンボリック リンクの宛先は $(WORKSPACE)/linux-dbg/deps/server/42/server になります。
  • サブランファイルへのシンボリック リンク: ランタイムである *_binary() Z ごと *_binary() C の依存関係がある場合、実行ファイルに 2 つ目のリンクがあります。 C のディレクトリを Z の runfile にコピーします。シンボリック リンクの名前は、 $(WORKSPACE)/package_name/rule_name.runfiles。シンボリック リンクのターゲットは 自動的に作成します。たとえば、すべてのサブプログラムは共通の runfiles ディレクトリを共有します。