نسبة استخدام رموز الصفحة مع Bazel

تتضمّن خدمة Bazel طلبًا فرعيًا مدته coverage لإنشاء تقارير حول تغطية الرموز البرمجية في المستودعات التي يمكن اختبارها باستخدام bazel coverage. وبسبب التشابه الخاص بين المنظومة المتكاملة للأنظمة اللغوية المختلفة، ليس من السهل دائمًا إنجاز ذلك في إطار مشروع معيّن.

توثّق هذه الصفحة العملية العامة لإنشاء تقارير التغطية وعرضها، وتعرض أيضًا بعض الملاحظات بلغات معيّنة. ومن الأفضل أن تقرأ أولاً القسم العام، ثم تقرأ المقالة عن متطلبات لغة معينة. لاحظ أيضًا قسم التنفيذ عن بُعد، والذي يتطلب بعض الاعتبارات الإضافية.

على الرغم من إمكانية الكثير من التخصيص، يركز هذا المستند على إنتاج تقارير lcov واستهلاكها، والتي تعد حاليًا الطريق الأكثر دعمًا.

إنشاء تقرير التغطية

الإعداد

يتطلّب سير العمل الأساسي لإنشاء تقارير التغطية ما يلي:

  • مستودع أساسي باستهدافات تجريبية
  • سلسلة أدوات مع تثبيت أدوات تغطية الرمز المخصّصة للغة
  • ضبط "التطبيق" الصحيح

هاتان الميزتان السابقتان خاصتان بلغة معيّنة وتكون مباشرة في الغالب، ولكنها قد تكون أكثر صعوبة في المشاريع المعقّدة.

وتشير "الأداة" في هذه الحالة إلى أدوات التغطية التي تُستخدم لاستهداف محدد. يسمح 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 في جذر مشروع البازيل.

لعرض النتيجة، ما عليك سوى فتح ملف index.html الذي تم إنشاؤه في الدليل genhtml في أي متصفّح ويب.

للحصول على مزيد من المساعدة والمعلومات حول أداة genhtml أو تنسيق التغطية lcov، يمكنك الاطّلاع على مشروع lcov.

التنفيذ عن بُعد

يواجه حاليًا تنفيذ الاختبار عن بُعد بعض التنبيهات:

  • لا يمكن تشغيل إجراء نسخة التقرير عن بُعد بعد. ويرجع السبب في ذلك إلى أنّ Bazel لا يتعامل مع ملفات إخراج المحتوى كجزء من الرسم البياني الخاص به (راجِع هذه المشكلة)، وبالتالي لا يتعامل معها بشكل صحيح على أنها إدخالات إلى التركيبة. إِجْرَاء ولحلّ هذه المشكلة، استخدِم --strategy=CoverageReport=local.
    • ملاحظة: قد يكون من الضروري تحديد شيئًا مثل --strategy=CoverageReport=local,remote، في حال إعداد منصّة Bazel لتجربة local,remote، بسبب الطريقة التي يتّبعها بازيل في حلّ الاستراتيجيات.
  • لا يمكن أيضًا استخدام --remote_download_minimal والعلامات المشابهة نتيجة لها.
  • سيفشل Bazel حاليًا في إنشاء معلومات التغطية إذا تم تخزين الاختبارات مؤقتًا في السابق. ولحل هذه المشكلة، يمكن ضبط --nocache_test_results تحديدًا للتغطية، على الرغم من أن هذا الأمر يترتّب عليه تكلفة باهظة من حيث مدد الاختبار.
  • --experimental_split_coverage_postprocessing و--experimental_fetch_all_coverage_outputs
    • يتم عادةً تشغيل التغطية كجزء من الإجراء الاختباري، ولذلك لا نعيد تلقائيًا كل التغطية كمخرجات للتنفيذ عن بُعد بشكل تلقائي. وتلغي هذه العلامات الإعداد التلقائي وتحصل على بيانات التغطية. اطّلع على هذه المشكلة لمزيد من التفاصيل.

إعداد خاص باللغة

Java

يجب أن يعمل جافا بشكل فوري باستخدام الإعداد الافتراضي. تتضمّن سلاسل أدوات البازل كل ما يلزم لتنفيذها عن بُعد أيضًا، بما في ذلك JUnit.

Python

المتطلبات الأساسية

تتوفّر المتطلبات الأساسية لتشغيل التغطية في python:

استخدام التغطية المعدّلة.py

يمكنك تحقيق ذلك من خلالالقواعد_الخاصة ، حيث يوفر ذلك إمكانية استخدامrequirements.txt الملف، يتم بعد ذلك إنشاء المتطلّبات المُدرَجة في الملف كأهداف بتنسيق bazel باستخدامتثبيت_pip قاعدة مستودع.

يجب أن يحتوي 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",
)

يمكن بعد ذلك استهلاك متطلبات.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",
    ],
)