نوشتن، اجرا و تست کد

رفع یک باگ یا پیاده‌سازی یک قابلیت مستلزم نوشتن مقداری کد جدید است.

برای شروع کار روی کد، اطمینان حاصل کنید که یک محیط توسعه راه‌اندازی کرده‌اید و روی یک شعبه کار می‌کنید.

ما یک راهنمای سبک کدنویسی داریم که دستورالعمل‌های ما را برای نوشتن کد در BeeWare تشریح می‌کند.

توسعهٔ مبتنی بر آزمون

یک روش خوب برای اطمینان از اینکه کد شما همان کاری را انجام می‌دهد که انتظار دارید، این است که ابتدا یک مورد آزمون برای آن بنویسید. این مورد آزمون در ابتدا باید شکست بخورد، زیرا کدی که قرار است آزمایش شود هنوز موجود نیست. سپس می‌توانید تغییرات لازم در کد را بنویسید تا آزمون با موفقیت اجرا شود و مطمئن شوید که نوشته‌هایتان مسئله‌ای را که انتظار دارید حل می‌کند.

کد خود را اجرا کنید

پس از نوشتن کدتان، باید مطمئن شوید که اجرا می‌شود. برای اطمینان از انجام آنچه انتظار دارید، باید کدتان را به‌صورت دستی اجرا کنید. اگر هنوز این کار را نکرده‌اید، باید یک مورد آزمون برای تغییرات خود بنویسید؛ همان‌طور که در بالا ذکر شد، این آزمون باید در صورتی که کد شما غیرفعال یا موجود نباشد، شکست بخورد.

شما مورد آزمون خود را به مجموعه آزمون‌ها اضافه می‌کنید تا بتوان آن را همراه با سایر آزمون‌ها اجرا کرد. گام بعدی اجرای مجموعه آزمون‌ها است.

اجرای تست‌ها و پوشش

BeeWare از tox برای مدیریت فرایند تست و از pytest برای مجموعه تست‌های خود استفاده می‌کند.

دستور پیش‌فرض tox شامل اجرای موارد زیر است:

• قلاب‌های پیش از commit
• towncrier بررسی یادداشت انتشار

• مستندسازی لینتینگ

• مجموعه آزمون برای نسخه‌های موجود پایتون

• گزارش پوشش کد

این اساساً همان چیزی است که CI هنگام ارسال یک درخواست برداشت اجرا می‌کند.

برای اجرای کامل مجموعه تست‌ها، اجرا کنید:

macOSLinuxWindows

(.venv) $ tox

(.venv) $ tox

(.venv) C:\...>tox

اجرای کل مجموعه تست ممکن است مدتی طول بکشد. شما می‌توانید با اجرای موازی tox، tox p (یا tox run-parallel)، آن را به‌طور قابل توجهی سریع‌تر کنید. وقتی مجموعه تست را به‌صورت موازی اجرا می‌کنید، بازخورد کمتری در مورد پیشرفت آن دریافت خواهید کرد، اما همچنان در پایان اجرای تست، خلاصه‌ای از هر مشکلی که پیدا شده است دریافت می‌کنید. باید خروجی‌ای دریافت کنید که نشان دهد تست‌ها اجرا شده‌اند. ممکن است تست‌های SKIPPED را ببینید، اما هرگز نباید هیچ نتیجه تست FAIL یا ERROR دریافت کنید. ما کل مجموعه تست خود را قبل از ادغام هر پچ اجرا می‌کنیم. اگر این فرآیند به هر مشکلی برخورد کند، آن پچ را ادغام نمی‌کنیم. اگر شما با یک خطا یا شکست تست مواجه شدید، یا در محیط تست شما چیزی عجیب است، یا شما یک مورد حاشیه‌ای (edge case) را پیدا کرده‌اید که ما قبلاً ندیده‌ایم - در هر صورت، به ما اطلاع دهید!

علاوه بر موفقیت آزمون‌ها، این باید ۱۰۰٪ پوشش آزمون را گزارش دهد.

اجرای تست‌های متغیر

تست‌ها را برای نسخه‌های مختلف پایتون اجرا کنید.

