توكيدات API: دليل عملي للتحقق من صحة الاستجابات

طلب واجهة برمجة تطبيقات (API) يعيد استجابة ليس اختبارًا ناجحًا. إنه مجرد استجابة. يوجد الاختبار فقط عندما يتحقق شيء ما من أن الاستجابة صحيحة. هذا التحقق هو تأكيد، وجودة تأكيداتك هي التي تحدد ما إذا كانت مجموعة اختباراتك تكتشف الأخطاء الحقيقية أم أنها فقط تؤكد أن الخادم يعمل.

يشرح هذا الدليل ماهية تأكيدات واجهة برمجة التطبيقات (API)، وأنواعها التي تستحق الكتابة، وأين تخطئ الفرق في تطبيقها، وكيفية بناء التأكيدات بصريًا في Apidog دون الحاجة إلى كتابة سكربتات.

ما هو تأكيد واجهة برمجة التطبيقات (API)

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

بدون التأكيدات، يثبت الاختبار الآلي فقط أن نقطة النهاية (endpoint) قابلة للوصول. بوجودها، يثبت أن نقطة النهاية صحيحة. الفجوة بين هذين الأمرين هي حيث تحدث معظم حوادث الإنتاج: كانت واجهة برمجة التطبيقات تعمل، وأعادت رمز 200، ولكن محتوى الجسم (body) كان خاطئًا.

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

تأكيد رمز الحالة، ولماذا لا يكفي

التحقق الأكثر شيوعًا هو تأكيد رمز حالة HTTP: توقع 200 للقراءة الناجحة، 201 للمورد الذي تم إنشاؤه، 400 للمدخلات السيئة، 401 لغياب المصادقة. هذا ضروري. إن الحصول على رموز الحالة بشكل صحيح هو انضباط بحد ذاته؛ رموز حالة HTTP التي يجب أن تستخدمها واجهات برمجة تطبيقات REST يستحق القراءة إذا كانت واجهة برمجة تطبيقاتك غير متناسقة هنا.

لكن تأكيد رمز الحالة وحده ضعيف. يمكن لواجهة برمجة التطبيقات أن تعيد 200 OK مع جسم فارغ، أو قيمة قديمة، أو قيمة خالية حيث يجب أن يكون هناك كائن، أو رسالة خطأ متنكرة في هيئة نجاح. تشير الحالة إلى أن الطلب تمت معالجته. لكنها لا تقول شيئًا عما إذا كانت البيانات صحيحة.

تعامل مع تأكيد الحالة كخط أول في خطوة الاختبار، وليس الخط الوحيد أبدًا.

أنواع التأكيدات التي تستحق الكتابة

تأكيدات محتوى الجسم. تحقق من القيم الفعلية في الاستجابة. حقل id موجود وغير فارغ. حقل email يطابق ما أرسلته. حقل total يساوي مجموع عناصر البنود. هذه التأكيدات تكتشف الأخطاء المنطقية التي لا تكتشفها رموز الحالة.

تأكيدات المخطط (Schema). تحقق من شكل الاستجابة مقابل مخطط JSON أو تعريف OpenAPI: الحقول المطلوبة موجودة، الأنواع صحيحة، لم تظهر حقول غير متوقعة. تكتشف تأكيدات المخطط انحراف العقد، حيث يغير الواجهة الخلفية (backend) بهدوء حقلًا من سلسلة نصية إلى كائن ويكسر كل عميل. يتداخل هذا مع اختبار عقد API، والذي يضفي الطابع الرسمي على الفكرة بين المنتج والمستهلك.

تأكيدات الرأس (Header). تأكد من أن Content-Type هو application/json، وأن رؤوس التخزين المؤقت (caching headers) مضبوطة كما هو مقصود، وأن رؤوس CORS موجودة، وأن رؤوس الأمان مثل Strict-Transport-Security موجودة.

تأكيدات وقت الاستجابة. حدد ميزانية زمن انتقال (latency budget)، مثلاً 800 مللي ثانية، وأفشل الاختبار عندما تكون الاستجابة أبطأ. تراجعات الأداء غير مرئية لأنواع التأكيدات الأخرى، لذا فإن هذا هو الوحيد الذي يكتشفها في مجموعة اختبارات وظيفية.

تأكيدات شكل الخطأ. للحالات السلبية، أكد جسم الخطأ، وليس مجرد رمز 4xx. حقل error يساوي validation_error، ومصفوفة details تسمي الحقل المخالف، ولا تتسرب أي بيانات حساسة في الرسالة.

تأكيدات الأمان. تأكد من أن نقطة النهاية ترفض الطلبات بدون رمز مميز (token)، وترفض الرموز المميزة المنتهية الصلاحية، وتفرض التفويض بين المستخدمين، ولا تعيد حمولات الحقن (injection payloads) غير مهربة.

