كتابة الكود وتشغيله واختباره¶
سيتطلب إصلاح خطأ أو تنفيذ ميزة ما كتابة بعض الأكواد الجديدة.
للبدء في العمل على الكود، تأكد من إعداد بيئة التطوير، وأنك تعمل على فرع
لدينا دليل أسلوب كتابة الكود الذي يحدد إرشاداتنا الخاصة بكتابة الكود لـ BeeWare.
التطوير القائم على الاختبار¶
من الطرق الجيدة للتأكد من أن الكود الخاص بك سيؤدي الغرض المطلوب منه، أن تبدأ أولاً بكتابة حالة اختبار للتحقق من ذلك. ومن المفترض أن تفشل حالة الاختبار هذه في البداية، لأن الكود الذي تختبره غير موجود بعد. يمكنك بعد ذلك إجراء التعديلات اللازمة على الكود لإنجاح الاختبار، وبذلك تتأكد من أن ما قمت بكتابته يحل المشكلة التي تتوقع حلها.
قم بتشغيل الكود الخاص بك¶
بمجرد الانتهاء من كتابة الكود، عليك التأكد من أنه يعمل. ستحتاج إلى تشغيل الكود يدويًّا للتحقق من أنه يؤدي الوظيفة التي تتوقعها. وإذا لم تكن قد قمت بذلك بعد، فمن المستحسن أن تكتب حالة اختبار للتغييرات التي أجريتها؛ وكما ذكرنا سابقًا، يجب أن يفشل هذا الاختبار إذا كان الكود معطلاً أو غير موجود.
ستقوم بإضافة حالة الاختبار الخاصة بك إلى مجموعة الاختبارات، بحيث يمكن تشغيلها جنبًا إلى جنب مع الاختبارات الأخرى. والخطوة التالية هي تشغيل مجموعة الاختبارات.
تشغيل الاختبارات والتغطية¶
يستخدم BeeWare tox لإدارة عملية
الاختبار وpytest لمجموعة الاختبارات
الخاصة به.
يتضمن الأمر الافتراضي tox تنفيذ ما يلي:
- خطافات ما قبل الالتزام
towncrierالتحقق من ملاحظات الإصدار-
فحص الأخطاء في الوثائق
-
مجموعة الاختبارات لإصدارات Python المتاحة
-
تقارير تغطية الكود
هذا هو ما تقوم به CI بشكل أساسي عند إرسال طلب سحب.
لتشغيل مجموعة الاختبارات الكاملة، قم بتنفيذ:
(.venv) $ tox
(.venv) $ tox
(.venv) C:\...>tox
قد يستغرق تشغيل مجموعة الاختبارات الكاملة بعض الوقت. يمكنك تسريع العملية بشكل
كبير عن طريق تشغيل tox بشكل متوازٍ، وذلك بتشغيل tox p (أو tox
run-parallel). عند تشغيل مجموعة الاختبارات بشكل متوازٍ، ستحصل على قدر أقل من
المعلومات حول تقدم المجموعة أثناء تشغيلها، لكنك ستحصل مع ذلك على ملخص لأي مشكلات
تم اكتشافها في نهاية عملية الاختبار. ومن المفترض أن تحصل على بعض النتائج التي
تشير إلى أن الاختبارات قد تم تشغيلها. قد ترى اختبارات SKIPPED، ولكن لا ينبغي
أن تحصل أبدًا على أي نتائج اختبار FAIL أو ERROR. نقوم بتشغيل مجموعة
الاختبارات الكاملة قبل دمج كل تصحيح. إذا اكتشفت تلك العملية أي مشاكل، فإننا لا
ندمج التصحيح. إذا وجدت خطأً أو فشلًا في الاختبار، فإما أن هناك شيئًا غريبًا في
بيئة الاختبار الخاصة بك، أو أنك وجدت حالة استثنائية لم نرها من قبل - في كلتا
الحالتين، أخبرنا بذلك!
بالإضافة إلى نجاح الاختبارات، من المفترض أن يُظهر هذا تغطية اختبار بنسبة 100٪.
تشغيل الاختبارات المختلفة¶
إجراء اختبارات على إصدارات متعددة من لغة Python¶
بشكل افتراضي، ستحاول العديد من أوامر tox تشغيل مجموعة الاختبارات عدة مرات، مرة
لكل إصدار من إصدارات Python التي يدعمها BeeWare. ولكن للقيام بذلك، يجب
أن تكون كل إصدارات Python مثبتة على جهازك ومتاحة لعملية [اكتشاف]tox Python
الخاصة بـ
(https://virtualenv.pypa.io/en/latest/explanation.html#python-discovery). وبشكل
عام، إذا كان إصدار ما من Python متاحًا عبر PATH، فيجب أن يتمكن tox من العثور
عليه واستخدامه.
تشغيل مجموعة الاختبارات فقط¶
إذا كنت تعمل على تطوير ميزة جديدة بوتيرة سريعة، فلست بحاجة إلى تشغيل مجموعة الاختبارات بالكامل؛ بل يمكنك تشغيل فقط اختبارات الوحدة. للقيام بذلك، قم بتشغيل:
(.venv) $ tox -e py
(.venv) $ tox -e py
(.venv) C:\...>tox -e py
تشغيل مجموعة فرعية من الاختبارات¶
بشكل افتراضي، يقوم tox بتشغيل جميع الاختبارات الموجودة في مجموعة الاختبارات
الوحدوية. عند تطوير اختبار جديد، قد يكون من المفيد تشغيل هذا الاختبار فقط.
للقيام بذلك، يمكنك تمرير أي محدد
pytest
كحجة إلى tox. مسارات الاختبارات هذه نسبية بالنسبة إلى دليل briefcase. على
سبيل المثال، لتشغيل الاختبارات الموجودة في ملف واحد فقط، قم بتشغيل:
(.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
ستظل تحصل على تقرير التغطية عند تشغيل جزء من مجموعة الاختبارات - لكن نتائج التغطية ستقتصر على سطور الكود التي تم تنفيذها من خلال الاختبارات المحددة التي قمت بتشغيلها.
تشغيل مجموعة الاختبارات لإصدار معين من لغة Python¶
بشكل افتراضي، سيتم تشغيل tox -e py باستخدام أي مترجم يتم تحديده على جهازك. إذا
كان لديك عدة إصدارات من Python مثبتة، وترغب في اختبار إصدار معين من بين
الإصدارات المثبتة، فيمكنك تحديد إصدار Python المراد استخدامه. على سبيل المثال،
لتشغيل مجموعة الاختبارات على Python python, قم بتشغيل:
(.venv) $ tox -e py310
(.venv) $ tox -e py310
(.venv) C:\...>tox -e py310
يمكن تشغيل مجموعة فرعية من الاختبارات عن طريق إضافة -- ومواصفات
الاختبار إلى سطر الأوامر.
تشغيل مجموعة الاختبارات دون تغطية (بسرعة)¶
بشكل افتراضي، سيقوم tox بتشغيل مجموعة اختبارات pytest في وضع الخيط الواحد.
يمكنك تسريع تنفيذ مجموعة الاختبارات عن طريق تشغيلها بشكل متوازٍ. لا ينتج عن هذا
الوضع ملفات تغطية بسبب التعقيدات التي تنطوي عليها عملية تسجيل التغطية داخل
العمليات التي تم إنشاؤها. لتشغيل إصدار واحد من Python في الوضع "السريع"، قم
بتشغيل:
(.venv) $ tox -e py-fast
(.venv) $ tox -e py-fast
(.venv) C:\...>tox -e py-fast
يمكن تشغيل مجموعة فرعية من الاختبارات عن طريق إضافة -- ومواصفات
الاختبار إلى سطر الأوامر؛ ويمكن استخدام إصدار معين من Python
عن طريق إضافة الإصدار إلى هدف الاختبار (على سبيل المثال، py310-fast للتشغيل السريع على Python 3.10).
تغطية الكود¶
يضمن BeeWare تغطية بنسبة 100% لجميع الفروع في قاعدة الكود. عند إضافة كود أو تعديله في المشروع، يجب عليك إضافة كود اختباري لضمان تغطية أي تغييرات تجريها.
ومع ذلك، يستهدف BeeWare منصات متعددة، بالإضافة إلى إصدارات متعددة من
لغة Python، لذا لا يمكن التحقق من التغطية الكاملة على منصة واحدة وإصدار واحد من
Python. ولتحقيق ذلك، تم تعريف عدة قواعد تغطية شرطية في قسم
tool.coverage.coverage_conditional_plugin.rules من pyproject.toml (على سبيل
المثال، يمكن استخدام no-cover-if-is-windows لتمييز كتلة من الكود لن يتم
تنفيذها عند تشغيل مجموعة الاختبارات على Windows). تُستخدم هذه القواعد لتحديد
أجزاء الكود التي يتم تغطيتها فقط على منصات معينة أو إصدارات Python معينة.
وتجدر الإشارة إلى أن تقارير التغطية قد تكون غير دقيقة بعض الشيء عبر إصدارات Python المختلفة. فعلى سبيل المثال، إذا تم إنشاء ملفات التغطية باستخدام إصدار معين من Python، بينما تم إعداد تقرير التغطية باستخدام إصدار آخر، فقد يتضمن التقرير نتائج إيجابية خاطئة تتعلق بالفروع التي لم يتم تغطيتها. ولهذا السبب، ينبغي أن تستخدم تقارير التغطية دائمًا أقدم إصدار من Python تم استخدامه لإنشاء ملفات التغطية.
فهم نتائج التغطية¶
في نهاية مخرجات اختبار التغطية، يجب أن يظهر تقرير ببيانات التغطية التي تم جمعها:
الاسم البيانات الفروع المفقودة نسبة المشاركة التغطية المفقود
---------------------------------------------------
المجموع 7540 0 1040 0 100.0%
هذا يدل على أن مجموعة الاختبارات قد نفذت كل مسار فرعي ممكن في الكود. وهذا لا يضمن بنسبة 100٪ عدم وجود أخطاء، ولكنه يعني أننا نختبر كل سطر من سطور الكود في قاعدة الكود.
إذا أجريت تغييرات على قاعدة الكود، فمن المحتمل أن تتسبب في حدوث فجوة في التغطية.
وعندما يحدث ذلك، سيُعلمك تقرير التغطية بالأسطر التي لم يتم تنفيذها. على سبيل
المثال، لنفترض أننا أجرينا تغييرًا على 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%
هذا يشير إلى أن السطر 170، والأسطر من 302 إلى 307، والانتقال من السطر 320 إلى السطر 335، لا يتم تنفيذها من قِبل مجموعة الاختبارات. ستحتاج إلى إضافة اختبارات جديدة (أو تعديل اختبار موجود) لاستعادة هذه التغطية.
تقرير التغطية الخاص بالمنصة المضيفة وإصدار لغة Python¶
يمكنك إنشاء تقرير تغطية لمنصة Python وإصدارها. على سبيل المثال، لتشغيل مجموعة الاختبارات وإنشاء تقرير تغطية على Python 3.10, قم بتشغيل:
(.venv) $ tox -m test310
(.venv) $ tox -m test310
(.venv) C:\...>tox -m test310
تقرير التغطية الخاص بالمنصة المضيفة¶
إذا كانت جميع إصدارات Python المدعومة متاحة لـ tox, فيمكن الإبلاغ عن التغطية
الخاصة بمنصة المضيف عن طريق تشغيل:
(.venv) $ tox p -m test-platform
(.venv) $ tox p -m test-platform
(.venv) C:\...>tox p -m test-platform
تقرير التغطية بتنسيق HTML¶
يمكن إنشاء تقرير تغطية HTML بإضافة -html إلى أي من أسماء بيئات التغطية tox،
على سبيل المثال:
(.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) يعمل على إصلاح المشكلة التي اكتشفتها.
بمجرد أن تصبح كل شيء جاهزًا للعمل، يمكنك إرسال طلب سحب مع التغييرات التي أجريتها.