به‌طور پیش‌فرض، بسیاری از دستورات tox تلاش می‌کنند مجموعه تست را چندین بار اجرا کنند، یک‌بار برای هر نسخه پایتونی که توسط BeeWare پشتیبانی می‌شود. با این حال، برای انجام این کار، هر یک از نسخه‌های پایتون باید روی سیستم شما نصب شده و در فرآیند کشف پایتون tox در دسترس باشد. به‌طور کلی، اگر نسخه‌ای از پایتون از طریق (https://virtualenv.pypa.io/en/latest/explanation.html#python-discovery) در دسترس باشد، PATH باید بتواند آن را پیدا کرده و از آن استفاده کند.

فقط مجموعه آزمون‌ها را اجرا کنید

اگر در حال تکرار سریع یک ویژگی جدید هستید، نیازی نیست کل مجموعه تست‌ها را اجرا کنید؛ می‌توانید فقط تست‌های واحد را اجرا کنید. برای این کار، اجرا کنید:

macOSLinuxWindows

(.venv) $ tox -e py

(.venv) $ tox -e py

(.venv) C:\...>tox -e py

اجرای زیرمجموعه‌ای از آزمون‌ها

به‌طور پیش‌فرض، tox تمام تست‌ها را در مجموعه تست واحد اجرا می‌کند. وقتی در حال توسعه تست جدید خود هستید، ممکن است مفید باشد که فقط همان یک تست را اجرا کنید. برای این کار می‌توانید هر مشخص‌کننده pytest را به‌عنوان آرگومان به tox پاس کنید. این مسیرهای تست نسبت به دایرکتوری briefcase هستند. برای مثال، برای اجرای تنها تست‌های یک فایل واحد، اجرا کنید:

macOSLinuxWindows

(.venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py

(.venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py

(.venv) C:\...>tox -e py -- tests/path_to_test_file/test_some_test.py

شما همچنان هنگام اجرای بخشی از مجموعه آزمون‌ها گزارش پوشش دریافت خواهید کرد، اما نتایج پوشش تنها خطوط کدی را گزارش می‌کنند که توسط آزمون‌های مشخصی که اجرا کرده‌اید، اجرا شده‌اند.

مجموعه تست‌ها را برای یک نسخه مشخص از پایتون اجرا کنید

به‌طور پیش‌فرض tox -e py با هر تفسیرگری که روی سیستم شما با python مطابقت دارد اجرا می‌شود. اگر چندین نسخهٔ پایتون نصب کرده باشید و بخواهید نسخهٔ خاصی را از میان نسخه‌های نصب‌شده آزمایش کنید، می‌توانید نسخهٔ مشخصی را برای استفاده تعیین کنید. برای مثال، برای اجرای مجموعهٔ تست‌ها روی پایتون 3.10، دستور زیر را اجرا کنید:

macOSLinuxWindows

(.venv) $ tox -e py310

(.venv) $ tox -e py310

(.venv) C:\...>tox -e py310

می‌توان یک زیرمجموعه از تست‌ها را با افزودن -- و یک مشخصهٔ تست به خط فرمان اجرا کرد.

مجموعه تست‌ها را بدون پوشش (سریع) اجرا کنید

به‌طور پیش‌فرض، tox مجموعه تست pytest را در حالت تک‌ریسمانی اجرا می‌کند. می‌توانید با اجرای موازی مجموعه تست، سرعت اجرای آن را افزایش دهید. این حالت به‌دلیل پیچیدگی‌های ثبت پوشش در فرآیندهای spawn شده، فایل‌های پوشش تولید نمی‌کند. برای اجرای یک نسخه از پایتون در حالت «سریع»، دستور زیر را اجرا کنید:

macOSLinuxWindows

(.venv) $ tox -e py-fast

(.venv) $ tox -e py-fast

(.venv) C:\...>tox -e py-fast

یک زیرمجموعه از تست‌ها را می‌توان با افزودن -- و یک مشخصه تست به خط فرمان اجرا کرد؛ یک نسخهٔ خاص پایتون را می‌توان با افزودن نسخه به هدف تست استفاده کرد (مثلاً py310-fast برای اجرای سریع روی پایتون 3.10).

پوشش کد

BeeWare در پایگاه‌کد خود پوشش ۱۰۰٪ شاخه‌ها را حفظ می‌کند. وقتی در پروژه کد اضافه یا تغییر می‌دهید، باید کد تست اضافه کنید تا پوشش هر تغییری را که ایجاد کرده‌اید تضمین کنید.

با این حال، BeeWare چندین پلتفرم و همچنین چندین نسخه از پایتون را هدف قرار می‌دهد، بنابراین پوشش کامل را نمی‌توان تنها روی یک پلتفرم و نسخه پایتون تأیید کرد. برای رفع این مشکل، چندین قاعده پوشش شرطی در بخش tool.coverage.coverage_conditional_plugin.rules از pyproject.toml تعریف شده‌اند (مثلاً می‌توان از no-cover-if-is-windows برای علامت‌گذاری بخشی از کد استفاده کرد که هنگام اجرای مجموعه تست‌ها روی ویندوز اجرا نخواهد شد). این قواعد برای شناسایی بخش‌های کدی به کار می‌روند که تنها روی پلتفرم‌ها یا نسخه‌های خاصی از پایتون پوشش داده شده‌اند.

شایان ذکر است که گزارش‌گیری پوشش در نسخه‌های مختلف پایتون می‌تواند کمی نامتعارف باشد. برای مثال، اگر فایل‌های پوشش با یک نسخه از پایتون تولید شوند اما گزارش‌گیری پوشش با نسخه‌ای دیگر انجام شود، ممکن است گزارش شامل نتایج مثبت کاذب برای شاخه‌های از دست رفته باشد. به همین دلیل، گزارش‌گیری پوشش همیشه باید با قدیمی‌ترین نسخه‌ای از پایتون که برای تولید فایل‌های پوشش استفاده شده است، انجام شود.

درک نتایج پوشش

در پایان خروجی آزمون پوشش باید گزارشی از داده‌های پوشش جمع‌آوری‌شده وجود داشته باشد:

نام    بیانیه‌ها   مفقود   بخش   پوشش   مفقود
 ---------------------------------------------------
 کل    7540 0   1040 0  100.0%

این به ما می‌گوید که مجموعه آزمون‌ها هر مسیر انشعابی ممکن در کد را اجرا کرده است. این تضمین صددرصدی نیست که هیچ باگی وجود ندارد، اما به این معناست که ما هر خط کد در پایگاه کد را اجرا می‌کنیم.

اگر در پایگاه کد تغییراتی ایجاد کنید، ممکن است در این پوشش یک شکاف ایجاد شود. وقتی این اتفاق می‌افتد، گزارش پوشش به شما می‌گوید کدام خطوط اجرا نمی‌شوند. برای مثال، فرض کنید ما تغییری در some/interesting_file.py ایجاد کردیم و منطق جدیدی اضافه کردیم. گزارش پوشش ممکن است چیزی شبیه به این باشد:

نام   اظهارات    شعبه    بخش    پوشش    مفقود
 -------------------------------------------------------------------------------
 src/some/interesting_file.py 111 1     26 0  98.1%   170, 302-307, 320->335
 -------------------------------------------------------------------------------
 مجموع 7540 1   1726 0  99.9%

این به ما می‌گوید که خط ۱۷۰، خطوط ۳۰۲ تا ۳۰۷ و جهشی از خط ۳۲۰ به خط ۳۳۵ توسط مجموعه آزمون اجرا نمی‌شوند. برای بازیابی این پوشش باید آزمون‌های جدیدی اضافه کنید (یا آزمون موجود را اصلاح کنید).

گزارش پوشش برای پلتفرم میزبان و نسخهٔ پایتون

می‌توانید یک گزارش پوشش برای پلتفرم و نسخهٔ پایتون خود تولید کنید. برای مثال، برای اجرای مجموعهٔ تست‌ها و تولید گزارش پوشش پایتون 3.10، اجرا کنید:

macOSLinuxWindows

(.venv) $ tox -m test310

(.venv) $ tox -m test310

(.venv) C:\...>tox -m test310

گزارش پوشش برای پلتفرم میزبان

اگر همه نسخه‌های پشتیبانی‌شدهٔ پایتون برای tox در دسترس باشند، می‌توان با اجرای زیر گزارش پوشش برای پلتفرم میزبان را تهیه کرد:

macOSLinuxWindows

(.venv) $ tox p -m test-platform

(.venv) $ tox p -m test-platform

(.venv) C:\...>tox p -m test-platform

گزارش پوشش در HTML

می‌توان با افزودن -html به هر یک از نام‌های محیط پوشش tox، یک گزارش پوشش HTML تولید کرد، برای مثال:

macOSLinuxWindows

(.venv) $ tox -e coverage-platform-html

(.venv) $ tox -e coverage-platform-html

(.venv) C:\...>tox -e coverage-platform-html

موضوع فقط نوشتن تست‌ها نیست!

اگرچه ما اطمینان حاصل می‌کنیم که تمام کدهایمان را تست می‌کنیم، اما این وظیفه صرفاً به حفظ آن سطح از تست محدود نمی‌شود. بخشی از این وظیفه، بازبینی کد در حین کار است. می‌توانید مجموعه‌ای جامع از تست‌ها برای یک جلیقه نجات واقعی بنویسید… اما آن جلیقه نجات واقعی همچنان برای هدفی که برای آن طراحی شده بود بی‌فایده خواهد بود!

در حین توسعهٔ تست‌ها، باید بررسی کنید که ماژول اصلی نیز از نظر درونی مطابق باشد. اگر متوجه نام متدهایی شدید که از نظر داخلی سازگار نیستند (مثلاً چیزی در یک ماژول با نام on_select و در ماژول دیگر با نام on_selected)، یا داده‌ها به‌طور یکسان پردازش نمی‌شوند، آن را علامت‌گذاری کرده و با ثبت یک تیکت به ما اطلاع دهید. یا اگر مطمئن هستید که می‌دانید چه کاری باید انجام شود، یک درخواست کش (pull request) ایجاد کنید که مشکل یافته‌شده را برطرف کند.

وقتی همه چیز به درستی کار کرد، می‌توانید یک درخواست کشش ارسال کنید با تغییرات خود.