テスト

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。
問題を報告する ソースを表示

Bazel で Starlark のコードをテストする方法はいくつかあります。このページでは、現在のベスト プラクティスとフレームワークをユースケース別に収集します。

ルールのテスト

Skylib には unittest.bzl というテスト フレームワークがあり、アクションやプロバイダなどのルールの分析時の動作を確認できます。このようなテストは「分析テスト」と呼ばれ、ルールの内部動作をテストするのに最適なオプションです。

注意点:

  • テスト アサーションは、個別のテストランナー プロセスではなく、ビルド内で行われます。テストによって作成されたターゲットは、他のテストやビルドのターゲットと競合しないように名前を付ける必要があります。テスト中に発生するエラーは、Bazel でテストの失敗ではなくビルドの破損と見なされます。

  • テスト対象のルールとテスト アサーションを含むルールを設定するには、かなりの量のボイラープレートが必要です。このボイラープレートは、最初は大変に思えるかもしれません。留意点として、マクロは評価され、読み込みフェーズ中にターゲットが生成されます。一方、ルール実装関数は、分析フェーズの後半まで実行されません。

  • 分析テストは、比較的小規模で軽量であることが意図されています。分析テスト フレームワークの特定の機能は、推移的依存関係の最大数(現在は 500)を持つターゲットの検証に限定されています。これは、これらの機能を大規模なテストで使用するとパフォーマンスに影響するためです。

基本原則は、テスト対象のルールに依存するテストルールを定義することです。これにより、テストルールにテスト対象ルールのプロバイダへのアクセスが許可されます。

テストルールの実装関数はアサーションを実行します。エラーが発生した場合、fail() を呼び出して(分析時のビルドエラーがトリガーされて)すぐに発生するのではなく、テスト実行時に失敗する生成スクリプトにエラーを保存することによって生じます。

下記にシンプルなおもちゃの例と、アクションをチェックする例を示します。

最も簡単な例

//mypkg/myrules.bzl:

MyInfo = provider(fields = {
    "val": "string value",
    "out": "output File",
})

def _myrule_impl(ctx):
    """Rule that just generates a file and returns a provider."""
    out = ctx.actions.declare_file(ctx.label.name + ".out")
    ctx.actions.write(out, "abc")
    return [MyInfo(val="some value", out=out)]

myrule = rule(
    implementation = _myrule_impl,
)

//mypkg/myrules_test.bzl:

load("@bazel_skylib//lib:unittest.bzl", "asserts", "analysistest")
load(":myrules.bzl", "myrule", "MyInfo")

# ==== Check the provider contents ====

def _provider_contents_test_impl(ctx):
    env = analysistest.begin(ctx)

    target_under_test = analysistest.target_under_test(env)
    # If preferred, could pass these values as "expected" and "actual" keyword
    # arguments.
    asserts.equals(env, "some value", target_under_test[MyInfo].val)

    # If you forget to return end(), you will get an error about an analysis
    # test needing to return an instance of AnalysisTestResultInfo.
    return analysistest.end(env)

# Create the testing rule to wrap the test logic. This must be bound to a global
# variable, not called in a macro's body, since macros get evaluated at loading
# time but the rule gets evaluated later, at analysis time. Since this is a test
# rule, its name must end with "_test".
provider_contents_test = analysistest.make(_provider_contents_test_impl)

# Macro to setup the test.
def _test_provider_contents():
    # Rule under test. Be sure to tag 'manual', as this target should not be
    # built using `:all` except as a dependency of the test.
    myrule(name = "provider_contents_subject", tags = ["manual"])
    # Testing rule.
    provider_contents_test(name = "provider_contents_test",
                           target_under_test = ":provider_contents_subject")
    # Note the target_under_test attribute is how the test rule depends on
    # the real rule target.

# Entry point from the BUILD file; macro for running each test case's macro and
# declaring a test suite that wraps them together.
def myrules_test_suite(name):
    # Call all test functions and wrap their targets in a suite.
    _test_provider_contents()
    # ...

    native.test_suite(
        name = name,
        tests = [
            ":provider_contents_test",
            # ...
        ],
    )

//mypkg/BUILD:

load(":myrules.bzl", "myrule")
load(":myrules_test.bzl", "myrules_test_suite")

# Production use of the rule.
myrule(
    name = "mytarget",
)

# Call a macro that defines targets that perform the tests at analysis time,
# and that can be executed with "bazel test" to return the result.
myrules_test_suite(name = "myrules_test")

テストは bazel test //mypkg:myrules_test で実行できます。