خطوة اختبار تؤكد الحالة، وحقلين أو ثلاثة من حقول الجسم، والمخطط، وميزانية وقت الاستجابة، تقوم بعمل حقيقي. أما الخطوة التي تؤكد الحالة فقط فهي مجرد زخرفة.

أين تخطئ منطق التأكيدات

الإفراط في التأكيد على البيانات المتقلبة. التأكيد على طابع زمني created_at دقيق أو معرف UUID مُنشأ يجعل الاختبار يفشل في كل مرة دون سبب. أكد أن الحقل موجود وله النوع الصحيح، وليس قيمته الدقيقة.

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

التأكيدات المعتمدة على الترتيب. إذا كان التأكيد B لا معنى له إلا عند نجاح التأكيد A، ولكن كلاهما يعمل بشكل أعمى، فإن الفشل في A ينتج عنه فشل ثانٍ مربك في B. قم بتنظيم الخطوات بحيث تكون التبعيات واضحة.

تأكيد واحد يؤدي وظيفتين. "الاستجابة صحيحة" ليست تأكيدًا. قسّمها: الحالة هي 200، token موجود، expires_in يساوي 3600. ثلاثة تحققات، ثلاث رسائل فشل واضحة.

تجاهل الحالات السلبية. تؤكد الفرق بشدة على النجاح وبصعوبة على الفشل. حالة سلبية بدون تأكيد للجسم تثبت فقط أن واجهة برمجة التطبيقات قالت "لا"، وليس أنها قالت "لا" بشكل صحيح.

بناء التأكيدات في Apidog

في Apidog، تعد التأكيدات جزءًا من منشئ الاختبار المرئي، لذا يمكنك تعريفها بالنقر بدلاً من كتابة السكربتات.

لأي طلب في سيناريو الاختبار، افتح لوحة التأكيد وأضف التحققات:

1. تأكيد الحالة. حدد "حالة الاستجابة" واضبطها لتساوي 200.
2. تأكيدات حقل الجسم. استخدم تعبير JSONPath مثل $.token وأكد أنه موجود وأنه سلسلة نصية غير فارغة؛ أكد أن $.expires_in يساوي 3600. يقرأ Apidog بنية الاستجابة، لذا يمكنك اختيار الحقول بدلاً من كتابة المسارات بشكل أعمى.
3. تأكيد المخطط. تحقق من الاستجابة مقابل المخطط المحدد لنقطة النهاية. نظرًا لأن Apidog يحتفظ بتصميم واجهة برمجة التطبيقات والاختبارات في مساحة عمل واحدة، فإن المخطط الذي يستخدمه تأكيدك هو نفس المخطط الذي تنشره وثائقك؛ لا توجد نسخة ثانية قد تنحرف.
4. تأكيد وقت الاستجابة. أضف تحققًا من أن وقت الاستجابة أقل من ميزانيتك.
5. سكربت مخصص، عند الحاجة فقط. للمنطق الذي لا يمكن للتحققات المرئية التعبير عنه، انتقل إلى معالج JavaScript اللاحق. معظم التأكيدات لا تحتاج إلى هذا أبدًا.

قم بتجميع التأكيدات عبر سيناريو واحد ويقوم Apidog بتشغيلها معًا. لتغطية قابلة للتطوير، أرفق ملف بيانات بحيث يتم تشغيل مجموعة تأكيد واحدة مقابل كل صف من مدخلات الاختبار المعتمدة على البيانات. عند تشغيل السيناريو، يعرض التقرير الذي تم إنشاؤه بدقة أي تأكيد فشل، وعلى أي طلب، مع عرض القيم المتوقعة والفعلية جنبًا إلى جنب.

يتم تشغيل نفس السيناريو دون تغيير في CI، لذا يعيد كل التزام (commit) فحص كل تأكيد؛ أتمتة اختبارات API في CI/CD تغطي هذا الربط. حمّل Apidog لبناء مجموعة تأكيد مقابل نقطة النهاية الخاصة بك.

مجموعة تأكيدات مطبقة

لنأخذ GET /users/{id} التي تعيد كائن مستخدم. إليك مجموعة تأكيدات قوية للمسار السعيد:

• الحالة تساوي 200
• رأس Content-Type يحتوي على application/json
• $.id يساوي المعرف المطلوب
• $.email موجود ويطابق نمط بريد إلكتروني
• $.role هو أحد القيم admin أو member أو viewer
• جسم الاستجابة يتوافق مع مخطط User
• وقت الاستجابة أقل من 600 مللي ثانية

