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

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

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

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

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

การจัดเตรียม

ขั้นตอนพื้นฐานในการสร้างรายงานการครอบคลุมมีดังนี้

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

ปัจจัย 2 ประการต่อไปนี้ใช้ภาษาที่เจาะจงและตรงไปตรงมาเป็นส่วนใหญ่ แม้ว่าวิธีหลังจะยากขึ้นสําหรับโครงการที่ซับซ้อน

"เครื่องมือ" ในกรณีนี้หมายถึงเครื่องมือการครอบคลุมที่ใช้กับเป้าหมายเฉพาะ Bazel อนุญาตให้เปิดการตั้งค่านี้สําหรับไฟล์ชุดย่อยที่เจาะจงโดยใช้แฟล็ก --instrumentation_filter ซึ่งระบุตัวกรองสําหรับเป้าหมายที่ทดสอบด้วยเครื่องมือ เปิดใช้อยู่ หากต้องการเปิดใช้การวัดคุมสําหรับการทดสอบ --instrument_test_targets คุณต้องใช้แฟล็ก

โดยค่าเริ่มต้น bazel จะพยายามจับคู่แพ็กเกจเป้าหมายและพิมพ์ตัวกรองที่เกี่ยวข้องเป็นข้อความ INFO

การครอบคลุมที่ทํางานอยู่

หากต้องการสร้างรายงานการครอบคลุม ให้ใช้ bazel coverage --combined_report=lcov [target] การดําเนินการนี้จะทดสอบเป้าหมายเพื่อสร้างรายงานการครอบคลุมในรูปแบบ Lcov สําหรับแต่ละไฟล์

เมื่อทําเสร็จแล้ว Bazel จะเรียกใช้ไฟล์ที่รวบรวม การผลิตที่ได้ทั้งหมด และนํามารวมเข้าด้วยกันเป็น 1 ไฟล์ ซึ่งสุดท้ายจะสร้างขึ้นใน $(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 ควรทํางานได้ทันทีที่มาพร้อมการกําหนดค่าเริ่มต้น เชนเครื่องมือ จะมีข้อมูลทุกอย่างที่จําเป็นสําหรับการดําเนินการระยะไกล รวมถึง JUnit

Python

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

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

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

การใช้การครอบคลุม.py

วิธีหนึ่งที่ทําได้คือผ่านทาง rules_python ซึ่งช่วยให้คุณใช้ไฟล์ requirements.txt ได้ ข้อกําหนดที่ระบุในไฟล์จะสร้างขึ้นเป็นเป้าหมาย Bazel โดยใช้ 101}กฎพื้นที่เก็บข้อมูล 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",
)

เป้าหมายการครอบคลุมจะใช้เพื่อกําหนดเป้าหมายการทดสอบได้ด้วยการตั้งค่าต่อไปนี้ในไฟล์ 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",
    ],
)