کتابخانه pytest-cov در پایتون

pytest-cov یک افزونه برای فریم‌ورک pytest است که امکان اندازه‌گیری و گزارش‌دهی پوشش کد (code coverage) را با استفاده از coverage.py فراهم می‌کند. این ابزار برای بررسی این که چه قسمت‌هایی از کد توسط تست‌ها اجرا شده‌اند بسیار حیاتی است و کمک می‌کند تا نقاط بدون تست یا ضعیف در تست‌ها را شناسایی و بهبود دهید.

چرا پوشش تست مهم است؟

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

نصب و راه‌اندازی

نصب pytest-cov ساده است و معمولاً همراه با pytest استفاده می‌شود:

pip install pytest pytest-cov

این دستور pytest و افزونه pytest-cov را نصب می‌کند تا بتوانید گزارش پوشش را تولید کنید.

اجرای تست‌ها با گزارش پوشش

مثال پایه‌ای اجرای تست و گزارش در ترمینال:

pytest --cov=your_package --cov-report=term-missing

در اینجا:

–cov=your_package: مشخص می‌کند پوشش برای کدام پکیج یا مسیر محاسبه شود.
–cov-report=term-missing: گزارش متنی با خطوطِ اجرا نشده را نمایش می‌دهد.

خروجی HTML

pytest --cov=your_package --cov-report=html
# سپس باز کردن پوشه htmlcov/index.html

این دستور یک گزارش HTML تولید می‌کند که به‌صورت گرافیکی نشان می‌دهد چه فایل‌هایی و چه خطوطی تست نشده‌اند. مناسب برای تحلیل دقیق‌تر و اشتراک‌گذاری با تیم است.

گزینه‌های رایج pytest-cov

گزینه	توضیح
–cov=PATH	محاسبه پوشش برای PATH مشخص
–cov-report=TYPE	نوع گزارش: term, term-missing, html, xml, annotate
–cov-fail-under=MIN	ناموفق کردن اجرای آزمون اگر پوشش کمتر از MIN درصد باشد
–cov-branch	محاسبه پوشش شاخه‌ها (branch coverage)
–cov-config=FILE	استفاده از فایل پیکربندی برای coverage.py

پیکربندی coverage با .coveragerc

برای کنترل دقیق‌تر، فایل .coveragerc می‌تواند مفید باشد. نمونه‌ای از .coveragerc:

[run]
branch = True
source = your_package
omit =
    tests/*
    */__init__.py

[report]
exclude_lines =
    pragma: no cover
    if __name__ == .__main__.:

این پیکربندی شاخه‌ها را فعال می‌کند، منبع را مشخص می‌نماید و فایل‌های تست یا __init__ را از محاسبه پوشش حذف می‌کند. همچنین خطوطی که با pragma: no cover علامت‌گذاری شده‌اند را نادیده می‌گیرد.

مثال کامل همراه با توضیح

# اجرای تست، محاسبه شاخه و گزارش متنی و html
pytest --cov=your_package --cov-branch --cov-report=term-missing --cov-report=html

در این مثال پوشش خط و شاخه محاسبه می‌شود، گزارش متنی (با نشان دادن خطوط ناقص) و یک گزارش HTML تولید می‌گردد تا بررسی بصری انجام شود.

ادغام با CI (مثال: GitHub Actions)

در CI معمولاً می‌خواهید پوشش را محاسبه و در صورت کمتر از حداقل مجاز، ساخت را شکست دهید. نمونه گام‌های ساده:

# یک job در GitHub Actions (نمونه خلاصه)
- name: Run tests with coverage
  run: pytest --cov=your_package --cov-report=xml --cov-fail-under=80

- name: Upload coverage report
  uses: actions/upload-artifact@v3
  with:
    name: coverage-xml
    path: coverage.xml

در این پیکربندی، پوشش به فرمت XML صادر می‌شود (مناسب برای ابزارهای گزارش‌دهی) و اجرای CI در صورتی که پوشش کمتر از 80٪ باشد ناموفق خواهد شد.

نکات پیشرفته و بهینه‌سازی

پوشش شاخه: branch coverage را فعال کنید تا شرایط شرط‌ها و بلوک‌های شرطی نیز تحت پوشش قرار گیرند، نه فقط خطوط.
تست‌های موازی (pytest-xdist): هنگام اجرای موازی، coverage.py ممکن است فایل‌های جداگانه تولید کند؛ پس از اتمام، از coverage combine استفاده کنید و سپس گزارش را بسازید: coverage combine && coverage html.
فایل‌های خارجی و وابستگی‌ها: کتابخانه‌ها و فایل‌های تولید شده را از گزارش حذف کنید تا اعداد پوشش معنادار باشند (با omit در .coveragerc یا –cov-omit).
آستانه‌ها: از –cov-fail-under استفاده کنید تا معیار کیفی پوشش را به‌عنوان بخشی از فرآیند توسعه حفظ کنید.

ادغام با pytest-xdist (نکته عملی)

اگر از pytest-xdist برای اجرای موازی تست‌ها استفاده می‌کنید، اجرا معمولاً چند فایل پوشش جدا می‌سازد. برای ترکیب این فایل‌ها و تولید گزارش واحد:

pytest -n auto --cov=your_package --cov-report=term
coverage combine
coverage html

در اینجا پس از اجرای موازی، دستور coverage combine تمامی فایل‌های موقت پوشش را به یک فایل واحد ادغام می‌کند و سپس coverage html گزارش نهایی را خواهد ساخت.

اشتباهات رایج و راه‌حل‌ها

محاسبه پوشش روی فایل‌های اشتباهی: مطمئن شوید –cov به مسیر صحیح اشاره می‌کند.
شناسایی تست‌هایی که عملاً چیزی را اجرا نمی‌کنند: term-missing و HTML کمک می‌کنند خطوط بدون اجرا را ببینید.
اعتماد صرف به درصد پوشش: درصد بالا تضمین کیفیت کد نیست؛ پوشش معنادار و تست‌های دقیق اهمیت دارند.

نتیجه‌گیری و بهترین شیوه‌ها

pytest-cov یک ابزار قدرتمند و ضروری برای هر پروژه پایتون است که از pytest استفاده می‌کند. با پیکربندی مناسب، گزارش‌های خوانا، و ادغام در CI می‌توانید کیفیت تست‌ها را به‌طور پیوسته اندازه‌گیری و بهبود دهید. همیشه پوشش را به‌عنوان یکی از معیارها در کنار بررسی کیفی تست‌ها و معیارهای دیگر در نظر بگیرید.

آیا این مطلب برای شما مفید بود ؟

خیر

بله