การครอบคลุมของโค้ดด้วย Bazel

Bazel มีคำสั่งย่อย coverage เพื่อสร้างรายงานความครอบคลุมของโค้ด ในที่เก็บข้อมูลที่ทดสอบได้ด้วย bazel coverage เนื่องจากระบบนิเวศของภาษาต่างๆ มีลักษณะเฉพาะตัว จึงอาจไม่ใช่เรื่องง่ายเสมอไปที่จะทำให้การทดสอบนี้ใช้งานได้กับโปรเจ็กต์ที่กำหนด

หน้านี้จะอธิบายกระบวนการทั่วไปในการสร้างและดูรายงานความครอบคลุม รวมถึงมีหมายเหตุเฉพาะภาษาสำหรับภาษาที่มีการกำหนดค่าที่ทราบกันดี คุณควรอ่านส่วนทั่วไปก่อน แล้วจึงอ่านเกี่ยวกับข้อกำหนดของภาษาที่ต้องการ นอกจากนี้ โปรดดูส่วนการดำเนินการระยะไกล ซึ่งต้องพิจารณาเพิ่มเติม

แม้ว่าคุณจะปรับแต่งได้หลายอย่าง แต่เอกสารนี้จะเน้นที่การสร้างและใช้ lcovรายงาน ซึ่งเป็นวิธีที่ได้รับการสนับสนุนมากที่สุดในปัจจุบัน

การสร้างรายงานความครอบคลุม

การเตรียมพร้อม

เวิร์กโฟลว์พื้นฐานสำหรับการสร้างรายงานความครอบคลุมต้องมีสิ่งต่อไปนี้

• ที่เก็บข้อมูลพื้นฐานที่มีเป้าหมายการทดสอบ
• ชุดเครื่องมือที่มีการติดตั้งเครื่องมือความครอบคลุมของโค้ดเฉพาะภาษา
• การกำหนดค่า "การวัดประสิทธิภาพ" ที่ถูกต้อง

2 ข้อแรกเป็นแบบเฉพาะภาษาและค่อนข้างตรงไปตรงมา แต่ข้อสุดท้ายอาจยากกว่าสำหรับโปรเจ็กต์ที่ซับซ้อน

"การวัดประสิทธิภาพ" ในที่นี้หมายถึงเครื่องมือความครอบคลุมที่ใช้สำหรับเป้าหมายที่เฉพาะเจาะจง 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

หากต้องการดูผลลัพธ์ เพียงเปิดไฟล์ index.html ที่สร้างขึ้นในไดเรกทอรี genhtml ในเว็บเบราว์เซอร์ใดก็ได้

หากต้องการความช่วยเหลือและข้อมูลเพิ่มเติมเกี่ยวกับเครื่องมือ genhtml หรือรูปแบบความครอบคลุม lcov โปรดดู โปรเจ็กต์ lcov

การดำเนินการระยะไกล

การเรียกใช้การดำเนินการทดสอบระยะไกลในปัจจุบันมีข้อควรระวังบางประการดังนี้

• การดำเนินการรวมรายงานยังไม่สามารถเรียกใช้จากระยะไกลได้ เนื่องจาก Bazel ไม่ถือว่าไฟล์เอาต์พุตความครอบคลุมเป็นส่วนหนึ่งของกราฟ (ดูปัญหาข้อนี้) จึงไม่สามารถจัดการไฟล์เหล่านี้เป็นอินพุตสำหรับการดำเนินการรวมได้อย่างถูกต้อง หากต้องการหลีกเลี่ยงปัญหานี้ ให้ใช้ --strategy=CoverageReport=local
  • หมายเหตุ: คุณอาจต้องระบุค่า เช่น --strategy=CoverageReport=local,remote แทน หากตั้งค่า Bazel ให้ลองใช้ local,remote เนื่องจากวิธีที่ Bazel แก้ไขกลยุทธ์
• คุณไม่สามารถใช้ --remote_download_minimal และแฟล็กที่คล้ายกันได้เช่นกันเนื่องจากข้อจำกัดก่อนหน้านี้
• ปัจจุบัน Bazel จะสร้างข้อมูลความครอบคลุมไม่สำเร็จหากมีการแคชการทดสอบไว้ก่อนหน้านี้ หากต้องการหลีกเลี่ยงปัญหานี้ คุณสามารถตั้งค่า --nocache_test_results สำหรับการเรียกใช้ความครอบคลุมโดยเฉพาะได้ แม้ว่าวิธีนี้จะทำให้เวลาในการทดสอบเพิ่มขึ้นอย่างมากก็ตาม
• --experimental_split_coverage_postprocessing และ --experimental_fetch_all_coverage_outputs
  • โดยปกติแล้ว ความครอบคลุมจะเรียกใช้เป็นส่วนหนึ่งของการดำเนินการทดสอบ ดังนั้นโดยค่าเริ่มต้น เราจึงไม่ได้รับความครอบคลุมทั้งหมดกลับมาเป็นเอาต์พุตของการดำเนินการระยะไกล แฟล็กเหล่านี้จะลบล้างค่าเริ่มต้นและรับข้อมูลความครอบคลุม ดูรายละเอียดเพิ่มเติมได้ในปัญหาข้อนี้

การกำหนดค่าเฉพาะภาษา

Java

Java ควรทำงานได้ทันทีด้วยการกำหนดค่าเริ่มต้น ชุดเครื่องมือ Bazel มีทุกสิ่งที่จำเป็นสำหรับการดำเนินการ ระยะไกล รวมถึง JUnit

Python

ข้อกำหนดเบื้องต้น

การเรียกใช้ความครอบคลุมด้วย Python มีข้อกำหนดเบื้องต้นดังนี้

• ไบนารี Bazel ที่มี b01c859, ซึ่งควรเป็น Bazel เวอร์ชัน >3.0
• coverage.py เวอร์ชันที่แก้ไขแล้ว

การใช้ coverage.py ที่แก้ไขแล้ว

วิธีหนึ่งในการดำเนินการนี้คือใช้ rules_python ซึ่งช่วยให้คุณใช้ไฟล์ requirements.txt ได้ จากนั้นระบบจะสร้างข้อกำหนดที่ระบุไว้ในไฟล์เป็นเป้าหมาย Bazel โดยใช้กฎที่เก็บข้อมูล pip_install

requirements.txt ควรมีรายการต่อไปนี้

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

จากนั้นใช้ rules_python, pip_install และไฟล์ requirements.txt ในไฟล์ WORKSPACE ดังนี้

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

จากนั้นเป้าหมายการทดสอบจะใช้ข้อกำหนด coverage.py ได้โดยตั้งค่าต่อไปนี้ในไฟล์ 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",
    ],
)

หากคุณใช้ชุดเครื่องมือ Python แบบ Hermetic แทนที่จะเพิ่มการขึ้นต่อกันของความครอบคลุมลงในเป้าหมาย 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",
)