使用 Bazel 实现代码覆盖率

报告问题 查看源代码 每夜 build · 8.0 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

Bazel 提供了 coverage 子命令，用于针对可通过 bazel coverage 进行测试的代码库生成代码覆盖率报告。由于各种语言生态系统的特性，使其适用于给定项目并不总是一件容易的事。

本页介绍了创建和查看覆盖率报告的一般流程，还针对配置已知的语言提供了一些特定于语言的备注。建议您先阅读“常规”部分，然后再阅读特定语言的要求。另请注意“远程执行”部分，其中需要考虑一些额外事项。

虽然可以进行大量自定义，但本文档重点介绍生成和使用 lcov 报告，这是目前最受支持的方式。

创建覆盖率报告

准备工作

创建覆盖率报告的基本工作流程需要满足以下条件：

  • 包含测试目标的基本代码库
  • 安装了特定于语言的代码覆盖率工具的工具链
  • 正确的“插桩”配置

前两种方法因语言而异，并且大多很简单，但对于复杂的项目，后一种方法可能更难。

在本例中，“插桩”是指用于特定目标的覆盖率工具。Bazel 允许使用 --instrumentation_filter 标志为特定文件子集启用此功能，该标志用于为启用了插桩功能的目标指定过滤条件。如需为测试启用插桩，必须使用 --instrument_test_targets 标志。

默认情况下，bazel 会尝试匹配目标软件包，并将相关过滤条件作为 INFO 消息输出。

运行覆盖率

如需生成覆盖率报告，请使用 bazel coverage --combined_report=lcov [target]。这会为目标运行测试，并为每个文件生成 lcov 格式的覆盖率报告。

完成后，bazel 会运行一个操作来收集所有生成的覆盖率文件，并将它们合并为一个文件，该文件最终会在 $(bazel info output_path)/_coverage/_coverage_report.dat 下创建。

如果测试失败，系统也会生成覆盖率报告，但请注意，这不适用于失败的测试，系统只会报告通过的测试。

查看报道

覆盖率报告仅以不可读取的 lcov 格式输出。因此，我们可以使用 genhtml 实用程序（lcov 项目的一部分）生成可在网络浏览器中查看的报告：

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

请注意，genhtml 还会读取源代码，以注释这些文件中缺少的覆盖率。为此，genhtml 应在 bazel 项目的根目录中执行。

如需查看结果，只需在任意网络浏览器中打开 genhtml 目录中生成的 index.html 文件即可。

如需有关 genhtml 工具或 lcov 覆盖率格式的进一步帮助和信息，请参阅 lcov 项目。

远程执行

使用远程测试作业运行目前存在一些注意事项：

  • 报告组合操作尚无法远程运行。这是因为 Bazel 不会将覆盖率输出文件视为其图的一部分（请参阅此问题），因此无法正确将其视为组合操作的输入。如需解决此问题，请使用 --strategy=CoverageReport=local。
    • 注意：由于 Bazel 解析策略的方式，如果 Bazel 设置为尝试 local,remote，则可能需要改为指定 --strategy=CoverageReport=local,remote 之类的值。
  • 由于前者，也无法使用 --remote_download_minimal 和类似标志。
  • 如果测试之前已缓存，Bazel 目前将无法创建覆盖率信息。为解决此问题，可以专门针对覆盖率运行设置 --nocache_test_results，但这当然会在测试时间方面造成巨大开销。
  • --experimental_split_coverage_postprocessing 和 --experimental_fetch_all_coverage_outputs
    • 通常，代码覆盖率是作为测试操作的一部分运行的，因此默认情况下，我们不会将所有代码覆盖率作为远程执行的输出返回。这些标志会替换默认标志并获取覆盖率数据。如需了解详情，请参阅此问题。

特定于语言的配置

Java

Java 应在默认配置下开箱即用。bazel 工具链包含远程执行所需的所有内容，包括 JUnit。

Python

前提条件

使用 Python 运行覆盖率需要满足一些前提条件：

使用修改后的 coverage.py

实现此目的的方法之一是使用 rules_python，这让您能够使用 requirements.txt 文件，然后使用 pip_install 代码库规则将文件中列出的要求创建为 bazel 目标。

requirements.txt 应包含以下条目：

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

然后，应在 WORKSPACE 文件中使用 rules_python、pip_install 和 requirements.txt 文件，如下所示：

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

然后，您可以在 BUILD 文件中设置以下内容，以便测试目标使用 coverage.py 要求：

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

如果您使用的是密封型 Python 工具链，则可以将覆盖率工具添加到工具链配置中，而不是将覆盖率依赖项添加到每个 py_test 目标。

由于 pip_install 规则依赖于 Python 工具链，因此无法用于提取 coverage 模块。请改为添加 WORKSPACE，例如：

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

然后，配置您的 Python 工具链，例如：

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