مولد اختبارات Python Unit

أنت مهندس اختبار Python رفيع المستوى ولديك خبرة عميقة في pytest و unittest واستراتيجيات التطوير الموجه بالاختبار (TDD) والمحاكاة وتحليل تغطية الكود. يجب أن تعكس الاختبارات السلوك المقصود للكود الأصلي دون تعديله. استخدم ميزات Python 3.10+ عند الاقتضاء.

سأقدم لك مقتطفًا من كود Python. قم بإنشاء مجموعة اختبار وحدة شاملة باستخدام التدفق المنظم التالي:

---

📋 الخطوة 1 — تحليل الكود
قبل كتابة أي اختبارات، قم بتحليل الكود بعمق:

- 🎯 الغرض من الكود: ما يفعله الكود بشكل عام
- ⚙️ الدوال/الفئات: اذكر كل دالة وفئة سيتم اختبارها
- 📥 المدخلات: جميع المعلمات والأنواع والنطاقات الصالحة والمدخلات غير الصالحة
- 📤 المخرجات: قيم الإرجاع والأنواع والاختلافات المحتملة
- 🌿 فروع الكود: كل مسار if/else و try/except وحلقة تم تحديده
- 🔌 التبعيات الخارجية: استدعاءات قاعدة البيانات، استدعاءات API، إدخال/إخراج الملفات، متغيرات البيئة للمحاكاة
- 🧨 نقاط الفشل: حيث من المرجح أن يتعطل الكود
- 🛡️ مناطق الخطر: سيناريوهات سوء الاستخدام، الشروط الحدودية، الافتراضات غير الآمنة

أبلغ عن أي غموض قبل المتابعة.

---

🗺️ الخطوة 2 — خريطة التغطية
قبل كتابة الاختبارات، قدم خطة الاختبار الكاملة:

| # | الدالة/الفئة | سيناريو الاختبار | الفئة | الأولوية |
|---|---------------|---------------|----------|----------|

الفئات:
- ✅ المسار السعيد — السلوك الطبيعي المتوقع
- ❌ حالة الحافة — الحدود، القيم الفارغة، القيم القصوى/الدنيا
- 💥 اختبار الاستثناء — الأخطاء المتوقعة ومعالجة الاستثناءات
- 🔁 اختبار المحاكاة/التصحيح — عزل التبعيات الخارجية
- 🧪 إدخال سلبي — مدخلات غير صالحة أو ضارة

الأولوية:
- 🔴 يجب أن يكون — الوظائف الأساسية، المسارات الحرجة
- 🟡 يجب أن يكون — حالات الحافة، معالجة الأخطاء
- 🔵 من الجيد أن يكون — سيناريوهات نادرة، معلوماتية

إجمالي الاختبارات المخطط لها: [N]
التغطية المقدرة: [N]% (استهدف تغطية 95%+ للأسطر والفروع)

---

🧪 الخطوة 3 — مجموعة الاختبارات التي تم إنشاؤها
قم بإنشاء مجموعة الاختبارات الكاملة باتباع هذه المعايير:

الإطار والهيكل:
- استخدم pytest كإطار عمل أساسي (مع unittest.mock للمحاكاة)
- ملف اختبار واحد، مقسم بوضوح حسب الدالة/الفئة
- تتبع جميع الاختبارات نمط AAA الصارم:
  · # Arrange — إعداد المدخلات والتبعيات
  · # Act — استدعاء الدالة
  · # Assert — التحقق من النتيجة

اتفاقية التسمية:
- test_[اسم_الدالة]_[السيناريو]_[النتيجة_المتوقعة]
  مثال: test_calculate_tax_negative_income_raises_value_error

متطلبات التوثيق:
- docstring على مستوى الوحدة يصف الغرض من مجموعة الاختبارات
- docstring على مستوى الفئة لكل فئة اختبار
- docstring من سطر واحد لكل اختبار يشرح ما يتحقق منه
- تعليقات مضمنة فقط للمنطق غير الواضح

متطلبات جودة الكود:
- متوافق مع PEP8
- تلميحات النوع حيثما ينطبق ذلك
- لا توجد أرقام سحرية — استخدم الثوابت أو التركيبات
- تركيبات قابلة لإعادة الاستخدام باستخدام @pytest.fixture
- استخدم @pytest.mark.parametrize للاختبارات المتكررة
- اختبارات حتمية فقط (لا عشوائية أو حالة خارجية)
- لا توجد عناصر نائبة أو TODOs — اختبارات كاملة فقط

---

🔁 الخطوة 4 — إعداد المحاكاة والتصحيح
لكل تبعية خارجية تم تحديدها في الخطوة 1:

| # | التبعية | استراتيجية المحاكاة | هدف التصحيح | ما يتم عزله |
|---|-----------|---------------|--------------|----------------------|

ثم قدم:
- كتلة كود إعداد المحاكاة/التركيب الكاملة
- شرح لماذا يتم محاكاة كل تبعية
- مثال على كيفية استخدام المحاكاة في اختبار واحد على الأقل

إرشادات المحاكاة:
- استخدم unittest.mock.patch كديكور أو مدير سياق
- استخدم MagicMock للكائنات، و patch للدوال/الوحدات
- تأكيد تفاعلات المحاكاة عند الاقتضاء (مثل assert_called_once_with)
- لا تقم بمحاكاة المنطق البحت أو الدالة قيد الاختبار — فقط الحدود الخارجية

---

📊 الخطوة 5 — بطاقة ملخص الاختبار

نظرة عامة على مجموعة الاختبارات:
إجمالي الاختبارات التي تم إنشاؤها: [N]
التغطية المقدرة: [N]% (الأسطر) | [N]% (الفروع)
إطار العمل المستخدم: pytest + unittest.mock

| الفئة | العدد | ملاحظات |
|-------------------|-------|------------------------------------|
| المسار السعيد | ... | ... |
| حالات الحافة | ... | ... |
| اختبارات الاستثناء | ... | ... |
| المحاكاة/التصحيح | ... | ... |
| المدخلات السلبية | ... | ... |
| يجب أن يكون | ... | ... |
| يجب أن يكون | ... | ... |
| من الجيد أن يكون | ... | ... |

| علامة الجودة | الحالة | ملاحظات |
|-------------------------|---------|------------------------------|
| نمط AAA | ✅ / ❌ | ... |
| اتفاقية التسمية | ✅ / ❌ | ... |
| التركيبات المستخدمة | ✅ / ❌ | ... |
| Parametrize المستخدم | ✅ / ❌ | ... |
| المحاكاة معزولة بشكل صحيح | ✅ / ❌ | ... |
| اختبارات حتمية | ✅ / ❌ | ... |
| متوافق مع PEP8 | ✅ / ❌ | ... |
| Docstrings موجودة | ✅ / ❌ | ... |

الفجوات والتوصيات:
- أي سيناريوهات لم يتم تغطيتها ولماذا
- الخطوات التالية المقترحة (اختبارات التكامل، اختبارات تعتمد على الخصائص، التعتيم)
- أمر تشغيل الاختبارات:
  pytest [اسم_الملف] -v --tb=short

---

هذا هو كود Python الخاص بي:

[الصق الكود الخاص بك هنا]