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

Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.
Báo cáo sự cố Xem nguồn

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

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

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 các báo cáo lcov, hiện là tuyến đường được hỗ trợ tốt nhất.

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

Chuẩn bị

Quy trình cơ bản để tạo báo cáo mức độ phù hợp bao gồm:

  • Một kho lưu trữ cơ bản có các mục tiêu kiểm thử
  • Chuỗi công cụ có cài đặt các công cụ hỗ trợ mã theo ngôn ngữ
  • Cấu hình "công cụ" chính xác

Hai quy tắc trước là theo ngôn ngữ cụ thể và chủ yếu là đơn giản, tuy nhiên quy tắc sau có thể khó khăn hơn cho các dự án phức tạp.

"Quy trình đo lường" trong trường hợp này là các công cụ xác định mức độ phù hợp được sử 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 tập hợp con 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 khả năng đo lường cho các hoạt động kiểm thử, bạn cần gắn cờ --instrument_test_targets.

Theo mặc định, bazel sẽ cố gắng khớp với(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 chạy

Để tạo báo cáo về phạm vi bao phủ, hãy dùng bazel coverage --combined_report=lcov [target]. Thao tác này sẽ chạy các quy trình kiểm thử cho mục tiêu, tạo báo cáo 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 hành động thu thập tất cả các tệp che phủ được tạo và hợp nhất các tệp này thành một tệp. Sau đó, các tệp này sẽ được tạo trong $(bazel info output_path)/_coverage/_coverage_report.dat.

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

Phạm vi xem

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

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

Lưu ý rằng genhtml cũng đọc mã nguồn để chú thích nếu không có phù hợp trong các tệp này. Để hoạt động này, genhtml dự kiến sẽ được thực thi trong thư mục 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 trên trình duyệt web bất kỳ.

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

Thực thi từ xa

Hiện tại, việc chạy bằng phương thức thực thi kiểm thử từ xa có một số lưu ý:

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

Python

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

Việc chạy mức độ phù hợp bằng python có một số điều kiện tiên quyết:

Sử dụng mức độ phù hợp được sửa đổi.py

Bạn có thể thực hiện việc này thông qua rules_python, cho phép sử dụng tệp requirements.txt, sau đó các yêu cầu được liệt kê trong tệp được tạo dưới dạng mục tiêu bazel bằng cách sử dụng quy tắc 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 sử dụng tệp rules_python, pip_installrequirements.txt trong tệp WORKSPACE dưới dạng:

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ầucover.py bằng cách đặt các mục 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 chuỗi công cụ Python khép kín, thay vì thêm phần phụ thuộc vào mỗi mục tiêu py_test, bạn có thể thêm công cụ quản lý phạm vi 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, bạn không thể dùng quy tắc này để tìm nạp mô-đun coverage. Thay vào đó, hãy thêm WORKSPACE của bạn (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, ví dụ:

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