DEV Community

Cover image for كيفية إضافة تفرع If/Else والتحكم في التدفق لسيناريوهات اختبار API في Apidog
Yusuf Khalidd
Yusuf Khalidd

Posted on • Originally published at apidog.com

كيفية إضافة تفرع If/Else والتحكم في التدفق لسيناريوهات اختبار API في Apidog

تعمل معظم اختبارات API كسلسلة خطية: تسجيل الدخول، ثم الدفع، ثم التحقق من الإيصال. لكن إذا فشل تسجيل الدخول برمز 401، فلن يكون تنفيذ طلب الدفع مفيدًا، وقد ينتج عنه فشل ثانٍ يخفي سبب المشكلة الحقيقي. الحل هو أن يقرأ السيناريو استجابة تسجيل الدخول، ويقرر هل يستمر أم ينتقل إلى مسار فشل واضح.

جرّب Apidog اليوم

هذا النوع من القرار هو تحكم في التدفق (Flow Control). في هذا الدليل ستبني تفرع if/else داخل سيناريو اختبار في Apidog: نفّذ تسجيل الدخول، تحقق من رمز الحالة، ثم نفّذ الدفع فقط إذا نجحت المصادقة. إذا كنت جديدًا على سيناريوهات Apidog، راجع كيفية كتابة سيناريو اختبار باستخدام Apidog. وللمفاهيم العامة، يقدم دليل MDN للعبارات الشرطية مقدمة مناسبة.

ما هو التحكم في التدفق؟

داخل وحدة Tests في Apidog، تنشئ سيناريو اختبار (Test Scenario) وتضيف إليه خطوات اختبار (Test Steps). يمكن أن تكون الخطوة:

واجهة التحكم في التدفق في Apidog

تسمح عناصر التحكم في التدفق للسيناريو باتخاذ قرارات بدل تنفيذ كل الطلبات بالترتيب نفسه. يركز هذا المقال على التفرع الشرطي (Conditional Branching)، وهو مكافئ if/else.

راجع وثائق Apidog حول التحكم في التدفق والتفرع الشرطي للتفاصيل الكاملة.

التفرع ليس حلقة.

التفرع يختار مسارًا مرة واحدة، بينما الحلقة تكرر مجموعة خطوات. لتكرار طلب عبر عناصر مصفوفة، استخدم ForEach كما في البرنامج التعليمي لحلقات ForEach.

بناء سيناريو: الدفع فقط بعد نجاح تسجيل الدخول

الهدف النهائي:

تسجيل الدخول
  └─ إذا كانت الحالة 200 → تنفيذ الدفع
  └─ وإلا → تسجيل الفشل أو إيقاف السيناريو
Enter fullscreen mode Exit fullscreen mode

الخطوة 1: إنشاء سيناريو اختبار

  1. افتح وحدة Tests في Apidog.
  2. انقر على + بجانب شريط البحث.
  3. أنشئ Test Scenario جديدًا.
  4. اختر الدليل والأولوية، ثم أكمل الإنشاء.

الخطوة 2: إضافة طلب تسجيل الدخول

أضف طلبًا مخصصًا كأول خطوة في السيناريو:

POST https://api.your-store.com/v1/login
Content-Type: application/json

{
  "email": "dana@example.com",
  "password": "correct-horse-battery-staple"
}
Enter fullscreen mode Exit fullscreen mode

شغّل الطلب منفردًا أولًا وتأكد من شكل الاستجابة. مثال لاستجابة ناجحة:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "userId": "usr_10482"
}
Enter fullscreen mode Exit fullscreen mode

الخطوة 3: الدخول إلى وضع التنظيم

انقر على أي خطوة للدخول إلى وضع التنظيم (Orchestrate Mode).

  • اللوحة اليسرى تعرض تدفق السيناريو.
  • اللوحة اليمنى تعرض إعدادات الخطوة المحددة.
  • لإعادة ترتيب الخطوات، اسحب أيقونة ≡.

الخطوة 4: إضافة تفرع شرطي

  1. انقر على إضافة خطوة (Add Step).
  2. اختر التفرع الشرطي (Conditional Branching).
  3. أنشئ شرطًا يعتمد على استجابة تسجيل الدخول.

في هذا السيناريو، الشرط المطلوب هو:

حالة استجابة تسجيل الدخول = 200
Enter fullscreen mode Exit fullscreen mode

