نام (NAME)

py2lcov - تبدیل داده‌های Coverage.py پایتون به قالب lcov

بخش راهنما: 1
گروه راهنما: LCOV Tools

نام (NAME)

py2lcov: تبدیل داده‌های Coverage.py پایتون به قالب lcov

خلاصه دستور (SYNOPSIS)

py2lcov [--output mydata.info] [--test-name name] [options] coverage.dat+

توضیحات (DESCRIPTION)

ابزار py2lcov داده‌های پوشش پایتون را در یک یا چند فایل داده‌های پوشش (تولیدشده توسط ماژول Coverage.py) پیمایش کرده و آن‌ها را به قالب .info ابزار LCOV تبدیل می‌کند.

توجه داشته باشید که آرگومان --no-functions ممکن است در صورتی که یک پایگاه‌داده پوشش no-functions با پایگاه‌داده‌ای حاوی داده‌های مشتق‌شده از توابع ادغام شود، به داده‌های پوشش با ناسازگاری‌های نامحسوس منجر گردد. دلیل این امر آن است که خط def myFunc(...) مقدار شمارش اجرای ۱ را دریافت خواهد کرد (مفسر پایتون اجرای def را هنگام تفسیر خط، یعنی زمان تعریف تابع، لحاظ می‌کند). در صورتی که تابع در آزمون‌های شما اجرا نشود، این حالت موجب بروز خطای inconsistent خواهد شد؛ زیرا تابع (مشتق‌شده) دارای شمارش اجرای صفر است اما خط اول تابع مقداری غیرصفر دارد.

بهترین شیوه: یا همواره --no-functions را مشخص کنید یا هرگز --no-functions را به کار نبرید.

ابزار py2lcov از Coverage.py برای استخراج داده‌های پوشش استفاده می‌کند. نام فایل اجرایی Coverage.py ممکن است در پلتفرم شما متفاوت باشد. به‌طور پیش‌فرض، py2lcov از coverage استفاده می‌کند (که انتظار می‌رود در PATH شما موجود باشد). شما می‌توانید از طریق متغیر محیطی COVERAGE_COMMAND یا گزینه خط فرمان --cmd از فایل اجرایی دیگری استفاده کنید.

ابزار py2lcov تمام مجموعه ویژگی‌های LCOV (مانند فیلترسازی، جایگزینی‌ها و غیره) را پیاده‌سازی نمی‌کند. ابتدا فایل با قالب ترجمه‌شده LCOV را تولید کرده و سپس داده‌ها را دوباره در lcov بخوانید تا بتوانید از این ویژگی‌ها بهره ببرید.

محدودیت‌های پوشش شاخه (Branch Coverage)

توجه داشته باشید که قالب داده‌های پوشش XML اطلاعات کافی برای استنتاج دقیق این که کدام عبارت‌های شاخه طی شده‌اند یا نشده‌اند را در خود ندارد. این قالب فقط تعداد کل عبارت‌های شاخه مرتبط با یک خط مشخص و تعداد موارد طی‌شده از بین آن‌ها را گزارش می‌کند. هیچ راهی برای آگاهی از این که دقیقاً کدام موارد بوده‌اند وجود ندارد (مگر احتمالاً از طریق بررسی کدهای پیرامون یا درک نحوه پیاده‌سازی برنامه).

این موضوع دست‌کم از ۲ جهت مشکل‌ساز است:

استفاده از نتیجه برای بهبود مجموعه آزمون‌های رگرسیون سرراست نیست، زیرا شما واقعاً نمی‌دانید چه مواردی آزموده شده یا نشده‌اند.
ادغام داده‌های پوشش با مشکل روبه‌رو می‌شود. برای نمونه: دو فایل XML مربوط به آزمون‌ها دارید که هر کدام ۴ شاخه از ۸ شاخه را در یک خط خاص پوشش داده‌اند. آیا این بدان معناست که ۴ مورد از آن‌ها طی شده است (هر دو آزمون کد یکسانی را اجرا کرده‌اند)، هر ۸ مورد (آزمون‌ها زیرمجموعه‌های مجزایی را اجرا کرده‌اند)، یا عددی بین این دو؟

این پیاده‌سازی فرض می‌کند که در هر مورد آزمون، M شاخه اول مواردی هستند که اجرا شده‌اند و N-M شاخه باقی‌مانده اجرا نشده‌اند. بنابراین، نتیجه ترکیبی در مثال بالا مدعی پوشش ۴ شاخه از ۸ شاخه خواهد بود. این تعریف در عمل یک حد پایین (lower bound) محسوب می‌شود.

