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

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

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

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

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

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

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

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

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

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

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

การรายงานข่าวอย่างต่อเนื่อง

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

เมื่อเสร็จแล้ว Bazel จะเรียกใช้การดำเนินการที่รวบรวมไฟล์ Coverage ทั้งหมดที่สร้างขึ้น และผสานรวมเป็นไฟล์เดียว ซึ่งจะสร้างขึ้นใน $(bazel info output_path)/_coverage/_coverage_report.dat ในที่สุด

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

การดูความครอบคลุม

รายงานความครอบคลุมจะแสดงในรูปแบบที่มนุษย์อ่านไม่ได้lcov เท่านั้น จากนั้นเราจะใช้ยูทิลิตี genhtml (ส่วนหนึ่งของโปรเจ็กต์ lcov) เพื่อสร้างรายงานที่ดูได้ในเว็บเบราว์เซอร์

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

โปรดทราบว่า genhtml จะอ่านซอร์สโค้ดด้วยเพื่อใส่คำอธิบายประกอบเกี่ยวกับความครอบคลุมที่ขาดหายไปในไฟล์เหล่านี้ โดยคาดว่า genhtml จะดำเนินการในรูทของโปรเจ็กต์ Bazel

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

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

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

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

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

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

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

C++

Linux

การครอบคลุมของ C++ ควรทำงานได้ทันทีด้วยการกำหนดค่าเริ่มต้น

macOS

ค่าเริ่มต้นของ GCOV_PREFIX_STRIP มักจะไม่ถูกต้องและต้องปรับด้วยตนเองเนื่องจากค่าที่ถูกต้องจะขึ้นอยู่กับการตั้งค่าของคุณ

เมื่อค่าไม่ถูกต้อง ระบบจะไม่พบข้อมูลความครอบคลุม

ตัวอย่างการตั้งค่า GCOV_PREFIX_STRIP=10 bazel coverage //foo:foo_test --test_env=GCOV_PREFIX_STRIP=10`

Java

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

Python

ดูเอกสารเกี่ยวกับความครอบคลุมของ rules_python เพื่อดูขั้นตอนเพิ่มเติมที่จำเป็นในการเปิดใช้การรองรับความครอบคลุมใน Python