كيفية كتابة حالات اختبار API: نموذج ومثال

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

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

ما هي حالة اختبار واجهة برمجة التطبيقات (API) حقًا

حالة اختبار واجهة برمجة التطبيقات (API) هي مجموعة محددة من المدخلات والإجراءات والنتائج المتوقعة المستخدمة للتأكد من أن نقطة نهاية معينة تعمل بشكل صحيح تحت شرط محدد واحد. إنها أضيق من سيناريو الاختبار. يقول السيناريو "تحقق من تسجيل دخول المستخدم". بينما تقول حالة الاختبار "أرسل بيانات اعتماد صالحة إلى /auth/login وتأكد من استجابة 200 مع رمز JWT في الجسم خلال 800 مللي ثانية".

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

عادةً ما يغطي اختبار واجهة برمجة التطبيقات (API) خمس زوايا، ويجب أن تتوزع حالاتك عليها جميعًا:

• وظيفي: هل تعيد نقطة النهاية البيانات الصحيحة للمدخلات الصالحة؟
• سلبي: هل ترفض المدخلات الخاطئة بالخطأ ورمز الحالة الصحيحين؟
• الأداء: هل تستجيب ضمن ميزانية زمنية مقبولة؟
• الأمان: هل تفرض المصادقة والتفويض وحدود الإدخال؟
• العقد: هل تتطابق الاستجابة مع المخطط الموثق؟

مجموعة اختبار تتحقق فقط من المسار الإيجابي (happy path) ستنجح حتى يرسل مستخدم حقيقي حقلاً فارغًا لكلمة المرور.

لماذا تحتاج إلى قالب حالة اختبار

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

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

تجعل القوالب أيضًا الأتمتة واقعية. تتطابق الحالة المنظمة بشكل نظيف مع خطوة اختبار مؤتمتة؛ أما الحالة الغامضة فيجب إعادة كتابتها قبل أن تتمكن الآلة من تشغيلها.

بنية حالة اختبار واجهة برمجة تطبيقات قوية

يحمل قالب حالة اختبار واجهة برمجة تطبيقات كامل هذه الحقول. لا تحتاجها جميعًا لكل حالة، ولكن المجموعة الأساسية غير قابلة للتفاوض.

الحقول التي تتجاهلها الفرق غالبًا هي وقت الاستجابة المتوقع وجسم الاستجابة المتوقع. تجاهلها هو كيف "ينجح" الاختبار بينما يعيد 200 مع حمولة فارغة، أو حمولة صحيحة متأخرة بثلاث ثوانٍ.

كيفية كتابة حالات اختبار واجهة برمجة التطبيقات (API) خطوة بخطوة

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

اكتب قائمة بالشروط التي تستحق الاختبار. لنقطة نهاية واحدة، يعني هذا عادةً: مدخلات صالحة، كل حقل مطلوب مفقود، كل حقل خاطئ التكوين، طلب غير مصرح به، رمز مميز منتهي الصلاحية، وحمولة زائدة عن الحد. يصبح كل شرط حالة اختبار واحدة.

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

اكتب النتيجة المتوقعة بدقة. "يعيد نجاحًا" ليس تأكيدًا. "يعيد 200، يحتوي الجسم على سلسلة token غير فارغة، expires_in يساوي 3600" هو كذلك. الدقة هنا هي ما يجعل الحالة تستحق التشغيل.

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

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

مثال عملي: اختبار نقطة نهاية تسجيل الدخول

خذ نقطة نهاية مصادقة قياسية: POST /auth/login، والتي تقبل بريدًا إلكترونيًا وكلمة مرور وتُرجع JWT. إليك أربع حالات تغطيها بشكل صحيح.

AUTH-LOGIN-001: بيانات اعتماد صالحة (وظيفية، حرجة)

• نقطة النهاية: POST /auth/login
• الشروط المسبقة: يوجد مستخدم بالبريد الإلكتروني dana@example.com
• الجسم: {"email": "dana@example.com", "password": "Correct-Horse-9"}
• الحالة المتوقعة: 200
• الاستجابة المتوقعة: يحتوي الجسم على token (سلسلة) غير فارغ، token_type يساوي Bearer، expires_in يساوي 3600
• وقت الاستجابة المتوقع: أقل من 800 مللي ثانية

AUTH-LOGIN-002: كلمة مرور خاطئة (سلبية، حرجة)