گزینه‌ها (OPTIONS)

-i, --input file: منسوخ‌شده: فایل XML ورودی از coverage.py را مشخص می‌کند.
-o, --output file: فایل خروجی .info ابزار LCOV را مشخص می‌کند. پیش‌فرض: py2lcov.info.
-t, --test-name, --testname name: نام آزمون را برای مدخل TN: در فایل .info ابزار LCOV مشخص می‌کند.
-e, --exclude patterns: الگوهای فایل‌های مستثنی‌شده را که با کاما از هم جدا شده‌اند مشخص می‌کند.
-v, --verbose: پیام‌های اشکال‌زدایی را چاپ می‌کند.
--version-script script: اسکریپت بازخوانی برای استخراج نسخه.
--checksum: محاسبه چک‌سام خط. به lcov(1) <file://../man/lcov.1.html> مراجعه کنید.
--no-functions: نقاط پوشش تابع را استخراج نمی‌کند.
--tabwidth n: اندازه نویسه تب هنگام محاسبه تورفتگی. پیش‌فرض: 8.
-k, --keep-going: خطاها را نادیده گرفته و به پردازش ادامه می‌دهد.
--cmd executable: فایل اجرایی مورد استفاده برای استخراج داده‌های پوشش پایتون (مانند python3-coverage). پیش‌فرض: coverage (یا مقدار متغیر محیطی COVERAGE_COMMAND).

توجه داشته باشید که py2lcov یک فایل اجرایی مستقل پایتون است؛ از این رو مستقیماً از گزینه‌های استاندارد خط فرمان و تنظیمات RC ابزار LCOV (برای نمونه برای فیلترسازی، گنجاندن یا مستثنی‌کردن فایل‌ها و غیره) پشتیبانی نمی‌کند. برای استفاده از این گزینه‌ها، باید ابتدا با استفاده از py2lcov پایگاه‌داده پوشش خود را ثبت کنید و سپس گزینه‌های دلخواه خود را از طریق lcov -a pycov.info <options> ... اعمال نمایید. برای جزئیات به lcov(1) <file://../man/lcov.1.html> مراجعه فرمایید.

مثال‌ها (EXAMPLES)

گردش کار پایه:

$ export PYCOV_DATA=path/to/pydata
# برای نسخه‌های 'coverage' ۶.۶.۱ و بالاتر (با پشتیبانی از "--data-file"):
$ coverage run --data-file=${PYCOV_DATA} --append --branch \
    /path/to/myPythonScript.py args_to_my_python_script
# برای نسخه‌های قدیمی‌تر بدون پشتیبانی از "--data-file":
$ COVERAGE_FILE=${PYCOV_DATA} coverage run --append --branch \
    /path/to/myPythonScript.py args_to_my_python_script
# تبدیل به قالب LCOV:
$ py2lcov -o pydata.info ${PYCOV_DATA}
# اعمال فیلترسازی:
$ lcov -a pydata.info -o filtered.info --filter branch,blank
# تولید گزارش HTML:
$ genhtml -o html_report pydata.info
# تولید گزارش فیلترشده:
$ genhtml -o html_filtered filtered.info
# استفاده از پوشش دیفرانسیلی برای مشاهده اثر فیلترسازی:
$ genhtml -o html_differential --baseline-file mydata.info filtered.info

حالت ورودی منسوخ‌شده XML:

# ابتدا تبدیل داده‌های پوشش پایتون به XML:
$ coverage xml --data-file=${PYCOV_DATA} -o pydata.xml
# سپس تبدیل XML به قالب LCOV:
$ py2lcov -i pydata.xml -o pydata.info --version-script myCovScript

محیط (ENVIRONMENT)

COVERAGE_COMMAND: جایگزین کردن فایل اجرایی پیش‌فرض coverage که برای استخراج داده‌های پوشش پایتون به کار می‌رود.
COVERAGE_FILE: فایل ورودی پیش‌فرض در صورتی که هیچ فایلی در خط فرمان مشخص نشده باشد.

نویسندگان (AUTHORS)

Henry Cox <<henry.cox@mediatek.com>>

همچنین ببینید (SEE ALSO)

lcov(1) <file://../man/lcov.1.html>, genhtml(1) <file://../man/genhtml.1.html>, geninfo(1) <file://../man/geninfo.1.html>

•: مستندات Coverage.py: https://coverage.readthedocs.io

کپی‌رایت و تکثیر (COPYRIGHT)

2024-2026, LCOV Project