このファイルには、最初の load() ステートメント以外にも 2 つの部分があります。

  • テスト自体は、1)テストルールの分析時実装関数、2)analysistest.make() によるテストルールの宣言、3)テスト対象ルール(およびその依存関係)の宣言時の読み込み時関数(マクロ)とテストルールで構成されます。テストケース間でアサーションが変更されない場合は、1)と 2)を複数のテストケースで共有できます。

  • テストスイート関数。テストごとに読み込み時間関数を呼び出し、すべてのテストをまとめる test_suite ターゲットを宣言します。

整合性を保つため、推奨の命名規則に従います。foo は、テストがチェックする内容を記述するテスト名の部分を表します(上記の例では provider_contents)。たとえば、JUnit テストメソッドは testFoo という名前になります。

した後:

  • テストとテスト対象のマクロを生成するマクロの名前は、_test_foo_test_provider_contents)にする必要があります。

  • そのテストルールのタイプは、foo_testprovider_contents_test)である必要があります

  • このルールタイプのターゲットのラベルは foo_testprovider_contents_test)です。

  • テストルールの実装関数は、_foo_test_impl_provider_contents_test_impl)という名前にする必要があります。

  • テスト対象のルールのターゲットとその依存関係のラベルは、foo_provider_contents_)で始まる必要があります

すべてのターゲットのラベルは、同じ BUILD パッケージの他のラベルと競合する可能性があるため、テストには一意の名前を付けると便利です。

障害テスト

特定の入力や特定の状態でルールが失敗することを確認すると便利です。これは、分析テスト フレームワークを使用して行うことができます。

analysistest.make で作成したテストルールでは、expect_failure を指定する必要があります。

failure_testing_test = analysistest.make(
    _failure_testing_test_impl,
    expect_failure = True,
)

テストルールの実装では、発生した障害の特性(具体的には失敗メッセージ)についてアサーションを行う必要があります。

def _failure_testing_test_impl(ctx):
    env = analysistest.begin(ctx)
    asserts.expect_failure(env, "This rule should never work")
    return analysistest.end(env)

また、テスト対象のターゲットに「手動」のタグが設定されていることも確認してください。これを行わないと、:all を使用してパッケージ内のすべてのターゲットをビルドすると、意図的に障害が発生したターゲットのビルドが発生し、ビルドエラーが発生します。「手動」では、テスト対象は、明示的に指定された場合、または手動以外のターゲットの依存関係(テストルールなど)としてのみビルドされます。

def _test_failure():
    myrule(name = "this_should_fail", tags = ["manual"])

    failure_testing_test(name = "failure_testing_test",
                         target_under_test = ":this_should_fail")

# Then call _test_failure() in the macro which generates the test suite and add
# ":failure_testing_test" to the suite's test targets.

登録済みのアクションを確認する

たとえば、ctx.actions.run() を使用して、ルールが登録されているアクションをアサーションを行うテストを作成できます。これは、分析テストルールの実装関数で行うことができます。次に例を示します。

def _inspect_actions_test_impl(ctx):
    env = analysistest.begin(ctx)

    target_under_test = analysistest.target_under_test(env)
    actions = analysistest.target_actions(env)
    asserts.equals(env, 1, len(actions))
    action_output = actions[0].outputs.to_list()[0]
    asserts.equals(
        env, target_under_test.label.name + ".out", action_output.basename)
    return analysistest.end(env)

analysistest.target_actions(env) は、テスト対象のターゲットによって登録されたアクションを表す Action オブジェクトのリストを返します。

さまざまなフラグに基づくルールの動作の確認

特定のビルドフラグを指定して、実際のルールが特定の動作をするかどうかを確認できます。たとえば、ユーザーが次の設定を行った場合、ルールの動作が変わる可能性があります。

bazel build //mypkg:real_target -c opt

bazel build //mypkg:real_target -c dbg

これを行うには、目的のビルドフラグを使用してテスト対象をテストします。

bazel test //mypkg:myrules_test -c opt

ただし、テストスイートに -c opt でルールの動作を確認するテストと、-c dbg でルールの動作を確認する別のテストを同時に含めることはできません。両方のテストを同じビルドで実行することはできません。

この問題は、テストルールを定義する際に、目的のビルドフラグを指定することで解決できます。

myrule_c_opt_test = analysistest.make(
    _myrule_c_opt_test_impl,
    config_settings = {
        "//command_line_option:compilation_mode": "opt",
    },
)

通常、現在のビルドフラグを考慮して、テスト対象のターゲットが分析されます。config_settings を指定すると、指定したコマンドライン オプションの値がオーバーライドされます。(指定されていないオプションは、実際のコマンドラインから値を保持します)。

上述のように、config_settings 辞書では、コマンドライン フラグの前に特別なプレースホルダ値 //command_line_option: を付ける必要があります。

アーティファクトの検証

生成されたファイルが正しいかどうかを確認するには、主に次の方法があります。

  • シェル、Python、またはその他の言語でテスト スクリプトを作成し、適切な *_test ルールタイプのターゲットを作成できます。

  • 実行するテストの種類に応じて、専用のルールを使用できます。

