Mức độ sử dụng mã với Bazel

Báo cáo vấn đề Xem nguồn Nightly · 8.4 · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

Bazel có một lệnh con coverage để tạo báo cáo về mức độ phù hợp của mã trên các kho lưu trữ có thể được kiểm thử bằng bazel coverage. Do đặc thù của nhiều hệ sinh thái ngôn ngữ, nên việc thực hiện điều này cho một dự án nhất định không phải lúc nào cũng đơn giản.

Trang này ghi lại quy trình chung để tạo và xem báo cáo về mức độ phù hợp, đồng thời cũng có một số ghi chú dành riêng cho ngôn ngữ đối với những ngôn ngữ có cấu hình đã biết. Bạn nên đọc phần chung trước, sau đó đọc về các yêu cầu đối với một ngôn ngữ cụ thể. Ngoài ra, hãy lưu ý đến phần thực thi từ xa. Phần này yêu cầu bạn phải cân nhắc thêm một số yếu tố.

Mặc dù có thể tuỳ chỉnh nhiều, nhưng tài liệu này tập trung vào việc tạo và sử dụng báo cáo lcov. Đây hiện là cách được hỗ trợ tốt nhất.

Tạo báo cáo về mức độ phù hợp

Chuẩn bị

Quy trình làm việc cơ bản để tạo báo cáo về mức độ phù hợp yêu cầu những điều sau:

  • Kho lưu trữ cơ bản có các mục tiêu kiểm thử
  • Một chuỗi công cụ đã cài đặt các công cụ đo lường mức độ phù hợp của mã theo ngôn ngữ cụ thể
  • Cấu hình "đo lường" chính xác

Hai loại đầu tiên là dành riêng cho ngôn ngữ và hầu hết đều đơn giản, tuy nhiên, loại thứ ba có thể khó hơn đối với các dự án phức tạp.

Trong trường hợp này, "đo lường" đề cập đến các công cụ đo lường được dùng cho một mục tiêu cụ thể. Bazel cho phép bật tính năng này cho một nhóm nhỏ tệp cụ thể bằng cách sử dụng cờ --instrumentation_filter. Cờ này chỉ định một bộ lọc cho các mục tiêu được kiểm thử khi bật tính năng đo lường. Để bật tính năng đo lường cho các kiểm thử, bạn cần có cờ --instrument_test_targets.

Theo mặc định, bazel sẽ cố gắng so khớp(các) gói mục tiêu và in bộ lọc có liên quan dưới dạng thông báo INFO.

Phạm vi bao phủ khi chạy

Để tạo báo cáo phạm vi lập chỉ mục, hãy sử dụng bazel coverage --combined_report=lcov [target]. Thao tác này sẽ chạy các kiểm thử cho mục tiêu, tạo báo cáo về mức độ phù hợp ở định dạng lcov cho từng tệp.

Sau khi hoàn tất, bazel sẽ chạy một thao tác thu thập tất cả các tệp mức độ phù hợp đã tạo và hợp nhất các tệp đó thành một tệp. Sau đó, tệp này sẽ được tạo trong $(bazel info output_path)/_coverage/_coverage_report.dat.

Báo cáo về mức độ phù hợp cũng được tạo nếu các kiểm thử không đạt, mặc dù lưu ý rằng điều này không áp dụng cho các kiểm thử không đạt – chỉ các kiểm thử đạt mới được báo cáo.

Xem tin tức

Báo cáo mức độ phù hợp chỉ được xuất ở định dạng lcov không đọc được. Từ đó, chúng ta có thể sử dụng tiện ích genhtml (thuộc dự án lcov) để tạo báo cáo có thể xem trong trình duyệt web:

genhtml --output genhtml "$(bazel info output_path)/_coverage/_coverage_report.dat"

Xin lưu ý rằng genhtml cũng đọc mã nguồn để chú thích phần thiếu hụt trong các tệp này. Để điều này hoạt động, bạn cần thực thi genhtml ở gốc của dự án bazel.

Để xem kết quả, bạn chỉ cần mở tệp index.html được tạo trong thư mục genhtml bằng bất kỳ trình duyệt web nào.

Để được trợ giúp và biết thêm thông tin về công cụ genhtml hoặc định dạng phạm vi lcov, hãy xem dự án lcov.

Thực thi từ xa

