Bazel ile kod kapsamı

Bazel, bazel coverage ile test edilebilen depolar hakkında kod kapsamı raporları oluşturmak için bir coverage alt komutu içerir. Çeşitli dil ekosistemlerinin kendine özgü farklılıkları nedeniyle, bu işlevin belirli bir projede işe yaraması her zaman sıradan bir şey değildir.

Bu sayfada, kapsam raporlarını oluşturma ve görüntülemeyle ilgili genel sürecin yanı sıra yapılandırması iyi bilinen diller için dile özgü bazı notlar yer almaktadır. Öncelikle genel bölümü okuduktan sonra belirli bir dilin şartlarını okumak en iyisidir. Ayrıca, bazı ek hususlar gerektiren uzaktan yürütme bölümüne de dikkat edin.

Çok fazla özelleştirme mümkün olsa da bu belge, şu anda en iyi desteklenen rota olan lcov raporlarını oluşturmaya ve kullanmaya odaklanmaktadır.

Kapsam raporu oluşturma

Hazırlık

Kapsam raporları oluşturmaya ilişkin temel iş akışı aşağıdakileri gerektirir:

• Test hedeflerine sahip temel bir depo
• Dile özgü kod kapsamı araçlarının yüklü olduğu bir araç zinciri
• Doğru "araçlar" yapılandırması

İlk ikisi dile özgü ve çoğunlukla basittir. Ancak karmaşık projelerde ikincisi daha zor olabilir.

Buradaki "araç", belirli bir hedef için kullanılan kapsam araçlarını ifade eder. Bazel, --instrumentation_filter işaretini kullanarak dosyaların belirli bir alt kümesi için bu özelliğin etkinleştirilmesini sağlar. Bu işaret, araçlar etkinken test edilen hedefler için bir filtre belirtir. Testlerde kullanılan araçları etkinleştirmek için --instrument_test_targets işareti gerekir.

Varsayılan olarak Bazel, hedef paketleri eşleştirmeye çalışır ve ilgili filtreyi INFO mesajı olarak yazdırır.

Yayın kapsamı

Kapsam raporu oluşturmak için bazel coverage --combined_report=lcov [target] kullanın. Bu işlem, hedef için testleri çalıştırır ve her dosya için lcov biçiminde kapsam raporları oluşturur.

Tamamlandıktan sonra Bazel, üretilen tüm cover dosyalarını toplayan ve bunları tek bir dosyada birleştiren bir işlem yürütür. Bu işlem daha sonra $(bazel info output_path)/_coverage/_coverage_report.dat altında oluşturulur.

Testler başarısız olursa kapsam raporları da oluşturulur. Ancak, bu rapor başarısız olan testleri kapsamaz, yalnızca geçen testler raporlanır.

Yayın kapsamı

Kapsam raporu, yalnızca kullanıcılar tarafından okunamayan lcov biçiminde oluşturulur. Buradan, web tarayıcısında görüntülenebilecek bir rapor oluşturmak için genhtml yardımcı programını (lcov projesinin bir parçası) kullanabiliriz:

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

Bu dosyalardaki eksik kapsamları eklemek için genhtml öğesinin kaynak kodu da okuduğunu unutmayın. Bunun çalışması için genhtml dosyasının, Bazel projesinin kök dizininde yürütülmesi beklenir.

Sonucu görüntülemek için, genhtml dizininde oluşturulan index.html dosyasını herhangi bir web tarayıcısında açmanız yeterlidir.

genhtml aracı veya lcov kapsam biçimi hakkında daha fazla yardım ve bilgi için lcov projesine bakın.

Uzaktan yürütme

Uzaktan test yürütmesiyle çalışırken şu anda dikkat edilmesi gereken birkaç nokta vardır:

• Rapor kombinasyonu işlemi henüz uzaktan çalıştırılamaz. Bunun nedeni, Bazel'in kapsam çıkış dosyalarını grafiğinin bir parçası olarak değerlendirmemesidir (bu soruna bakın) ve bu nedenle, bunları doğru bir şekilde kombinasyon işleminin girdileri olarak değerlendiremez. Bu sorunu gidermek için --strategy=CoverageReport=local aracını kullanın.
  • Not: Bazel'in stratejileri çözme şekli nedeniyle, Bazel local,remote alanını denemek üzere ayarlandıysa bunun yerine --strategy=CoverageReport=local,remote gibi bir değer belirtmeniz gerekebilir.
• --remote_download_minimal ve benzer işaretler de kullanılamaz.
• Testler daha önce önbelleğe alınmışsa Bazel şu anda kapsam bilgilerini oluşturamaz. Bu sorunu gidermek amacıyla --nocache_test_results, özellikle kapsam çalıştırmaları için ayarlanabilir. Ancak bu işlem, test süreleri açısından büyük bir maliyete neden olur.
• --experimental_split_coverage_postprocessing ve --experimental_fetch_all_coverage_outputs
  • Kapsam genellikle test işleminin bir parçası olarak çalıştırılır. Dolayısıyla varsayılan olarak, uzaktan yürütmenin çıktıları olarak kapsamın tamamını geri almayız. Bu işaretler, varsayılan değeri geçersiz kılar ve kapsam verilerini elde eder. Daha fazla bilgi için bu soruna bakın.

Dile özgü yapılandırma

Java

Java ilk yapılandırmayla anında çalışmalıdır. Pazar araç zincirleri, JUnit dahil olmak üzere uzaktan yürütme için gerekli her şeyi içerir.

Python

Ön koşullar

Python ile kapsam çalıştırmanın bazı ön koşulları vardır:

• b01c859 değerini içeren ve Bazel >3.0 olması gereken bir bazel ikili programı.
• Scope.py'nin değiştirilmiş bir sürümü.

Değiştirilen kapsama.py dosyasını kullanma

Bunu yapmanın bir yolu rules_python kullanmaktır. Bu yöntem, requirements.txt dosyası kullanabilmenizi sağlar. Dosyada listelenen gereksinimler, daha sonra pip_install depo kuralı kullanılarak bazel hedefleri olarak oluşturulur.

requirements.txt aşağıdaki girişe sahip olmalıdır:

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

Ardından rules_python, pip_install ve requirements.txt dosyası WORKSPACE dosyasında şu şekilde kullanılmalıdır:

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

Not: rules_python sürümü tesadüfidir. Bu, yazıldığı tarihte en son sürümdür. Güncel talimatlar için yukarı akışa bakın.

Daha sonra kapsam.py gereksinimi, BUILD dosyasında aşağıdakiler ayarlanarak test hedefleri tarafından kullanılabilir:

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

Hermetik Python araç zinciri kullanıyorsanız her py_test hedefine kapsam bağımlılığını eklemek yerine kapsam aracını araç zinciri yapılandırmasına ekleyebilirsiniz.

pip_install kuralı Python araç zincirine bağlı olduğundan, coverage modülünü getirmek için kullanılamaz. Bunun yerine, WORKSPACE metriğinizi ekleyin. Örneğin,

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

Ardından python araç zincirinizi

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