測試

回報問題 查看原始碼 Nightly · 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

在 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() 陳述式之外,檔案還有兩個主要部分:

  • 測試本身,每個測試都包含 1) 用於測試規則的分析時間實作函式、2) 透過 analysistest.make() 宣告測試規則,以及 3) 用於宣告測試規則 (及其依附元件) 和測試規則的載入時間函式 (巨集)。如果斷言在測試案例之間沒有變更,1) 和 2) 可能會由多個測試案例共用。

  • 這個測試套件函式會呼叫每項測試的載入時間函式,並宣告 test_suite 目標,將所有測試組合在一起。

為求一致性,請遵循建議的命名慣例:讓 foo 代表測試名稱的部分,說明測試檢查的內容 (上例中的 provider_contents)。例如,JUnit 測試方法會命名為 testFoo

然後執行下列步驟:

  • 產生測試和測試目標的巨集應命名為 _test_foo (_test_provider_contents)

  • 其測試規則類型應命名為 foo_test (provider_contents_test)

  • 此規則類型的目標標籤應為 foo_test (provider_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:,如上圖所示。

驗證構件

檢查產生的檔案是否正確的主要方法如下:

  • 您可以使用 Shell、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"],
)

使用自訂規則

另一種較複雜的做法是將 Shell 指令碼當作範本編寫,讓新規則將其例項化。這會涉及更多間接和 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,而非 unittest.bzlanalysistest 程式庫。針對這類測試套件,便利函式 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 本身的測試