تشمل عوامل المقارنة المتاحة في Apidog:

  • يساوي / لا يساوي
  • موجود / غير موجود
  • أقل من / أكبر من
  • يحتوي على / لا يحتوي على
  • يطابق باستخدام Regex
  • فارغ / ليس فارغًا
  • في القائمة / ليس في القائمة

الخطوة 5: قراءة بيانات خطوة تسجيل الدخول

لديك طريقتان لتمرير بيانات الاستجابة إلى الشرط.

الطريقة الأولى: Retrieve pre-step data

انقر داخل قيمة الشرط، ثم اختر أيقونة العصا السحرية، وبعدها:

Retrieve pre-step data
Enter fullscreen mode Exit fullscreen mode

ينشئ Apidog مرجعًا لبيانات خطوة سابقة بهذا الشكل:

{{$.<step id>.response.body.<field path>}}
Enter fullscreen mode Exit fullscreen mode

مثلًا، لقراءة token من الخطوة رقم 1:

{{$.1.response.body.token}}
Enter fullscreen mode Exit fullscreen mode

اختيار بيانات خطوة سابقة

ملاحظات مهمة:

  • تعمل هذه الطريقة داخل وحدة Tests فقط.
  • تُحل القيمة عند تشغيل السيناريو كاملًا، وليس عند تشغيل خطوة منفردة.
  • إذا ظهرت القيمة فارغة أثناء اختبار خطوة واحدة، شغّل السيناريو كاملًا.

الطريقة الثانية: استخراج متغير

إذا احتجت إلى استخدام القيمة في وحدات متعددة أو في عدة خطوات:

  1. افتح Post-processors لطلب تسجيل الدخول.
  2. أضف Extract Variable.
  3. استخدم JSONPath لاستخراج الحقل، مثل: 
$.token
Enter fullscreen mode Exit fullscreen mode
  1. احفظه باسم مثل token.
  2. استخدمه لاحقًا بهذه الصيغة: 
{{token}}
Enter fullscreen mode Exit fullscreen mode

راجع كيفية تمرير البيانات بين خطوات الاختبار لمزيد من التفاصيل.

الخطوة 6: إضافة مسار Else

مرر المؤشر فوق كتلة If ثم انقر على + Else.

رتب المسارين كالتالي:

  • داخل If: أضف طلب الدفع.
  • داخل Else: أضف خطوة تُظهر سبب الفشل بوضوح، مثل طلب تسجيل أو إشعار، أو تأكيد يفشل عمدًا.

مثال لطلب دفع يستخدم الرمز المستخرج:

POST https://api.your-store.com/v1/payments
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "amount": 2500,
  "currency": "USD"
}
Enter fullscreen mode Exit fullscreen mode

هذا النمط مشابه لاستخدام رؤوس المصادقة في وثائق Stripe API.

الآن أصبح منطق السيناريو واضحًا:

إذا نجح تسجيل الدخول → نفّذ الدفع
وإلا → أبلغ عن فشل تسجيل الدخول
Enter fullscreen mode Exit fullscreen mode

الخطوة 7: الحفظ والتشغيل

  1. انقر على حفظ الكل (Save All).
  2. شغّل السيناريو كاملًا.
  3. اختبر بيانات اعتماد صحيحة للتأكد من تنفيذ If.
  4. اختبر بيانات اعتماد خاطئة للتأكد من تنفيذ Else.

حالات عملية إضافية

التفرع بناءً على حقل في جسم الاستجابة

لا تقتصر الشروط على رمز الحالة. إذا أعادت API استجابة مثل:

{
  "status": "active",
  "role": "admin"
}
Enter fullscreen mode Exit fullscreen mode

يمكنك استخدام:

{{$.1.response.body.status}}
Enter fullscreen mode Exit fullscreen mode

ثم تطبيق شرط:

يساوي "active"
Enter fullscreen mode Exit fullscreen mode

أو اختبار دور المستخدم عبر عامل في القائمة:

["admin", "editor"]
Enter fullscreen mode Exit fullscreen mode

دمج التفرع مع ForEach

يمكنك وضع تفرع داخل حلقة ForEach لتخطي عناصر محددة، مثل المنتجات غير المتوفرة.

مراجع الحلقة تكون بالشكل التالي:

{{$.<loop step id>.index}}
{{$.<loop step id>.element.<field path>}}
Enter fullscreen mode Exit fullscreen mode

يبدأ index من 0. راجع البرنامج التعليمي لحلقات ForEach لتفاصيل الاستخدام.

