Kiểm thử

Báo cáo vấn đề Xem nguồn Nightly/3}

Có một số phương pháp kiểm thử mã Starlark trong Bazel. Trang này thu thập các khung và phương pháp hay nhất hiện tại theo trường hợp sử dụng.

Kiểm thử quy tắc

Skylib có một khung kiểm thử tên là unittest.bzl để kiểm tra hành vi tại thời điểm phân tích của các quy tắc, chẳng hạn như thao tác và trình cung cấp của các quy tắc đó. Những loại hình kiểm thử đó được gọi là "kiểm thử phân tích" và hiện là cách tốt nhất để kiểm thử hoạt động bên trong của các quy tắc.

Một số điều cần lưu ý:

• Xác nhận kiểm thử xuất hiện trong bản dựng, không phải trong một quy trình chạy kiểm thử riêng biệt. Mục tiêu do chương trình kiểm thử tạo phải được đặt tên sao cho không va chạm với các mục tiêu trong bài kiểm thử khác hoặc từ bản dựng. Bazel xem một lỗi xảy ra trong quá trình kiểm thử là lỗi bản dựng chứ không phải là lỗi kiểm thử.

• Cần có một lượng lớn các mã nguyên mẫu để thiết lập các quy tắc kiểm thử và các quy tắc chứa câu nhận định kiểm thử. thoạt đầu, mã nguyên mẫu này có vẻ sẽ gây trở ngại. Điều này giúp lưu ý rằng macro được đánh giá và mục tiêu được tạo trong giai đoạn tải, trong khi các hàm triển khai quy tắc chỉ chạy trong giai đoạn phân tích.

• Thử nghiệm phân tích có quy mô tương đối nhỏ và gọn nhẹ. Một số tính năng của khung kiểm thử phân tích bị hạn chế để xác minh các mục tiêu có số lượng phần phụ thuộc bắc cầu tối đa (hiện là 500). Điều này là do các hệ quả về hiệu suất khi sử dụng các tính năng này với các kiểm thử lớn hơn.

Nguyên tắc cơ bản là xác định một quy tắc kiểm thử phụ thuộc vào quy tắc kiểm thử dưới mức. Việc này cấp cho quy tắc kiểm thử quyền truy cập vào các nhà cung cấp của quy tắc kiểm thử dưới mức.

Chức năng triển khai của quy tắc kiểm thử tiến hành xác nhận. Nếu có bất kỳ lỗi nào, thì lỗi này không được đưa ra ngay lập tức bằng cách gọi fail() (sẽ kích hoạt lỗi bản dựng tại thời điểm phân tích), mà bằng cách lưu trữ lỗi trong một tập lệnh đã tạo nhưng không thể thực thi tại thời điểm thực thi kiểm thử.

Hãy xem ví dụ tối thiểu về đồ chơi ở bên dưới, tiếp theo là ví dụ kiểm tra các thao tác.

Ví dụ tối giản

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

Bạn có thể chạy chương trình kiểm thử bằng bazel test //mypkg:myrules_test.

Ngoài các câu lệnh load() ban đầu, tệp này có hai phần chính:

• Bản thân các hoạt động kiểm thử, mỗi hoạt động bao gồm 1) hàm triển khai tại thời điểm phân tích cho quy tắc kiểm thử, 2) phần khai báo quy tắc kiểm thử qua analysistest.make() và 3) hàm thời gian tải (macro) để khai báo quy tắc kiểm thử dưới mức (và các phần phụ thuộc) cũng như quy tắc kiểm thử. Nếu câu nhận định không thay đổi giữa các trường hợp kiểm thử, 1) và 2) có thể được chia sẻ trong nhiều trường hợp kiểm thử.

• Hàm bộ kiểm thử gọi các hàm thời gian tải cho mỗi lượt kiểm thử và khai báo một mục tiêu test_suite nhóm tất cả kiểm thử lại với nhau.

Để đảm bảo tính nhất quán, hãy làm theo quy ước đặt tên được đề xuất: Đặt foo là viết tắt của phần tên kiểm thử mô tả nội dung kiểm thử đang kiểm tra (provider_contents trong ví dụ trên). Ví dụ: phương thức kiểm thử JUnit sẽ được đặt tên là testFoo.

Sau đó:

• thì macro tạo hoạt động kiểm thử và mục tiêu đang được kiểm thử phải được đặt tên là _test_foo (_test_provider_contents)

• loại quy tắc kiểm thử của nó sẽ được đặt tên là foo_test (provider_contents_test)

• nhãn của mục tiêu của loại quy tắc này phải là foo_test (provider_contents_test)

• hàm triển khai cho quy tắc kiểm thử phải được đặt tên là _foo_test_impl (_provider_contents_test_impl)

• nhãn của mục tiêu của quy tắc kiểm thử và các phần phụ thuộc của các quy tắc đó phải được thêm tiền tố foo_ (provider_contents_)

Lưu ý rằng nhãn của tất cả mục tiêu có thể xung đột với các nhãn khác trong cùng một gói XÂY DỰNG. Vì vậy, bạn nên sử dụng tên riêng biệt cho kiểm thử.

Không kiểm thử được

Có thể bạn nên xác minh rằng một quy tắc không thành công dựa trên một số thông tin đầu vào nhất định hoặc ở một số trạng thái nhất định. Bạn có thể thực hiện việc này bằng cách sử dụng khung kiểm thử phân tích:

Quy tắc kiểm thử được tạo bằng analysistest.make phải chỉ định expect_failure:

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

Việc triển khai quy tắc kiểm thử phải đưa ra nhận định về bản chất của lỗi đã xảy ra (cụ thể là thông báo lỗi):

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

