الدرس 10 · الوحدة 5: التوثيق وتقارير النتائج

توثيق العيوب: تقرير الخطأ الجيّد

وجدتَ العيب؛ كيف تكتبه بحيث يُعاد إنتاجه ويُصلَح لا يُنسى؟ ⏱ نحو 35 دقيقة.

بعد هذا الدرس ستستطيع أن:

تعرف حقول تقرير الخطأ الجيّد.
تكتب خطوات إنتاج قابلة للتكرار.
تفصل المتوقَّع عن الفعلي.
تتحقّق من اكتمال التقرير آليًّا.

١العيب الذي لا يُوثَّق لا يُصلَح

وجدتَ عيبًا — ثم ماذا؟ العيب الذي تقوله شفهيًّا يُنسى. تقرير الخطأ Bug Report هو الوثيقة التي تنقل العيب إلى المطوّر بوضوحٍ يكفي ليُعيد إنتاجه ويصلحه. تقريرٌ غامض («لا يعمل!») يضيّع وقت الجميع.

الحقل	يجيب عن	مثال
العنوان	ما العيب باختصار؟	زرّ الدفع لا يستجيب على الجوّال
خطوات الإنتاج	كيف أراه بنفسي؟	1) افتح السلّة 2) اضغط دفع
المتوقَّع	ماذا يجب أن يحدث؟	تظهر صفحة الدفع
الفعلي	ماذا حدث فعلًا؟	لا شيء يحدث
البيئة	أين؟	Chrome على أندرويد 14
الشدّة	كم هو خطر؟	حرجة (يمنع الشراء)

أهمّ حقلٍ: خطوات الإنتاج. عيبٌ لا يستطيع المطوّر إعادة إنتاجه لا يُصلَح. ثم المتوقَّع مقابل الفعلي: يحدّد الخلل بدقّة.

٢من بلاغٍ غامض إلى تقرير

✗ خطأ

main.py

العنوان: مشكلةالوصف: الموقع خربان

✓ صواب

main.py

العنوان: الخصم لا يُطبَّق على السلّةالخطوات: 1) أضف منتجًا 50ر 2) أدخل كود GET10المتوقَّع: السعر 45الفعلي: السعر 50 (لم يُطبَّق)البيئة: Chrome 120

اليمين قابل لإعادة الإنتاج والإصلاح؛ اليسار مجرّد شكوى.

نمثّل التقرير بنيةً نتحقّق من اكتمالها آليًّا — تمامًا كما نتحقّق من صحّة أيّ بيانات:

main.py

REQUIRED = ["title", "steps", "expected", "actual", "severity"] def is_complete(bug):    "تقرير مكتمل إن وُجدت كل الحقول المطلوبة وليست فارغة"    return all(bug.get(f) for f in REQUIRED) good = {"title": "الخصم لا يُطبَّق", "steps": "1) ... 2) ...",        "expected": "45", "actual": "50", "severity": "عالية"}bad  = {"title": "مشكلة", "actual": "لا يعمل"} print("التقرير الجيّد مكتمل؟", is_complete(good))print("التقرير الغامض مكتمل؟", is_complete(bad))

Shell×

>>> %Run main.py

التقرير الجيّد مكتمل؟ True

التقرير الغامض مكتمل؟ False

>>>

٣قابلية إعادة الإنتاج أوّلًا

التقرير الجيّد جزءٌ من ضمان الجودة لا هامشٌ عليه: فريق التطوير يقيس جودته بعدد العيوب القابلة لإعادة الإنتاج مقابل الغامضة.

توقّع وتحقّق

أهمّ حقلٍ في تقرير الخطأ:

التقرير الجيّد يذكر المتوقَّع و:

عيبٌ لا يُعاد إنتاجه:

«يحدث أحيانًا» تقرير:

الخلاصة

العيب الذي لا يُوثَّق بوضوحٍ لا يُصلَح؛ تقرير الخطأ ينقله للمطوّر كاملًا.
الحقول الأساسية: عنوان، خطوات إنتاج، متوقَّع، فعليّ، بيئة، شدّة.
أهمّها خطوات الإنتاج: عيبٌ لا يُعاد إنتاجه يصعب إصلاحه.
اسعَ لأصغر شرطٍ يُظهر العيب، وأرفق دليلًا (لقطة/سجلّ).

تحدٍّ برمجي: تحقّق من التقرير

متوسط

أكمل missing_fields لتعيد قائمة الحقول المطلوبة الناقصة أو الفارغة في تقرير خطأ، ثم اطبعها لتقريرٍ ناقص.

المطلوب:

الحقول المطلوبة: title, steps, expected, actual.
اطبع قائمة الناقص للتقرير المعطى.

ابدأ من هذا الكود، واضغط ▶ شغّل هنا لتكتب حلّك وتجرّبه مباشرة:

main.py

REQUIRED = ["title", "steps", "expected", "actual"]def missing_fields(bug):    # أعِد قائمة الحقول المطلوبة الغائبة أو الفارغة    passbug = {"title": "زر معطّل", "actual": "لا شيء"}print(missing_fields(bug))

المطلوب×

['steps', 'expected']

💡 تلميح 1

[f for f in REQUIRED if not bug.get(f)].

💡 تلميح 2

bug.get(f) يكون فارغًا أو None للحقل الناقص.

حاول بنفسك أولًا؛ للمسألة أكثر من حلّ صحيح.

main.py

REQUIRED = ["title", "steps", "expected", "actual"]def missing_fields(bug):    return [f for f in REQUIRED if not bug.get(f)]bug = {"title": "زر معطّل", "actual": "لا شيء"}print(missing_fields(bug))

انتقل إلى تقييم الدرساختيار من متعدد، وصح وخطأ، وأكمل الفراغ، وتتبّع الناتج.ابدأ التقييم ←

📝 معلم؟ أرسل ملاحظة للمؤلف عن هذا الدرس