ما هو اختبار API؟ وكيف تختبر REST API

الخطوة 1: اقرأ العقد. يوثّق العقد تسع نتائج: 201 و400 و401 و403 FORBIDDEN و403 INSUFFICIENT_SCOPE و404 و409 و415 و422؛ فتحتاج المجموعة إلى تسعة اختبارات على الأقل قبل أي قيمة حدّية. والقواعد التي لها حدود هي: qty (من ⁦1⁩ إلى الكمية القابلة للإرجاع: ⁦2⁩ للمنتج A-100 و⁦1⁩ للمنتج B-200 في الطلبية O-5001)، وcomment (⁦500⁩ حرف)، وitems (عنصر واحد على الأقل، وكل SKU مرة واحدة، ومن منتجات الطلبية فقط)، ومهلة الأيام الأربعة عشر. ولا تحوي بيانات الاختبار طلبية على حدّ المهلة، فاطلب طلبيتين اصطناعيتين إضافيتين للعميل CUS-101، مثل O-5004 المسلَّمة في ⁦17⁩ سبتمبر ⁦2026⁩ (قبل ⁦14⁩ يوماً من اليوم) وO-5005 المسلَّمة في ⁦16⁩ سبتمبر ⁦2026⁩ (قبل ⁦15⁩ يوماً)، وفي كل منهما ⁦A-100 × 1⁩ حتى يصلح لهما طلب المطوّر دون تغيير. ونفّذ كل اختبار على بيانات مستعادة، لأن كل إرجاع ناجح يُنقص الكمية القابلة للإرجاع في الاختبار التالي. وترقّم المجموعة النموذجية أدناه الاختبارات من RT-01 إلى RT-25؛ وقد يختلف ترقيمك وصياغتك.

الخطوة 2: المسار السعيد. RT-01 طلب المطوّر (⁦A-100 × 1⁩، DAMAGED)، والمتوقع 201؛ وقيمة Location هي /api/v1/returns/ متبوعةً بقيمة id الواردة في الجسم؛ وContent-Type: application/json وCache-Control: no-store؛ والجسم يحوي كل حقول الإرجاع بالأنواع الصحيحة — refundAmount رقم لا نص، وcomment قيمته null، وcreatedAt بصيغة ISO 8601 مع الإزاحة الزمنية — وبالقيم الصحيحة: orderId هو O-5001، وstatus هو requested، والعناصر والسبب كما أُرسلت، وrefundAmount هو ⁦49.95⁩؛ وزمن الاستجابة أقل من ⁦800⁩ ميلي ثانية. احفظ هذه الاستجابة خطَّ أساس. RT-02 إرجاع كل ما في الطلبية: ⁦A-100 × 2⁩ و⁦B-200 × 1⁩، والسبب WRONG_ITEM، مع تعليق قصير، والمتوقع 201 مع العنصرين كليهما، وعودة التعليق كما أُرسل، وrefundAmount بقيمة ⁦219.90⁩ (⁦2 × 49.95 + 120.00⁩)، وهي قيمة لا يكشفها التحقق من رمز الحالة وحده أبداً.