Việc chạy với tính năng thực thi kiểm thử từ xa hiện có một số điểm hạn chế:

  • Hành động kết hợp báo cáo hiện chưa thể chạy từ xa. Điều này là do Bazel không coi các tệp đầu ra về mức độ phù hợp là một phần của biểu đồ (xem vấn đề này), do đó, không thể coi các tệp này là dữ liệu đầu vào cho thao tác kết hợp một cách chính xác. Để giải quyết vấn đề này, hãy sử dụng --strategy=CoverageReport=local.
    • Lưu ý: Bạn có thể cần chỉ định một nội dung nào đó như --strategy=CoverageReport=local,remote thay vào đó, nếu Bazel được thiết lập để thử local,remote, do cách Bazel phân giải các chiến lược.
  • --remote_download_minimal và các cờ tương tự cũng không thể được dùng do hậu quả của cờ trước.
  • Bazel hiện sẽ không tạo được thông tin về mức độ phù hợp nếu các kiểm thử đã được lưu vào bộ nhớ đệm trước đó. Để giải quyết vấn đề này, bạn có thể đặt --nocache_test_results một cách cụ thể cho các lần chạy phạm vi, mặc dù điều này tất nhiên sẽ tốn nhiều thời gian kiểm thử.
  • --experimental_split_coverage_postprocessing và --experimental_fetch_all_coverage_outputs
    • Thông thường, mức độ phù hợp được chạy như một phần của thao tác kiểm thử, do đó, theo mặc định, chúng ta không nhận được tất cả mức độ phù hợp dưới dạng đầu ra của quá trình thực thi từ xa theo mặc định. Các cờ này sẽ ghi đè giá trị mặc định và lấy dữ liệu về mức độ phù hợp. Hãy xem vấn đề này để biết thêm thông tin chi tiết.

Cấu hình theo ngôn ngữ cụ thể

Java

Java sẽ hoạt động ngay khi xuất xưởng với cấu hình mặc định. Chuỗi công cụ bazel chứa mọi thứ cần thiết cho quá trình thực thi từ xa, cũng như JUnit.

Python

Điều kiện tiên quyết

Để chạy mức độ sử dụng bằng Python, bạn cần đáp ứng một số điều kiện tiên quyết:

Sử dụng coverage.py đã sửa đổi

Một cách để thực hiện việc này là thông qua rules_python. Cách này cho phép bạn sử dụng tệp requirements.txt. Sau đó, các yêu cầu được liệt kê trong tệp sẽ được tạo dưới dạng mục tiêu bazel bằng cách sử dụng quy tắc kho lưu trữ pip_install.

requirements.txt phải có mục nhập sau:

git+https://github.com/ulfjack/coveragepy.git@lcov-support

Sau đó, bạn nên dùng tệp rules_python, pip_install và requirements.txt trong tệp WORKSPACE như sau:

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")

http_archive(
    name = "rules_python",
    url = "https://github.com/bazelbuild/rules_python/releases/download/0.5.0/rules_python-0.5.0.tar.gz",
    sha256 = "cd6730ed53a002c56ce4e2f396ba3b3be262fd7cb68339f0377a45e8227fe332",
)

load("@rules_python//python:pip.bzl", "pip_install")

pip_install(
   name = "python_deps",
   requirements = "//:requirements.txt",
)

Sau đó, các mục tiêu kiểm thử có thể sử dụng yêu cầu coverage.py bằng cách thiết lập nội dung sau trong tệp BUILD:

load("@python_deps//:requirements.bzl", "entry_point")

alias(
    name = "python_coverage_tools",
    actual = entry_point("coverage"),
)

py_test(
    name = "test",
    srcs = ["test.py"],
    env = {
        "PYTHON_COVERAGE": "$(location :python_coverage_tools)",
    },
    deps = [
        ":main",
        ":python_coverage_tools",
    ],
)

Nếu đang sử dụng một chuỗi công cụ Python khép kín, thay vì thêm phần phụ thuộc về mức độ phù hợp vào mọi mục tiêu py_test, bạn có thể thêm công cụ mức độ phù hợp vào cấu hình chuỗi công cụ.

Vì quy tắc pip_install phụ thuộc vào chuỗi công cụ Python, nên quy tắc này không thể dùng để tìm nạp mô-đun coverage. Thay vào đó, hãy thêm WORKSPACE, ví dụ:

http_archive(
    name = "coverage_linux_x86_64"",
    build_file_content = """
py_library(
    name = "coverage",
    srcs = ["coverage/__main__.py"],
    data = glob(["coverage/*", "coverage/**/*.py"]),
    visibility = ["//visibility:public"],
)
""",
    sha256 = "84631e81dd053e8a0d4967cedab6db94345f1c36107c71698f746cb2636c63e3",
    type = "zip",
    urls = [
        "https://files.pythonhosted.org/packages/74/0d/0f3c522312fd27c32e1abe2fb5c323b583a5c108daf2c26d6e8dfdd5a105/coverage-6.4.1-cp39-cp39-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
    ],
)

Sau đó, hãy định cấu hình chuỗi công cụ Python của bạn, chẳng hạn như

py_runtime(
    name = "py3_runtime_linux_x86_64",
    coverage_tool = "@coverage_linux_x86_64//:coverage",
    files = ["@python3_9_x86_64-unknown-linux-gnu//:files"],
    interpreter = "@python3_9_x86_64-unknown-linux-gnu//:bin/python3",
    python_version = "PY3",
)

py_runtime_pair(
    name = "python_runtimes_linux_x86_64",
    py2_runtime = None,
    py3_runtime = ":py3_runtime_linux_x86_64",
)

toolchain(
    name = "python_toolchain_linux_x86_64",
    exec_compatible_with = [
        "@platforms//os:linux",
        "@platforms//cpu:x86_64",
    ],
    toolchain = ":python_runtimes_linux_x86_64",
    toolchain_type = "@bazel_tools//tools/python:toolchain_type",
)