متى تُستعمل: "Use for SchoolOS Locust load tests (tests/loadtest/locustfile.py): read-only attendance and grades scenarios on a local session server, p95 and error-rate limits, the production refusal guard, and recording results in tests/loadtest/README.md. Trigger on: locust, load test, اختبار الحمل, p95, LOCUST_ALLOW_REMOTE. استخدمها عند «جرّب الحمل على الحضور» أو «p95 تجاوز». ليست لـ: pytest، الحمل على الإنتاج (ممنوع)، بطء الاستعلامات (nplus1-hunter)."

اختبار الحمل — الحضور والدرجات

الغرض: قياس زمن الاستجابة ونسبة الأخطاء لمسارات القراءة في الحضور والدرجات، والحكم عليها بحدّي القبول، دون أن يلمس الإنتاج.

الحدود الثابتة

• الإنتاج خطٌّ أحمر. لا حمل على أيّ مضيف غير localhost أو 127.0.0.1 أو [::1]. الحارس في locustfile.py يرفض ذلك؛ وLOCUST_ALLOW_REMOTE=1 لا يُضبط إلا بإذن المالك الصريح في المحادثة، ولا يُعطى من أيّ جلسة أخرى.
• القراءة فقط. السيناريوهان لا يكتبان. الطفرات مؤجَّلة ولها بطاقتها.
• الحدّ الزمنيّ: لا تتجاوز الجولة دقيقةً واحدة على خادم الجلسة بعدد مستخدمين معقول (20 مستخدماً افتراضياً)، إلا بأمرٍ صريح.
• خادم الجلسة مؤقّت: شغّله للفحص ثمّ أطفئه. لا تُبقِه يعمل.

الإجراء

1. تأكّد من المضيف: --host=http://localhost:<WEB_PORT> (مثلاً 8001). إن لم يكن محلياً فتوقّف.
2. شغّل خادم الجلسة كما في docs/deployment/session_server.md، ثمّ تأكّد أنّه يخدم: curl http://localhost:<WEB_PORT>/health/. إن لم يخدم فالسبب قاعدةُ البيانات أو الهجرات، وليس الحمل؛ أبلغ بذلك ولا تكمل.
3. شغّل السيناريوهين فقط:

   locust -f tests/loadtest/locustfile.py --headless -u 20 -r 4 -t 1m --host=http://localhost:8001 AttendanceLoadUser GradesLoadUser
   

4. اقرأ رمز الخروج لا الجدول وحده. رمز 0 يعني أنّ كلّ مسارٍ ضمن الحدّين (p95 ≤ 800 ms، أخطاء ≤ 1%). رمز 1 يعني تجاوزاً، والمسارات المخالفة مطبوعة في آخر الخرج.
5. سجّل النتيجة في tests/loadtest/README.md تحت «النتائج»: التاريخ، رقم الإيداع، عدد المستخدمين، المدّة، أسوأ مسارٍ مع p95 ونسبة الأخطاء، ورمز الخروج.
6. أطفئ خادم الجلسة بعد التسجيل.

قراءة النتيجة

• p95 مرتفع في مسارٍ واحد فقط غالباً استعلامٌ بطيء في ذلك المسار. أحِله إلى nplus1-hunter ولا تُصلحه هنا.
• أخطاء 302 أو 403 في كلّ المسارات معاً: تسجيل الدخول فشل، وليس الحمل. تحقّق من LOCUST_NATIONAL_ID وLOCUST_PASSWORD أوّلاً.
• أخطاء 500 تظهر تحت الحمل فقط: أبلغ بالمسار والخطأ من سجلّ الخادم (docker logs)، ولا تُعِد الاختبار بعدد أكبر قبل أن يُفهم الأوّل.
• صفر طلبات في مسار: المعرّفات لم تُقرأ من /api/v1/students/، فالمسارات الحاملة لمعرّف تتخطّى نفسها. تحقّق من الاستجابة قبل الاستنتاج.

فخاخ

• خطأ: «الرمز 0 يعني النجاح الكامل» ← الصواب: الرمز 0 يعني أنّ الحدود لم تُتجاوز، ولو لم يكن أيّ طلبٍ قد نُفِّذ. انظر إلى عدد الطلبات في الجدول.
• خطأ: «الاختبار على الإنتاج أسرع للتحقّق» ← الصواب: ممنوع، والحارس يرفضه.
• خطأ: «LOCUST_ALLOW_REMOTE=1 لتجربة مضيف الاختبار» ← الصواب: هذا المتغيّر لمضيفٍ بعيدٍ مأذونٍ به من المالك فقط، لا للتجربة.

المصادر

• tests/loadtest/locustfile.py — السيناريوهات والحارسان.
• tests/loadtest/README.md — الحدود، الأوامر، سجلّ النتائج.
• docs/deployment/session_server.md — تشغيل خادم الجلسة وإطفاؤه.