مثال على تدفق يتضمن حلقة وتفرعًا

إيقاف الحلقة مبكرًا

استخدم Break If condition داخل الحلقة لإيقافها فور تحقق شرط معين. يمكنك إضافة العنصر أكثر من مرة داخل الحلقة عند الحاجة.

التعامل مع أخطاء الطلبات داخل الحلقات

تحتوي الحلقات على عنصر On Error ثابت. تحدد إعداداته ما يحدث عند فشل طلب داخل الحلقة:

  • Ignore: الانتقال إلى الطلب التالي.
  • Continue: تخطي بقية خطوات الدورة الحالية.
  • Break execution: إيقاف الحلقة ثم متابعة السيناريو بعدها.
  • End execution: إنهاء السيناريو كاملًا.

إضافة انتظار بين الخطوات

إذا كانت API تحتاج وقتًا لمعالجة عملية إنشاء قبل قراءتها، أضف خطوة Wait وحدد التأخير بالمللي ثانية.

استخدام القيم داخل السكريبتات

داخل سكريبتات ما قبل أو ما بعد المعالجة، لا تستخدم {{variable}} مباشرة. استخدم:

pm.variables.get("$.2.response.body.token")
Enter fullscreen mode Exit fullscreen mode

عدّل رقم الخطوة ومسار الحقل حسب السيناريو. للمزيد، راجع:

لا يمكن للسيناريو الإشارة إلى نفسه كسيناريو اختبار أصلي، لتجنب حلقات التنفيذ اللانهائية.

تشغيل السيناريو في CI باستخدام Apidog CLI

بعد بناء السيناريو، يمكنك تشغيله من سطر الأوامر داخل CI.

ثبّت الأداة وسجل الدخول:

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Enter fullscreen mode Exit fullscreen mode

شغّل السيناريو:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
Enter fullscreen mode Exit fullscreen mode

المعاملات الأساسية:

  • -t: معرف سيناريو الاختبار.
  • -e: معرف البيئة.
  • -r: نوع التقرير.

يمكنك استخدام أكثر من مُبلغ:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r html,cli
Enter fullscreen mode Exit fullscreen mode

أنواع التقارير المتاحة تشمل:

  • cli
  • html
  • junit

يُحل التفرع في CLI بالطريقة نفسها داخل التطبيق: يقرأ المشغل استجابة تسجيل الدخول، ثم ينفذ مسار If أو Else. راجع:

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

ما الفرق بين التفرع الشرطي والحلقة؟

التفرع يختار مسارًا مرة واحدة بناءً على شرط، مثل تنفيذ الدفع فقط بعد نجاح تسجيل الدخول. أما For وForEach فتكرران مجموعة خطوات.

لماذا تظهر قيمة Retrieve pre-step data فارغة؟

تأكد من أمرين:

  1. أنت تعمل داخل وحدة Tests.
  2. تشغّل السيناريو كاملًا، لا خطوة منفردة.

هل يمكن التفرع بناءً على حقل في جسم الاستجابة؟

نعم. استخدم مرجعًا مثل:

{{$.1.response.body.status}}
Enter fullscreen mode Exit fullscreen mode

أو استخرج القيمة إلى متغير ثم استخدم عامل مقارنة مناسبًا.

كيف أقرأ متغيرًا داخل سكريبت؟

استخدم:

pm.variables.get("$.2.response.body.token")
Enter fullscreen mode Exit fullscreen mode

بدلًا من صيغة {{variable}}.

هل توجد متطلبات خاصة لاستخدام التفرع؟

لا تذكر وثائق Apidog قيودًا خاصة على التحكم في التدفق أو التفرعات أو الحلقات أو تمرير البيانات، ولا تفرق هذه الميزات بين السحابة والاستضافة الذاتية.

الخلاصة

الاختبار الخطي يخبرك أن شيئًا فشل، لكن الاختبار المتفرع يحدد مكان الفشل ويمنع تنفيذ طلبات لاحقة لا يمكن أن تنجح. أضف Conditional Branching، اقرأ استجابة خطوة سابقة أو متغيرًا مستخرجًا، ثم اربط مساري If وElse.

بعد التحقق من السيناريو داخل التطبيق، شغّله في CI باستخدام apidog run للحفاظ على المنطق نفسه في خط الأنابيب. جرّب Apidog مجانًا وحوّل اختبارات API الخطية إلى سيناريوهات تتخذ قرارات فعلية.

Top comments (0)