كيف تكتب تقرير خطأ (Bug Report)

ما الذي يحتويه تقرير الخطأ الجيد

• العنوان — العَرَض في سطر واحد محدد: «إتمام الشراء يعيد 500 عندما تحتوي السلة على منتج مخفّض» أفضل من «إتمام الشراء معطّل».
• البيئة — إصدار التطبيق أو البناء، والمتصفح/نظام التشغيل أو الجهاز، وبيئة API (اختبار أو إنتاج)، والحساب أو الدور المستخدم.
• الشروط المسبقة — ما يجب أن يكون صحيحاً قبل الخطوات: مستخدم مسجّل الدخول ولديه منتجات في السلة، أو علم ميزة محدد.
• خطوات إعادة الإنتاج — مرقّمة وقليلة ودقيقة. ضمّن البيانات التي استخدمتها (أو ما يعادلها مولّداً) والطلب إذا كان خطأ في API.
• النتيجة المتوقعة — ما كان ينبغي أن يحدث، ويفضّل مع إشارة إلى المتطلب أو التصميم.
• النتيجة الفعلية — ما حدث بدلاً من ذلك، منقولاً بدقة: الرسالة، ورمز الحالة، والقيمة الخاطئة.
• الأدلة — لقطة شاشة أو تسجيل، وطلب HTTP واستجابته، وأسطر من سجل وحدة التحكم أو الخادم، وتتبّع المكدس.
• التكرار — دائماً، أو متقطع (كم مرة)، أو عند أول تحميل فقط.
• الخطورة والأولوية — مدى سوء الخطأ ومدى سرعة وجوب إصلاحه (انظر أدناه).

جرّبها: مولّد وصف الأخطاء بالذكاء الاصطناعي جرّبها: مولّد عناوين الأخطاء بالذكاء الاصطناعي

نموذج تقرير خطأ

Title:        Checkout returns 500 when the cart contains a discounted item
Environment:  Web app 4.12.0 · Chrome 128 / Windows 11 · staging · customer role
Severity:     Major        Priority: High        Frequency: Always

Preconditions:
  - Logged in as a verified customer
  - Cart contains one item with an active 20% discount (SKU A-100)

Steps to reproduce:
  1. Open /checkout
  2. Select "Card" as the payment method
  3. Click "Place order"

Expected result:
  Order is created (201), confirmation page shows the discounted total 199.20

Actual result:
  Page shows "Something went wrong". POST /api/v1/orders returns 500:
  {"error":{"code":"INTERNAL","requestId":"9f1c…"}}

Evidence:
  - screenshot-checkout-500.png
  - request/response captured (attached)
  - server log: TypeError: cannot read "rate" of undefined (discount.ts:41)

Notes:
  Works when the cart has no discounted item. Started after release 4.12.0.

جرّبها: مولّد وصف الأخطاء بالذكاء الاصطناعي جرّبها: فاحص طلبات HTTP

الخطورة مقابل الأولوية

تقيس الخطورة (Severity) الأثر على النظام أو المستخدم: ما مقدار ما تعطّل ولمن. وتقيس الأولوية (Priority) الإلحاح بالنسبة للعمل: متى يجب إصلاحه مقارنةً بالأعمال الأخرى. يحددهما أشخاص مختلفون وكثيراً ما يختلفان.

خطأ إملائي في اسم الشركة على صفحة تسجيل الدخول خطورته تافهة لكن أولويته عالية. وانهيار في تقرير إداري يعمل مرة كل ربع سنة خطورته عالية لكن أولويته منخفضة حتى ينتهي الربع. وتسجيل الاثنين، كلٌّ على حدة، هو ما يتيح للفريق التخطيط بصدق.

• الخطورة — حاجب (لا حل بديل، والمسار الأساسي غير قابل للاستخدام)، وحرج (فقدان بيانات، أو أمان، أو فشل دفع)، ورئيسي (الميزة معطّلة مع وجود حل بديل)، وثانوي (شكلي أو حالة حدّية)، وتافه.
• الأولوية — قصوى / عالية (إصلاح قبل الإصدار أو الآن)، ومتوسطة (السبرنت القادم)، ومنخفضة (قائمة الانتظار).

جرّبها: اقتراح خطورة الخطأ بالذكاء الاصطناعي جرّبها: اقتراح أولوية الخطأ بالذكاء الاصطناعي

قبل الإبلاغ: اعزل الخطأ

• أعد إنتاجه مرتين. إذا حدث مرة واحدة فسجّله كمتقطع ودوّن ما اختلف.
• قلّل الخطوات إلى الحد الأدنى الذي ما زال يسببه. أزل كل ما لا يغيّر النتيجة.
• غيّر متغيراً واحداً في كل مرة — متصفح مختلف، أو حساب مختلف، أو بيانات مختلفة — لإيجاد المحفّز.
• تحقق مما إذا كان مبلَّغاً عنه مسبقاً: ابحث في المتتبّع عن رسالة الخطأ ونقطة النهاية.
• التقط الأدلة وهي على الشاشة: الطلب، والاستجابة، ووحدة التحكم، والرسالة بنصها.

جرّبها: محلّل رسائل الأخطاء بالذكاء الاصطناعي جرّبها: محلّل استجابات API

الأخطاء التي تجعل التقارير تُعاد

• لا خطوات، بل وصف للعَرَض فقط.
• «لا يعمل» كنتيجة فعلية، دون رسالة أو رمز أو لقطة شاشة.
• عدة أخطاء في تقرير واحد — كل خطأ يحتاج إلى دورة حياته الخاصة.
• رأي في العنوان («هذا فظيع») بدلاً من العَرَض.
• بيانات عملاء حقيقية ملصقة في التقرير. استخدم بيانات اختبار مولّدة تعيد إنتاج الشكل نفسه.
• بيئة ناقصة — الخطأ الذي يظهر فقط على Safari في iOS يهدر يوماً كاملاً إن لم يُذكر ذلك.

جرّبها: مصنع بيانات الاختبار

الإبلاغ عن أخطاء API

في عيوب API، إعادة الإنتاج هي الطلب نفسه. ضمّن الطريقة وعنوان URL والترويسات (مع حجب الرموز) والجسم، والاستجابة الكاملة — الحالة والترويسات والجسم — ومعرّف الطلب إن كانت الواجهة تعيده. وأمر cURL هو الشكل الأكثر قابلية للنقل: يستطيع المطوّر لصقه ورؤية الفشل فوراً.

جرّبها: فاحص طلبات HTTP جرّبها: مولّد أوامر cURL

الأسئلة الشائعة