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

Báo cáo vấn đề Xem nguồn Nightly · 7.4 .

Bazel có một lệnh phụ coverage để tạo báo cáo mức độ sử dụng 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ữ, việc làm cho tính năng này hoạt động cho một dự án cụ thể 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 mức độ sử dụng, đồng thời cung cấp 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 phổ biến. Tốt nhất là 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 ý rằng phần thực thi từ xa yêu cầu một số điểm cần cân nhắc khác.

Mặc dù có thể tuỳ chỉnh rất 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 (hiện là tuyến được hỗ trợ nhiều nhất).

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

Chuẩn bị

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

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

2 phần tử trước đều theo ngôn ngữ cụ thể và gần như đơn giản, tuy nhiên, phần sau có thể khó hơn đối với các dự án phức tạp.

"Đo lường" trong trường hợp này là các công cụ về mức độ sử dụ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 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 kiểm thử, bạn cần phải có cờ --instrument_test_targets.

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

Mức độ phù hợp đang chạy

Để tạo báo cáo về mức độ phù hợp, hãy sử dụng bazel coverage --combined_report=lcov [target]. Thao tác này sẽ chạy các lượt kiểm thử cho mục tiêu, tạo báo cáo về mức độ sử dụng ở đị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 độ sử dụng được 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 độ sử dụng cũng được tạo nếu kiểm thử không thành công, mặc dù lưu ý rằng tình trạng này không bao gồm các lượt kiểm thử không thành công mà chỉ báo cáo các lượt kiểm thử đạt.

Phạm vi xem

Báo cáo mức độ sử dụng chỉ 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 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 sẽ đọc mã nguồn để chú thích mức độ phù hợp bị thiếu trong các tệp này. Để làm được điều này, theo dự kiến, genhtml 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 trong bất kỳ trình duyệt web nào.

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

Thực thi từ xa

Hiện tại, quá trình chạy bằng quy trình thực thi kiểm thử từ xa có một số lưu ý sau:

  • Hành động kết hợp báo cáo chưa thể chạy từ xa. Lý do là Bazel không coi các tệp đầu ra về mức độ sử dụng 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 chính xác cho thao tác kết hợp. Để 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 giá trị như --strategy=CoverageReport=local,remote, 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.
  • Bạn cũng không thể sử dụng --remote_download_minimal và các cờ tương tự do trạng thái cũ.
  • Hiện tại, Bazel sẽ không tạo được thông tin về mức độ sử dụng nếu các hoạt động 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ể thiết lập riêng --nocache_test_results cho các lần chạy mức độ sử dụng, mặc dù tất nhiên phương thức này sẽ làm phát sinh chi phí cao về thời gian kiểm thử.
  • --experimental_split_coverage_postprocessing và --experimental_fetch_all_coverage_outputs
    • Thông thường, mức độ sử dụng đượ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 ta không lấy lại toàn bộ mức độ sử dụng dưới dạng kết quả của quá trình thực thi từ xa. Những cờ này ghi đè giá trị mặc định và lấy dữ liệu về mức độ sử dụng. 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 chứa mọi thứ cần thiết cho quá trình 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 độ sử dụng bằng python có 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 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 sau:

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

Sau đó, bạn nên sử 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 đặt 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 chuỗi công cụ Python kín, thay vì thêm phần phụ thuộc phạm vi sử dụng vào mọi mục tiêu py_test, bạn có thể thêm công cụ phạm vi sử dụng 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 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, 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 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",
)