Cakupan kode dengan Bazel

Bazel memiliki sub-perintah coverage untuk menghasilkan laporan cakupan kode pada repositori yang dapat diuji dengan bazel coverage. Karena keistimewaan berbagai ekosistem bahasa, tidak mudah untuk membuat pekerjaan ini untuk project tertentu.

Halaman ini mendokumentasikan proses umum untuk membuat dan melihat laporan cakupan, serta menampilkan beberapa catatan khusus bahasa untuk bahasa yang konfigurasinya terkenal. Sebaiknya baca terlebih dahulu dengan membaca bagian umum, kemudian baca tentang persyaratan untuk bahasa tertentu. Perhatikan juga bagian eksekusi jarak jauh, yang memerlukan beberapa pertimbangan tambahan.

Meskipun banyak penyesuaian dapat dilakukan, dokumen ini berfokus pada produksi dan penggunaan laporan lcov, yang saat ini merupakan rute yang paling didukung.

Membuat laporan cakupan

Persiapan

Alur kerja dasar untuk membuat laporan cakupan memerlukan hal berikut:

  • Repositori dasar dengan target pengujian
  • Toolchain dengan alat cakupan kode khusus bahasa yang diinstal
  • Konfigurasi "instrumentasi" yang benar

Dua yang pertama bersifat spesifik per bahasa dan sebagian besar langsung, tetapi yang kedua dapat lebih sulit untuk project yang kompleks.

"Instrumentasi" dalam hal ini mengacu pada alat cakupan yang digunakan untuk target tertentu. Bazel memungkinkan pengaktifan ini untuk subkumpulan file tertentu menggunakan tanda --instrumentation_filter, yang menentukan filter untuk target yang diuji dengan instrumentasi. Untuk mengaktifkan instrumentasi pengujian, flag --instrument_test_targets diperlukan.

Secara default, bazel mencoba mencocokkan paket target, dan mencetak filter yang relevan sebagai pesan INFO.

Cakupan yang berjalan

Untuk membuat laporan cakupan, gunakan bazel coverage --combined_report=lcov [target]. Tindakan ini akan menjalankan pengujian untuk target, menghasilkan laporan cakupan dalam format lcov untuk setiap file.

Setelah selesai, bazel menjalankan tindakan yang mengumpulkan semua file cakupan yang dihasilkan, dan menggabungkannya menjadi satu, yang akhirnya dibuat dengan $(bazel info output_path)/_coverage/_coverage_report.dat.

Laporan cakupan juga dibuat jika pengujian gagal. Namun, perlu diperhatikan bahwa ini tidak mencakup pengujian yang gagal - hanya pengujian yang lulus yang dilaporkan.

Melihat cakupan

Laporan cakupan hanya menghasilkan format lcov yang tidak dapat dibaca manusia. Setelah itu, kita dapat menggunakan utilitas genhtml (bagian dari project lcov) untuk membuat laporan yang dapat dilihat di browser web:

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

Perlu diketahui bahwa genhtml juga akan membaca kode sumber, untuk menganotasi cakupan yang tidak ada dalam file ini. Agar berfungsi, diharapkan genhtml dijalankan di root project bazel.

Untuk melihat hasilnya, cukup buka file index.html yang dihasilkan di direktori genhtml di browser web apa pun.

Untuk bantuan dan informasi lebih lanjut tentang alat genhtml, atau format cakupan lcov, lihat project lcov.

Eksekusi jarak jauh

Menjalankan dengan eksekusi pengujian jarak jauh saat ini memiliki beberapa peringatan:

  • Tindakan kombinasi laporan belum dapat dijalankan dari jarak jauh. Ini karena Bazel tidak menganggap file output cakupan sebagai bagian dari grafiknya (lihat masalah ini), sehingga tidak dapat memperlakukannya dengan benar sebagai input untuk kombinasi tersebut. Untuk menyelesaikan masalah ini, gunakan --strategy=CoverageReport=local.
    • Catatan: Mungkin Anda perlu menentukan sesuatu seperti --strategy=CoverageReport=local,remote, jika Bazel disiapkan untuk mencoba local,remote, karena cara Bazel menyelesaikan strategi.
  • --remote_download_minimal dan flag serupa juga tidak dapat digunakan sebagai konsekuensi dari yang sebelumnya.
  • Bazel saat ini akan gagal membuat informasi cakupan jika pengujian telah disimpan dalam cache sebelumnya. Untuk mengatasi hal ini, --nocache_test_results dapat disetel khusus untuk cakupan cakupan, meskipun hal ini tentu saja menimbulkan biaya yang berat dalam hal waktu pengujian.
  • --experimental_split_coverage_postprocessing dan --experimental_fetch_all_coverage_outputs
    • Biasanya cakupan dijalankan sebagai bagian dari tindakan pengujian, sehingga secara default, kami tidak mendapatkan kembali semua cakupan sebagai output eksekusi jarak jauh secara default. Flag ini mengganti default dan mendapatkan data cakupan. Lihat masalah ini untuk mengetahui detail selengkapnya.

Konfigurasi khusus bahasa

Java

Java akan langsung bekerja dengan konfigurasi default. Toolchain toolchain berisi semua yang diperlukan untuk eksekusi jarak jauh, termasuk JUnit.

Python

Prasyarat

Menjalankan cakupan dengan python memiliki beberapa prasyarat:

Memakai cakupan.py yang dimodifikasi

Cara untuk melakukannya adalah melaluiaturan_python, hal ini memberikan kemampuan untuk menggunakanrequirements.txt file, persyaratan yang tercantum dalam file kemudian dibuat sebagai target bazel menggunakan pip_instal aturan repositori.

requirements.txt harus memiliki entri berikut:

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

Kemudian, file rules_python, pip_install, dan requirements.txt akan digunakan dalam file WORKSPACE sebagai:

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

Persyaratan cakupan.py kemudian dapat digunakan oleh target pengujian dengan menetapkan hal berikut dalam file 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",
    ],
)