تجري معظم اختبارات الـ API بخط مستقيم. استدعاء تسجيل الدخول، استدعاء الدفع، استدعاء نقطة نهاية الإيصال، والتأكيد على طول الطريق. هذا يعمل بشكل جيد حتى تفشل خطوة بطريقة تعتمد عليها الخطوة التالية. إذا أعاد تسجيل الدخول رمز 401، فإن تشغيل طلب الدفع لا طائل منه. والأسوأ من ذلك، أنه يخفي الفشل الحقيقي وراء فشل ثانٍ مضلل. ما تريده هو اختبار يقرأ استجابة تسجيل الدخول، ويقرر ما إذا كان سيستمر، ويبلغ عن الحقيقة حول مكان حدوث الخلل.
هذا القرار هو منطق شرطي، وتبنيه باستخدام التحكم في التدفق. يوضح لك هذا الدليل كيفية إضافة تفرع if/else إلى سيناريو اختبار API في Apidog بحيث يمكن للتشغيل أن يتفرع بناءً على استجابة سابقة. ستقوم ببناء سيناريو حقيقي: تسجيل الدخول، التحقق من رمز الحالة، والمتابعة إلى الدفع فقط عندما ينجح تسجيل الدخول بالفعل. إذا كنت جديدًا في سيناريوهات Apidog، فإن الإرشادات التفصيلية حول كيفية كتابة سيناريو اختبار باستخدام Apidog تغطي الأساسيات الخطية التي يبني عليها هذا المقال. لتعريف نمط التفرع نفسه، فإن دليل MDN للعبارات الشرطية هو مقدمة جيدة. يمكنك تنزيل Apidog والمتابعة مجانًا.
ما هو التحكم في التدفق، وما هو ليس كذلك
في Apidog، توجد الاختبارات الآلية في وحدة الاختبارات (Tests). الوحدة التي تعمل بها هي سيناريو اختبار (Test Scenario)، والذي تصفه الوثائق بأنه مماثل للمجموعة (Collection) في Postman. داخل السيناريو، تقوم بترتيب خطوات الاختبار (Test Steps): كل خطوة إما أن تكون طلبًا فرديًا أو عنصر تحكم في التدفق مثل تفرع (branch) أو حلقة (loop) أو تأخير (delay).
التحكم في التدفق هو مجموعة عناصر التحكم في التدفق. إنه يتيح للسيناريو أن يفعل أكثر من مجرد المرور عبر الطلبات بالترتيب. تعتبر وثائق Apidog حول التحكم في التدفق والتفرع الشرطي هي المرجع وراء كل تسمية مستخدمة هنا. العنصر الذي يركز عليه هذا المقال هو التفرع الشرطي (Conditional Branching)، وهو اسم Apidog لـ if/else. يقرأ التفرع قيمة تعطيه إياها، ويختبر تلك القيمة مقابل شرط، ويشغل مجموعة واحدة من الخطوات عندما يتحقق الشرط ومجموعة أخرى عندما لا يتحقق.
توضيح مسبق، لأن الاثنين غالبًا ما يختلطان. التفرع ليس تكرارًا (looping). يقرر التفرع مرة واحدة ما إذا كانت كتلة من الخطوات ستعمل. بينما تشغل الحلقة كتلة عدة مرات. لدى Apidog ميزات منفصلة للتكرار، تسمى حلقات For وحلقات ForEach، وهي تنتمي إلى مشكلة مختلفة: تكرار نفس الطلب عبر نطاق أو عبر العناصر في مصفوفة. إذا كنت بحاجة إلى المرور عبر مصفوفة من معرفات الطلبات، فهذه حلقة ForEach، كما هو موضح في البرنامج التعليمي لحلقات ForEach، وليست تفرعًا. يركز هذا الدليل على if/else.
لا تذكر وثائق Apidog أي قيود مجانية مقابل مدفوعة على التحكم في التدفق، أو التفرع الشرطي، أو الحلقات، أو تمرير البيانات بين الخطوات. كما لا يوجد تمييز بين السحابة مقابل الاستضافة الذاتية لهذه الميزات. إذا كان بإمكانك بناء سيناريو، يمكنك إضافة تفرع إليه.
بناء سيناريو يتفرع بناءً على استجابة تسجيل الدخول
هنا الهدف. يقوم المستخدم بتسجيل الدخول. إذا أعادت نقطة نهاية تسجيل الدخول رمز 200، فإن السيناريو يستمر لإنشاء عملية دفع. وإذا أعادت أي شيء آخر، يتوقف السيناريو ويبلغ عن الفشل بدلاً من التظاهر بأن الدفع قد تم.
الخطوة 1: إنشاء سيناريو الاختبار
افتح Apidog وانتقل إلى وحدة الاختبارات (Tests). انقر على `+` بجانب شريط البحث لإنشاء سيناريو اختبار جديد، واختر الدليل الذي يجب أن يوجد فيه، وحدد أولوية لإكمال الإنشاء. لديك الآن سيناريو فارغ جاهز للخطوات.
الخطوة 2: إضافة طلب تسجيل الدخول كخطوة أولى
أضف خطوة الاختبار الأولى. يوفر لك Apidog عدة طرق لإضافة طلب: استيراده من مواصفات نقطة نهاية موجودة، استيراده من حالة نقطة نهاية محفوظة، إضافة طلب مخصص مباشرة، أو إضافة طلب من سلسلة cURL. لبدء سريع، أضف طلبًا مخصصًا. اضبطه على POST ووجهه إلى نقطة نهاية المصادقة الخاصة بك مع جسم JSON:
POST https://api.your-store.com/v1/login
Content-Type: application/json
{
"email": "dana@example.com",
"password": "correct-horse-battery-staple"
}
قم بتشغيل هذه الخطوة مرة واحدة بمفردها للتأكد من أنها تُرجع ما تتوقعه. تسجيل الدخول الناجح يُرجع رمز 200 ورمزًا مميزًا (token) في الجسم، شيء من هذا القبيل:
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"userId": "usr_10482"
}
الخطوة 3: الدخول إلى وضع التنظيم (orchestrate mode)
انقر على أي خطوة للدخول إلى وضع التنظيم. تعرض اللوحة اليسرى التدفق العام للسيناريو؛ وتعرض اللوحة اليمنى تفاصيل أي خطوة قمت بتحديدها. هذا العرض المقسم هو المكان الذي تقوم فيه بترتيب التفرع. إذا احتجت في أي وقت إلى إعادة ترتيب الخطوات، اسحب الأيقونة `≡` على خطوة لتحريكها.
الخطوة 4: إضافة التفرع الشرطي
انقر على زر `إضافة خطوة` (Add Step). هذه هي الطريقة الأساسية لإدراج أي عنصر تحكم في التدفق. من القائمة، اختر `التفرع الشرطي` (Conditional Branching). يؤدي ذلك إلى إنشاء عبارة If، وهي تفرع فارغ ينتظر شرطًا وبعض الخطوات لتشغيلها.
الآن قم ببناء الشرط. تحتاج إلى إدخال رمز حالة استجابة تسجيل الدخول في التفرع. يبني Apidog الشروط من مجموعة ثابتة من عوامل التشغيل (judgment operators). القائمة الكاملة هي: يساوي (Equals)، لا يساوي (Does not equal)، موجود (Exists)، غير موجود (Does not exist)، أقل من (Less than)، أقل من أو يساوي (Less than or equal)، أكبر من (Greater than)، أكبر من أو يساوي (Greater than or equal)، يطابق باستخدام Regex (Matches with Regex)، يحتوي على (Contains)، لا يحتوي على (Does not contain)، فارغ (Is empty)، ليس فارغًا (Is not Empty)، في القائمة (In List)، وليس في القائمة (Not in List).
لهذا التفرع، تريد أن يكون رمز حالة تسجيل الدخول يساوي 200. لذلك يقرأ الشرط: حالة استجابة تسجيل الدخول `يساوي` `200`.
الخطوة 5: الإشارة إلى الاستجابة السابقة في الشرط
للحصول على نتيجة تسجيل الدخول في حقل الشرط، لديك طريقتان.
الطريقة الأولى لا تحتاج إلى إعداد. انقر داخل حقل قيمة الشرط وانقر على أيقونة العصا السحرية، ثم حدد `استرداد بيانات الخطوة السابقة` (Retrieve pre-step data). يتيح لك Apidog الإشارة مباشرة إلى خطوة تسجيل الدخول السابقة واستخراج قيمة من استجابتها. يستخدم هذا تحت الغطاء مرجعًا قبل الخطوة مع بناء الجملة `{{$.<step id>.response.body.<field path>}}`. إذا أردت الرمز المميز (token) من جسم تسجيل الدخول بدلاً من الحالة، على سبيل المثال، ستشير إلى `{{$.1.response.body.token}}`، حيث `1` هو معرف خطوة تسجيل الدخول.
شيئان يجب معرفتهما حول `استرداد بيانات الخطوة السابقة` (Retrieve pre-step data). يعمل فقط في وحدة الاختبارات (Tests)، وليس في وحدة واجهات برمجة التطبيقات (APIs). ويتم حله فقط عند تشغيل السيناريو بالكامل، وليس عند تشغيل خطوة واحدة بشكل منفصل. إذا بدا مرجع ما قبل الخطوة فارغًا أثناء تشغيل فردي، فهذا متوقع؛ قم بتشغيل السيناريو بالكامل وسيمتلئ.
الطريقة الثانية تستخدم متغيرًا مُسمى وتعمل في كل من وحدتي الاختبارات (Tests) وواجهات برمجة التطبيقات (APIs). في طلب تسجيل الدخول، افتح معالجاته اللاحقة (post-processors) وأضف إجراء `استخراج متغير` (Extract Variable). استخرج الحقل الذي تهتم به باستخدام تعبير JSONPath، على سبيل المثال `$.token`، ويقوم Apidog بتخزينه تحت اسم. يمكنك بعد ذلك الإشارة إليه في أي مكان لاحقًا كـ `{{token}}`. هذا هو النهج الأكثر قابلية للنقل عندما تريد نفس القيمة متاحة عبر الوحدات أو في عدة تفرعات. يتم تغطية الآليات الأعمق لتحريك القيم بين الخطوات في الدليل حول كيفية تمرير البيانات بين خطوات الاختبار.
بالنسبة لتفرع رمز الحالة، فإن `استرداد بيانات الخطوة السابقة` (Retrieve pre-step data) على حالة خطوة تسجيل الدخول هو أقصر طريق.
الخطوة 6: إضافة تفرع "إلا" (Else)
مرر المؤشر فوق كتلة If وانقر على `+ Else`. يمنحك ذلك المسار البديل الذي يتم تشغيله عندما يكون الشرط خاطئًا، مما يعني أن تسجيل الدخول لم يُرجع 200.
الآن املأ كلا الجانبين:
- داخل كتلة If، أضف طلب الدفع كخطوة اختبار. هذا هو المسار الناجح. يتم تشغيله فقط عندما يُرجع تسجيل الدخول 200. إذا كان الدفع يحتاج إلى رمز تسجيل الدخول المميز (login token)، فاشر إليه هنا باستخدام `{{token}}` (إذا قمت باستخراجه) أو بمرجع ما قبل الخطوة إلى جسم تسجيل الدخول. غالبًا ما يحمل استدعاء الدفع الحقيقي رمز مميز للحامل (bearer token) في رأس `Authorization`، وهو نفس النمط الذي تستخدمه وثائق Stripe API للطلبات المصادق عليها.
- داخل كتلة Else، أضف خطوة تجعل الفشل واضحًا. الخيار الشائع هو طلب إلى نقطة نهاية تسجيل أو إشعارات، أو طلب مخصص مع تأكيد يفشل دائمًا بحيث يبرز تقرير السيناريو هذا التشغيل بوضوح.
السيناريو الخاص بك يقرأ الآن كمنطق واضح: إذا كان تسجيل الدخول يساوي 200، قم بتشغيل عملية الدفع؛ وإلا، أبلغ وتوقف.
الخطوة 7: حفظ
انقر على `حفظ الكل` (Save All) لحفظ السيناريو. تظهر التغييرات غير المحفوظة مؤشر نقطة، لذا إذا رأيت تلك النقطة، فلا يزال لديك عمل للكتابة. قم بتشغيل السيناريو بالكامل وشاهد التفرع يتم حله. وجه تسجيل الدخول إلى بيانات اعتماد صالحة وتعمل كتلة If. وجهه إلى بيانات اعتماد خاطئة وتعمل كتلة Else بدلاً من ذلك.
التنوعات والتحكم المتقدم في التدفق
بمجرد أن يعمل التفرع الأساسي، تغطي نفس اللبنات الكثير من الاحتمالات.
- تفرع بناءً على حقل الجسم، وليس فقط الحالة. رموز الحالة هي الحالة الشائعة، ولكن الشروط تقرأ أي قيمة يمكنك الإشارة إليها. افترض أن تسجيل الدخول الخاص بك يُرجع `200` حتى لحساب مغلق، مع وجود الحالة الحقيقية في حقل `status`. استرد `{{$.1.response.body.status}}` واستخدم عامل التشغيل `يساوي` (Equals) مقابل `\"active\"`، أو استخدم `يحتوي على` (Contains) مقابل سلسلة رسالة. تمنحك قائمة عوامل التشغيل أيضًا فحوصات النطاق: `أكبر من` (Greater than) على رصيد مُعاد، `في القائمة` (In List) لاختبار ما إذا كان الدور المُعاد هو أحد القيم المسموح بها المتعددة.
- اجمع التفرع مع الحلقات. يتكون التفرع والتكرار معًا. داخل حلقة ForEach على مصفوفة من معرفات المنتجات، يمكن لخطوة التفرع الشرطي تخطي المنتجات غير المتوفرة ومعالجة الباقي. يبدأ مرجع فهرس الحلقة `{{$.<loop step id>.index}}` من 0، وعنصر ForEach هو `{{$.<loop step id>.element.<field path>}}`. الحلقات هي موضوع بحد ذاته؛ يتناول البرنامج التعليمي لحلقات ForEach هذا الموضوع بشكل صحيح.
- إيقاف حلقة مبكرًا باستخدام Break If. عند التكرار، ينهي عنصر `Break If condition` الحلقة بمجرد تحقيق الشرط. يمكنك سحبه لإعادة وضعه وإضافته أكثر من مرة في الحلقة.
- التعامل مع الأخطاء باستخدام On Error. تحمل الحلقات عنصر `On Error` ثابتًا في بداية الحلقة، ولا يمكنك نقله. تحدد خياراته ما يحدث عندما يحدث خطأ في طلب داخل الحلقة: `تجاهل` (Ignore) يتابع مع الطلب التالي، `متابعة` (Continue) يتخطى بقية طلبات الدورة الحالية، `إيقاف التنفيذ` (Break execution) يوقف الحلقة ويستمر بعدها، و `إنهاء التنفيذ` (End execution) يوقف السيناريو بأكمله.
- إضافة انتظار بين الخطوات. أحيانًا تحتاج خدمة تالية إلى فترة قبل أن تعكس عملية كتابة. يضيف عنصر `انتظار` (Wait) تأخيرًا يُقاس بالمللي ثانية، وهو مفيد بين استدعاء إنشاء والقراءة التي تتحقق منه.
- الإشارة إلى القيم داخل السكريبتات. إذا كان التفرع يحتاج إلى منطق معقد للغاية لقائمة عوامل التشغيل، يمكن لسكريبت ما قبل المعالجة أو ما بعد المعالجة حسابه. داخل السكريبت، لا يمكنك استخدام صيغة `{{variable}}` مباشرة. استخدم `pm.variables.get("$.2.response.body.token")` بدلاً من ذلك، مع مطابقة معرف الخطوة ومسار الحقل الذي تريده. للنمط الأوسع لسلسلة الطلبات بحيث يغذي أحدهما الآخر، راجع الدليل حول سلسلة الطلبات والمقالة الأعمق حول تنسيق اختبارات API وتمرير البيانات.
ملاحظة حول الإشارة الذاتية: لا يمكن للسيناريو الإشارة إلى سيناريو الاختبار الأصلي نفسه. يمنع هذا الحماية حلقات لا نهائية عرضية عند تداخل السيناريوهات.
أتمتة سير العمل باستخدام Apidog CLI
السيناريو الذي بنيته للتو لا يجب أن يعمل داخل التطبيق فقط. يشحن Apidog أداة تشغيل سطر أوامر تنفذ السيناريوهات المحفوظة بدون واجهة رسومية، وهو بالضبط ما تريده في CI (التكامل المستمر). قم بتثبيته وتسجيل الدخول:
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
ثم قم بتشغيل سيناريو التفرع الخاص بك بالمعرف، ووجهه إلى بيئة واختر مُبلغًا (reporter):
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
هنا `-t` هو معرف سيناريو الاختبار، و `-e` هو معرف البيئة، و `-r` هو المُبلغ. استخدم `cli` لإخراج وحدة التحكم، أو `html` و `junit` للملفات التي يمكن لخط أنابيبك نشرها؛ افصلها بفاصلة مثل `-r html,cli` لإصدار عدة مخرجات في وقت واحد. يتم حل التفرع بنفس الطريقة التي يتم بها في التطبيق: يقرأ المُشغل استجابة تسجيل الدخول، يأخذ مسار If أو Else، ويعكس رمز الخروج النتيجة بحيث يؤدي تسجيل الدخول الفاشل إلى فشل البناء. الإعداد الكامل موجود في دليل تثبيت Apidog CLI، وتوصيله بخط أنابيب مغطى في دليل Apidog CLI GitHub Actions. إذا كنت تفضل تشغيل نفس السيناريو على مؤقت بدلاً من كل عملية التزام (commit)، فراجع كيفية جدولة اختبارات API في Apidog.
الأسئلة الشائعة
ما الفرق بين التفرع الشرطي والحلقة في Apidog؟
يقرر التفرع الشرطي مرة واحدة ما إذا كانت كتلة من الخطوات ستعمل، بناءً على شرط. بينما تشغل الحلقة كتلة بشكل متكرر. استخدم التفرع عندما يكون لديك قرار إما/أو، مثل المتابعة إلى الدفع فقط إذا نجح تسجيل الدخول. استخدم حلقة For أو ForEach عندما تحتاج إلى تكرار طلب عبر عدد معين أو مصفوفة. يغطي البرنامج التعليمي لحلقات ForEach التكرار بالكامل.
لماذا يعود مرجع `استرداد بيانات الخطوة السابقة` (Retrieve pre-step data) فارغًا؟
سببان شائعان. أولاً، يعمل `استرداد بيانات الخطوة السابقة` (Retrieve pre-step data) فقط في وحدة الاختبارات (Tests)، وليس في وحدة واجهات برمجة التطبيقات (APIs). ثانيًا، يتم حله فقط عند تشغيل سيناريو الاختبار بالكامل. إذا قمت بتشغيل خطوة واحدة بشكل منفصل، فلن يكون للمرجع شيء يشير إليه بعد. قم بتشغيل السيناريو بالكامل وسيمتلئ القيمة.
هل يمكنني التفرع بناءً على حقل داخل جسم الاستجابة، وليس فقط رمز الحالة؟
نعم. أشر إلى الحقل بتعبير ما قبل الخطوة مثل `{{$.1.response.body.status}}` أو استخرجه في متغير مُسمى، ثم اختر عامل تشغيل مثل `يساوي` (Equals)، `يحتوي على` (Contains)، أو `في القائمة` (In List). أي قيمة يمكنك الإشارة إليها يمكن أن تدفع شرطًا. يتم تغطية نقل هذه القيم في كيفية تمرير البيانات بين خطوات الاختبار.
كيف أستخدم متغيرًا داخل سكريبت بدلاً من منشئ الشروط؟
لا تقبل السكريبتات صيغة `{{variable}}` مباشرة. استخدم `pm.variables.get("$.2.response.body.token")` في سكريبت ما قبل المعالجة أو ما بعد المعالجة، مع مطابقة معرف الخطوة ومسار الحقل الذي تريده.
هل يتطلب التفرع تكلفة إضافية، أو يتطلب النسخة المستضافة ذاتيًا؟
لا تذكر وثائق Apidog أي قيود على الخطط للتحكم في التدفق، أو التفرع الشرطي، أو الحلقات، أو تمرير البيانات، ولا تمييز بين السحابة مقابل الاستضافة الذاتية لهذه الميزات. إذا كان بإمكانك بناء سيناريو، يمكنك إضافة تفرعات إليه.
الخلاصة
يخبرك الاختبار الخطي أن شيئًا ما قد تعطل. بينما يخبرك الاختبار المتفرع أين حدث ذلك، ويوقف إهدار الخطوات على مسار لا يمكن أن ينجح بعد الآن. أضف خطوة تفرع شرطي، وزودها باستجابة سابقة باستخدام `استرداد بيانات الخطوة السابقة` (Retrieve pre-step data) أو متغير مستخرج، وقم بتوصيل If و `+ Else`، وسيقوم السيناريو الخاص بك الآن باتخاذ القرارات بالطريقة التي تعمل بها واجهة برمجة التطبيقات (API) الحقيقية الخاصة بك. عندما يعمل في التطبيق، فإن أمر `apidog run` واحد ينقل نفس المنطق إلى CI. جرب Apidog مجانًا، بدون الحاجة إلى بطاقة ائتمان، وحول اختباراتك الخطية إلى سيناريوهات تفكر.