テスト ターゲットの使用

アーティファクトを検証する最も簡単な方法は、スクリプトを記述して、*_test ターゲットを BUILD ファイルに追加することです。確認する特定のアーティファクトは、このターゲットのデータ依存関係である必要があります。検証ロジックが複数のテストで再利用可能な場合、テスト ターゲットの args 属性で制御されるコマンドライン引数を取るスクリプトである必要があります。上の例では、myrule の出力が "abc" であることを検証します。

//mypkg/myrule_validator.sh:

if [ "$(cat $1)" = "abc" ]; then
  echo "Passed"
  exit 0
else
  echo "Failed"
  exit 1
fi

//mypkg/BUILD:

...

myrule(
    name = "mytarget",
)

...

# Needed for each target whose artifacts are to be checked.
sh_test(
    name = "validate_mytarget",
    srcs = [":myrule_validator.sh"],
    args = ["$(location :mytarget.out)"],
    data = [":mytarget.out"],
)

カスタムルールの使用

さらに複雑な方法として、シェル スクリプトをテンプレートとして作成し、新しいルールでインスタンス化することもできます。これには間接化と Starlark ロジックがより多く含まれますが、BUILD ファイルがよりクリーンになります。副作用として、任意の引数の前処理は、スクリプトではなく Starlark で実行できます。スクリプトは、(引数に)数値のプレースホルダではなくシンボリック プレースホルダを使用するため、やや自己文書化が進んでいます。

//mypkg/myrule_validator.sh.template:

if [ "$(cat %TARGET%)" = "abc" ]; then
  echo "Passed"
  exit 0
else
  echo "Failed"
  exit 1
fi

//mypkg/myrule_validation.bzl:

def _myrule_validation_test_impl(ctx):
  """Rule for instantiating myrule_validator.sh.template for a given target."""
  exe = ctx.outputs.executable
  target = ctx.file.target
  ctx.actions.expand_template(output = exe,
                              template = ctx.file._script,
                              is_executable = True,
                              substitutions = {
                                "%TARGET%": target.short_path,
                              })
  # This is needed to make sure the output file of myrule is visible to the
  # resulting instantiated script.
  return [DefaultInfo(runfiles=ctx.runfiles(files=[target]))]

myrule_validation_test = rule(
    implementation = _myrule_validation_test_impl,
    attrs = {"target": attr.label(allow_single_file=True),
             # You need an implicit dependency in order to access the template.
             # A target could potentially override this attribute to modify
             # the test logic.
             "_script": attr.label(allow_single_file=True,
                                   default=Label("//mypkg:myrule_validator"))},
    test = True,
)

//mypkg/BUILD:

...

myrule(
    name = "mytarget",
)

...

# Needed just once, to expose the template. Could have also used export_files(),
# and made the _script attribute set allow_files=True.
filegroup(
    name = "myrule_validator",
    srcs = [":myrule_validator.sh.template"],
)

# Needed for each target whose artifacts are to be checked. Notice that you no
# longer have to specify the output file name in a data attribute, or its
# $(location) expansion in an args attribute, or the label for the script
# (unless you want to override it).
myrule_validation_test(
    name = "validate_mytarget",
    target = ":mytarget",
)

または、テンプレート展開アクションを使用する代わりに、テンプレートを .bzl ファイルに文字列としてインライン化し、分析フェーズで str.format メソッドまたは % 形式を使用して拡張することもできます。

Starlark ユーティリティのテスト

Skylibunittest.bzl フレームワークは、ユーティリティ関数(つまり、マクロとルール実装のいずれでもない関数)のテストに使用できます。unittest.bzlanalysistest ライブラリを使用する代わりに、unittest を使用できます。このようなテストスイートの場合、コンビニエンス関数 unittest.suite() を使用してボイラープレートを縮小できます。

//mypkg/myhelpers.bzl:

def myhelper():
    return "abc"

//mypkg/myhelpers_test.bzl:

load("@bazel_skylib//lib:unittest.bzl", "asserts", "unittest")
load(":myhelpers.bzl", "myhelper")

def _myhelper_test_impl(ctx):
  env = unittest.begin(ctx)
  asserts.equals(env, "abc", myhelper())
  return unittest.end(env)

myhelper_test = unittest.make(_myhelper_test_impl)

# No need for a test_myhelper() setup function.

def myhelpers_test_suite(name):
  # unittest.suite() takes care of instantiating the testing rules and creating
  # a test_suite.
  unittest.suite(
    name,
    myhelper_test,
    # ...
  )

//mypkg/BUILD:

load(":myhelpers_test.bzl", "myhelpers_test_suite")

myhelpers_test_suite(name = "myhelpers_tests")

その他の例については、Skylib 独自のテストをご覧ください。