• الجسم: {"email": "dana@example.com", "password": "wrong"}
• الحالة المتوقعة: 401
• الاستجابة المتوقعة: error يساوي invalid_credentials؛ لا يوجد حقل token
• ملاحظة: يجب ألا تكشف الرسالة ما إذا كان البريد الإلكتروني موجودًا أم لا

AUTH-LOGIN-003: حقل كلمة المرور مفقود (سلبية، عالية)

• الجسم: {"email": "dana@example.com"}
• الحالة المتوقعة: 400
• الاستجابة المتوقعة: error يساوي validation_error؛ details يحدد حقل password

AUTH-LOGIN-004: بريد إلكتروني خاطئ التنسيق (سلبية، متوسطة)

• الجسم: {"email": "not-an-email", "password": "Correct-Horse-9"}
• الحالة المتوقعة: 400
• الاستجابة المتوقعة: error يساوي validation_error

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

كتابة نفس حالة الاختبار في Apidog

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

1. استيراد أو تعريف نقطة النهاية. قم بإحضار POST /auth/login من ملف OpenAPI، أو مجموعة Postman، أو قم بتعريفه مباشرة. يصبح مخطط الطلب أساسًا لكل تأكيد.
2. أضف بيانات الطلب. أدخل الجسم للحالة AUTH-LOGIN-001. لتغطية تعتمد على البيانات، أرفق ملف CSV أو JSON بحيث يتم تشغيل حالة واحدة مقابل كل صف بيانات اعتماد؛ هكذا يحل اختبار واجهة برمجة التطبيقات المعتمد على البيانات محل أربع حالات متطابقة تقريبًا بحالة واحدة.
3. قم بتعيين التأكيدات بصريًا. انقر للتأكيد على أن الحالة تساوي 200، وأن token موجود وهو سلسلة غير فارغة، وأن expires_in يساوي 3600، وأن وقت الاستجابة يبقى أقل من 800 مللي ثانية. لا يلزم أي برمجة.
4. تجميع الحالات في سيناريو اختبار. أضف جميع حالات تسجيل الدخول الأربع إلى سيناريو واحد بحيث يتم تمرين نقطة النهاية بالكامل في تشغيل واحد.
5. تشغيل وقراءة التقرير. يقوم Apidog بتنفيذ السيناريو، ويولد تقرير نجاح/فشل لكل حالة، ويكشف عن التأكيد الدقيق الذي تعطل. يمكنك تشغيل السيناريو محليًا، أو بجدول زمني، أو داخل CI.

النقطة ليست أن البرمجة خاطئة؛ بل هي أن الحالة المرئية المهيكلة أسرع في الكتابة، وأسهل في المراجعة، وأصعب في ارتكاب الأخطاء الدقيقة فيها. عندما تحتاج إلى التعليمات البرمجية، يتيح لك Apidog الدخول إلى نصوص برمجية مخصصة. لتدفق عمل خالٍ تمامًا من البرمجة، يغطي اختبار واجهة برمجة التطبيقات بدون Postman النهج الأوسع.

أخطاء شائعة يجب تجنبها

التأكيد على رمز الحالة فقط. رمز 200 يعني أنه تم التعامل مع الطلب، وليس أن الاستجابة كانت صحيحة. قم دائمًا بالتأكيد على حقول الجسم.

حالة واحدة عملاقة لكل نقطة نهاية. عندما تفشل، لا تتعلم شيئًا. قسّم حسب الشرط.

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

عدم تأكيد وقت الاستجابة. تتسلل تراجعات الأداء بصمت عندما لا يقيس شيء وقت الاستجابة.

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

قم بتنزيل Apidog إذا كنت ترغب في متابعة المثال وبناء حالات تسجيل الدخول الأربع بنفسك.

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

كم عدد حالات الاختبار التي تحتاجها نقطة نهاية واحدة؟ يكفي لتغطية المسار الإيجابي (happy path)، وكل فشل في حقل مطلوب، وفشل واحد في المصادقة، واختبار أمان واحد. لنقطة نهاية بسيطة تكون أربع إلى ست حالات؛ لنقطة معقدة يمكن أن تكون أكثر.

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

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

ما الفرق بين حالة الاختبار وسيناريو الاختبار؟ السيناريو هو الهدف عالي المستوى ("التحقق من تسجيل الدخول")؛ بينما الحالة هي فحص واحد ملموس وقابل للتشغيل ضمن هذا السيناريو. انظر سيناريو الاختبار مقابل حالة الاختبار.