وبالنسبة لـ GET /users/{id} بمعرف غير معروف:

• الحالة تساوي 404
• $.error يساوي not_found
• جسم الاستجابة لا يحتوي على email أو id أو أي حقول مستخدم أخرى

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

التأكيدات في مسار CI

تكتسب التأكيدات قيمتها الكاملة عندما تعمل تلقائيًا. فمجموعة اختبار يديرها شخص يدويًا مرة واحدة في الأسبوع تكتشف الأخطاء متأخرة بأسبوع. بينما نفس المجموعة المدمجة في CI تكتشفها عند طلب السحب (pull request).

عندما تعمل التأكيدات في مسار CI، يهم خياران تصميميان. أولاً، يجب أن يكون الفشل واضحًا لا لبس فيه. سجل CI الذي يقول "فشل الاختبار" يجبر المطور على إعادة إنتاج التشغيل محليًا؛ أما سجل يقول "كان من المتوقع أن يساوي $.expires_in القيمة 3600، ولكن حصلنا على 7200 في POST /auth/login" يخبرهم أين يبحثون فورًا. التأكيدات القوية والمحددة هي التي تنتج هذا الفشل الواضح.

ثانيًا، يجب أن تكون التأكيدات مستقرة عبر البيئات المختلفة. فالتأكيد الذي يقوم بتضمين معرف مستخدم إنتاجي ثابت سيفشل في بيئة الاختبار (staging) لسبب لا علاقة له بالكود. احتفظ بالقيم الخاصة بالبيئة في متغيرات، وأكد على البنية والنوع حيث تعتمد القيمة الدقيقة على البيئة. تأكيد المخطط ينتقل جيدًا بين البيئات؛ أما التأكيد على معرف مُنشأ محدد فلا ينتقل.

النمط العملي: أكد الحالة والمخطط على كل نقطة نهاية كخط أساس يعمل في كل مكان، ثم أضف فوق ذلك تأكيدات القيمة المدركة للبيئة. يكتشف خط الأساس انحراف العقد في أي بيئة؛ وتكتشف تأكيدات القيمة الأخطاء المنطقية حيث تتوفر لديك بيانات مستقرة. قم بتشغيل كليهما مع كل التزام (commit) وتصبح مجموعة الاختبار بوابة بدلاً من مجرد تقرير.

الأسئلة المتكررة

ما الفرق بين التأكيد وحالة الاختبار؟ حالة الاختبار هي التحقق الكامل: طلب بالإضافة إلى نتيجته المتوقعة. التأكيدات هي المقارنات الفردية داخلها التي تحدد النجاح أو الفشل. راجع كيفية كتابة حالات اختبار API.

كم عدد التأكيدات التي يجب أن يحتوي عليها الطلب الواحد؟ بما يكفي لتغطية الحالة، وحقول الجسم الرئيسية، والمخطط، وميزانية زمن الانتقال. بالنسبة لمعظم نقاط النهاية، يتراوح العدد من أربعة إلى ثمانية. والمزيد لا بأس به إذا كان كل تأكيد يتحقق من شيء مميز.

هل يجب علي تأكيد أجسام الاستجابة الدقيقة؟ أكد الحقول المستقرة بدقة والحقول المتقلبة حسب النوع أو الوجود. إن التأكيد على جسم كامل يتضمن الطوابع الزمنية والمعرفات المُنشأة يؤدي إلى إنشاء اختبارات تفشل في كل مرة تشغيل.

هل يمكنني تأكيد أداء API في اختبار وظيفي؟ نعم. تأكيد وقت الاستجابة يكتشف تراجعات زمن الانتقال أثناء التشغيل الوظيفي العادي، ولا يلزم اختبار تحميل منفصل للتحقق من الميزانية الأساسية.

هل يجب أن تحتوي حالات الاختبار السلبية على تأكيدات أيضًا؟ قطعًا، وهي الحالات التي غالبًا ما تُترك فارغة. حالة سلبية مع التحقق من رمز الحالة فقط تثبت أن واجهة برمجة التطبيقات قالت "لا"، وليس أنها قالت "لا" بشكل صحيح. أكد على حقل الخطأ، وتفاصيل الحقل المخالف، وغياب أي بيانات حساسة في الرسالة.

أين يجب استخدام سكربتات التأكيد المخصصة؟ خصص السكربتات للمنطق الذي لا يمكن لمنشئ الواجهة المرئية التعبير عنه: المقارنات عبر الطلبات، القيم المشتقة، أو التحققات الشرطية التي تعتمد على استجابات سابقة. معظم التأكيدات، مثل الحالة والمخطط وحقول الجسم والتوقيت، تكون أوضح وأسهل للمراجعة كتحققات مرئية.