الخطوة 3: اكسر المدخلات؛ وكل اختبار هنا هو RT-01 مع تغيير واحد. RT-03 جسم مقطوع بعد {"items": [، والمتوقع 400 MALFORMED_JSON. RT-04 الجسم الصالح نفسه مع Content-Type: text/plain، والمتوقع 415 UNSUPPORTED_MEDIA_TYPE. RT-05 حذف items، والمتوقع 422 VALIDATION_ERROR مع field بقيمة items. RT-06 القيمة "items": []، والمتوقع 422 مع field بقيمة items. RT-07 حدود qty للمنتج A-100 الذي كميته القابلة للإرجاع ⁦2⁩ (الصيغة الثنائية من تحليل القيم الحدّية، 2-value BVA: كل قيمة حدّية وأقرب قيمة مجاورة لها في القسم المجاور): ⁦0⁩ يعطي 422 مع field بقيمة items[0].qty، و⁦1⁩ يعطي 201 (RT-01)، و⁦2⁩ يعطي 201، و⁦3⁩ يعطي 422. RT-08 قيم وأنواع غير صالحة لـqty: -1 و1.5 و"1" (نص)، والمتوقع 422 لكل منها. RT-09 المنتج C-300 الذي ينتمي إلى طلبية أخرى، والمتوقع 422 مع field بقيمة items[0].sku. RT-10 المنتج A-100 مرتين في items، والمتوقع 422. RT-11 حذف reason، ثم reason بقيمة OTHER، والمتوقع 422 مع field بقيمة reason. RT-12 تعليق comment من ⁦500⁩ حرف بالضبط يعطي 201 ويعود التعليق كاملاً، و⁦501⁩ حرف يعطي 422 مع field بقيمة comment.

RT-13 الطلبية O-9999، والمتوقع 404 ORDER_NOT_FOUND. RT-14 الطلبية O-5002 التي شُحنت ولم تُسلَّم، والمتوقع 409 ORDER_NOT_RETURNABLE، وهي الاستجابة التي يحددها العقد للطلبية غير المسلَّمة (انظر Q4). RT-15 المهلة: O-5004 (اليوم ⁦14⁩) تعطي 201 إن كان اليوم الرابع عشر محسوباً (السؤال Q1)، وO-5005 (اليوم ⁦15⁩) وO-5003 (اليوم ⁦21⁩) تعطيان 409. RT-16 تعليق فيه علامات تنصيص وأقواس زاوية، مثل O'Brien "test" <b>x</b>، والمتوقع 201 وعودة التعليق كما أُرسل تماماً، دون 500 ودون SQL أو تتبّع مكدس في أي رسالة. ولا ترسل مثل هذه المدخلات إلا إلى أنظمة مأذون لك باختبارها، وهي هنا بيئة Staging الخاصة بفريقك.

الخطوة 4: المصادقة. RT-17 دون ترويسة Authorization، والمتوقع 401 UNAUTHENTICATED دون أي بيانات إرجاع؛ ويشترط RFC 9110 أيضاً أن تحمل كل استجابة 401 ترويسة WWW-Authenticate. RT-18 الرمز TOKEN_A_EXPIRED، والمتوقع 401 UNAUTHENTICATED. RT-19 الرمز TOKEN_B الخاص بالعميل CUS-202 على الطلبية O-5001، والمتوقع 403 FORBIDDEN دون أي معلومة عن O-5001 في الجسم؛ وبعده يُظهر الطلب GET /api/v1/orders/O-5001/returns بالرمز TOKEN_A أنه لا إرجاع جديداً، والطلب GET نفسه بالرمز TOKEN_B يُرفض بـ403. ويسمح RFC 9110 للخادم بأن يجيب بـ404 بدلاً من ذلك ليخفي وجود الطلبية؛ لكن هذا العقد اختار 403، فهو النتيجة المتوقعة. RT-20 الرمز TOKEN_A_READ الذي لا يملك إلا النطاق orders:read، والمتوقع 403 INSUFFICIENT_SCOPE.

الخطوة 5: تغيّر الحالة والترويسات. RT-21 بعد RT-01 يعيد GET /api/v1/orders/O-5001/returns رمز الحالة 200 مع إرجاع واحد بالضبط تطابق قيمُ id والعناصر والسبب وrefundAmount فيه جسمَ استجابة 201. RT-22 الكمية القابلة للإرجاع تنقص: بعد RT-01 يعطي المنتج A-100 مع qty بقيمة ⁦2⁩ الرمز 422 (لم يبقَ إلا ⁦1⁩)، ومع qty بقيمة ⁦1⁩ يعطي 201، ثم مع qty بقيمة ⁦1⁩ مرة أخرى يعطي 422. RT-23 طلب RT-01 مضافاً إليه "status": "approved", "refundAmount": 999، والمتوقع 201 مع status بقيمة requested وrefundAmount بقيمة ⁦49.95⁩: يجب ألا يستطيع العميل تحديد المبلغ المسترد بنفسه (ويغطي OWASP API Security Top 10 2023 ذلك تحت API3، أي Broken Object Property Level Authorization). RT-24 الطلبات المرفوضة لا تغيّر شيئاً: بعد RT-07 مع qty بقيمة ⁦3⁩، وRT-11، وRT-14 تبقى قائمة إرجاعات الطلبية كما هي. RT-25 إرسال طلب RT-02 مرتين في اللحظة نفسها، والمتوقع استجابة 201 واحدة واستجابة 422 واحدة؛ فاستجابتا 201 تعنيان استرداد ثمن المنتجات نفسها مرتين. وفي كل استجابة، بما فيها الأخطاء، تحقق من Content-Type: application/json وCache-Control: no-store (فالبيانات خاصة)، ومن شكل الخطأ المحدد في العقد، ومن أن Location لا يظهر إلا مع 201.

وتنطبق أيضاً الخطوتان الأخيرتان من الطريقة: سجّل زمن استجابة كل اختبار وعلّم كل زمن يتجاوز ⁦800⁩ ميلي ثانية حتى لو كانت الاستجابة صحيحة، وقارن الأزمنة بين البناءات، فالزمن الذي يواصل الارتفاع انحدار حتى لو بقي دون ⁦800⁩ ميلي ثانية. ثم حوّل المجموعة إلى مجموعة طلبات (Collection) تستعيد بيانات الاختبار وتعمل مع كل بناء وتقارن RT-01 بخط الأساس المحفوظ. هذه ⁦25⁩ اختباراً لنقطة نهاية واحدة. ويذكر قسم الأسئلة الشائعة في الدليل الحدّ الأدنى: مسار سعيد واحد، واختبار لكل خطأ موثّق، وحالة فشل في المصادقة، والقيم الحدّية لكل معامل؛ أما RT-21 إلى RT-25 فهي ما تفوته مجموعة مبنية على الاستجابات المنفردة وحدها.

الخطوة 6: التشغيل الأول. R1 فاشل لثلاثة أسباب يذكرها الدليل كلها: 500 لمدخلات سيئة بدلاً من 422، وشكل خطأ يخالف العقد (نص بدلاً من الكائن error بحقوله code وmessage وfield)، وهذان من الأعطال الشائعة في الدليل؛ ورسالة تسرّب تفاصيل داخلية (اسم استثناء وملفاً مصدرياً ورقم سطر)، وهو ما تمنعه قائمة الدليل لما تتحقق منه في كل استجابة. المتوقع: 422 VALIDATION_ERROR مع field بقيمة items[0].qty.

R2 فاشل وهو الأخطر: فحص تفويض مفقود، فالرمز صالح لكنه يخص عميلاً لا حق له في هذه الطلبية. فأي عميل مسجّل الدخول يستطيع طلب الإرجاع، ومن ثَمّ استرداد المبالغ، على طلبية غيره، والاستجابة تكشف بيانات تلك الطلبية. ويصنّف OWASP API Security Top 10 2023 هذا تحت API1، أي Broken Object Level Authorization. المتوقع: 403 FORBIDDEN وعدم إنشاء أي إرجاع. بلّغ عنه أولاً بخطورة حرج (Critical)، مع الطلب كما أُرسل بالرمز TOKEN_B واستجابة 201 والإرجاع R-9002 الذي أنشأه؛ وبعد الإصلاح أعد تنفيذ RT-19 اختبارَ تأكيد (Confirmation testing)، بما فيه طلب GET بالرمز TOKEN_B. وR3 فاشل: 200 OK مع خطأ داخل الجسم، فالتطبيق الذي يعتمد على رمز الحالة يخبر العميل بأن الإرجاع قُبل، والجسم بشكل خطأ آخر مختلف. المتوقع: 422 VALIDATION_ERROR مع field بقيمة reason، وعدم إنشاء أي إرجاع.

أسئلة لمالك المنتج والمطوّر. Q1 هل تشمل عبارة العقد "within 14 days of delivery" اليوم الرابع عشر، وهل تُحسب المهلة بالأيام التقويمية في المنطقة الزمنية للمتجر أم بفترات من ⁦24⁩ ساعة تبدأ من وقت التسليم؟ Q2 كيف تُعدّ أحرف comment الخمسمئة في النص العربي وفي الرموز التعبيرية (Emoji)، وهل يُقبل تعليق فارغ؟ Q3 هل reason حساس لحالة الأحرف، أي هل تُرفض القيمة damaged؟ Q4 حين يخالف الطلب قاعدتين، فأي خطأ يأتي أولاً؟ مثل طلبية عميل آخر مع جسم غير صالح، أو الطلبية O-5002 التي لم تُسلَّم، فلا كمية قابلة للإرجاع فيها بعد (409 أم 422؟). والمتوقع عادةً أن يأتي فحص التفويض أولاً، حتى لا تكشف رسائل التحقق شيئاً عن طلبية شخص آخر.

راجع عملك: يجب أن يظهر كل رمز حالة موثّق في مجموعتك مرة واحدة على الأقل؛ وأن يغيّر كل اختبار سلبي شيئاً واحداً فقط في RT-01؛ وأن تذكر كل نتيجة متوقعة رمز الحالة ورمز الخطأ، لا مجرد «خطأ». وبمصطلحات ISTQB، فإن العقد هو أساس الاختبار (Test basis)، وكل استجابة موثّقة وكل قاعدة شرط اختبار (Test condition)، والاختبارات RT-07 وRT-12 وRT-15 تطبّق الصيغة الثنائية من تحليل القيم الحدّية. وإن لم تكن في مجموعتك فحوصات بعد الاستجابة، أي RT-21 إلى RT-25، فأضفها: فقد تبدو الاستجابة صحيحة بينما البيانات التي خلفها خاطئة.