Ngoài ra, hãy đảm bảo rằng mục tiêu đang được thử nghiệm của bạn được gắn thẻ cụ thể là "thủ công". Nếu không, việc tạo tất cả mục tiêu trong gói bằng :all sẽ dẫn đến việc tạo mục tiêu không cố ý và gây ra lỗi bản dựng. Khi sử dụng giá trị "thủ công", mục tiêu đang được kiểm thử sẽ chỉ tạo khi được chỉ định rõ ràng hoặc dưới dạng phần phụ thuộc của mục tiêu không thủ công (chẳng hạn như quy tắc kiểm thử):

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.

Đang xác minh các thao tác đã đăng ký

Có thể bạn sẽ muốn viết các chương trình kiểm thử đưa ra xác nhận về những hành động mà quy tắc của bạn đăng ký, chẳng hạn như sử dụng ctx.actions.run(). Bạn có thể làm việc này trong chức năng triển khai quy tắc kiểm thử phân tích. Ví dụ:

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)

Lưu ý rằng analysistest.target_actions(env) trả về danh sách các đối tượng Action đại diện cho các hành động được mục tiêu đăng ký đang được kiểm thử.

Xác minh hành vi của quy tắc dưới các cờ khác nhau

Bạn có thể muốn xác minh quy tắc thực của mình hoạt động theo một cách nhất định dựa trên một số cờ bản dựng nhất định. Ví dụ: quy tắc của bạn có thể hoạt động theo cách khác nếu người dùng chỉ định:

bazel build //mypkg:real_target -c opt

so với

bazel build //mypkg:real_target -c dbg

Nhìn chung, bạn có thể thực hiện việc này bằng cách kiểm thử mục tiêu đang được kiểm thử bằng cách sử dụng các cờ bản dựng mong muốn:

bazel test //mypkg:myrules_test -c opt

Nhưng sau đó, bộ kiểm thử của bạn không thể chứa đồng thời một kiểm thử xác minh hành vi của quy tắc trong -c opt và một kiểm thử khác xác minh hành vi của quy tắc trong -c dbg. Cả hai kiểm thử đều không thể chạy trong cùng một bản dựng!

Bạn có thể giải quyết vấn đề này bằng cách chỉ định cờ bản dựng mong muốn khi xác định quy tắc kiểm thử:

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

Thông thường, mục tiêu đang được kiểm thử sẽ được phân tích dựa trên cờ bản dựng hiện tại. Việc chỉ định config_settings sẽ ghi đè giá trị của các tuỳ chọn dòng lệnh đã chỉ định. (Mọi tuỳ chọn chưa được chỉ định sẽ giữ lại giá trị lấy từ dòng lệnh thực tế).

Trong từ điển config_settings đã chỉ định, cờ dòng lệnh phải có tiền tố là một giá trị phần giữ chỗ đặc biệt //command_line_option:, như minh hoạ ở trên.

Xác thực cấu phần phần mềm

Sau đây là một số cách chính để kiểm tra xem tệp đã tạo có chính xác hay không:

• Bạn có thể viết một tập lệnh kiểm thử trong shell, Python hoặc một ngôn ngữ khác và tạo mục tiêu của loại quy tắc *_test thích hợp.

• Bạn có thể sử dụng quy tắc chuyên biệt cho loại thử nghiệm mà mình muốn thực hiện.

Sử dụng mục tiêu thử nghiệm

Cách đơn giản nhất để xác thực cấu phần phần mềm là viết một tập lệnh và thêm mục tiêu *_test vào tệp BUILD. Các cấu phần phần mềm cụ thể mà bạn muốn kiểm tra phải là các phần phụ thuộc dữ liệu của mục tiêu này. Nếu logic xác thực của bạn có thể sử dụng lại cho nhiều kiểm thử, thì đó phải là một tập lệnh nhận các đối số dòng lệnh được kiểm soát bằng thuộc tính args của mục tiêu kiểm thử. Dưới đây là ví dụ xác thực rằng kết quả của myrule ở trên là "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"],
)

Sử dụng quy tắc tuỳ chỉnh

Một cách khác phức tạp hơn là ghi tập lệnh shell dưới dạng mẫu được tạo thực thể bằng quy tắc mới. Việc này liên quan đến nhiều yếu tố gián tiếp và logic Starlark hơn, nhưng sẽ dẫn đến việc xoá các tệp BUILD hơn. Như một lợi ích đi kèm, mọi quá trình xử lý trước đối số đều có thể được thực hiện trong Starlark thay vì tập lệnh và tập lệnh được tự ghi lại nhiều hơn một chút vì tập lệnh này sử dụng phần giữ chỗ biểu tượng (cho phần thay thế) thay vì phần giữ chỗ dạng số (đối với đối số).

//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",
)

Ngoài ra, thay vì sử dụng thao tác mở rộng mẫu, bạn có thể đưa mẫu vào tệp .bzl dưới dạng chuỗi và mở rộng mẫu đó trong giai đoạn phân tích bằng cách sử dụng phương thức str.format hoặc định dạng %.

Kiểm thử tiện ích Starlark

Bạn có thể dùng khung unittest.bzl của Skylib để kiểm thử các hàm hiệu dụng (nghĩa là các hàm không phải là macro hoặc quy tắc triển khai). Thay vì dùng thư viện analysistest của unittest.bzl, bạn có thể dùng unittest. Đối với các bộ kiểm thử như vậy, bạn có thể dùng hàm tiện lợi unittest.suite() để giảm bớt mã nguyên mẫu.

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

Để biết thêm ví dụ, hãy xem các kiểm thử riêng của Skylib.