اختبار العقد

لماذا يهم

تُصدَر الخدمات والتطبيقات كلٌّ على حدة. وقد ينجح تغيير في المزوّد في كل اختباراته ثم يُعطّل مستهلكاً، لأن تلك الاختبارات لا تعرف ما يقرؤه المستهلك. ومن دون اختبار العقد لا يظهر العطل إلا حين يعمل الطرفان معاً: بعد أيام في بيئة اختبارات E2E، أو في الإنتاج حيث تواصل الإصدارات القديمة من تطبيق الجوال استدعاء الواجهة.

وبالنسبة إلى المختبِر، يجيب اختبار العقد عن سؤال إصدار محدد: هل سيعمل إصدار المزوّد هذا مع كل إصدار مستهلك سيلتقي به؟ وإن لم يعمل، سمّى المستهلك والتفاعل والحقل.

المستهلكون والمزوّدون والعقد

يصف مارتن فاولر (Martin Fowler) اختبار العقد بأنه فحص يتأكد أن بديل الاختبار (Test Double)، أي الـStub أو الـMock الذي تستخدمه اختبارات أخرى مكان خدمة ما، ما زال يتصرف كالخدمة الحقيقية. ويطبّق اختبار العقد الفكرة على الطرفين: يُختبر كلٌّ منهما مقابل العقد المكتوب نفسه.

في واجهة HTTP يحدّد كل تفاعل في العقد ما يلي:

• الطلب: الطريقة (Method) والمسار ومعاملات الاستعلام والترويسات المهمة والجسم.
• الاستجابة المتوقعة: رمز الحالة والترويسات وحقول الجسم مع أنواعها أو أنماطها.
• حالة المزوّد (Provider State): البيانات التي يجب أن توجد ليكون للتفاعل معنى، مثل «الطلب ORD-1042 موجود».

اختبار العقد المدفوع بالمستهلك

في اختبار العقد المدفوع بالمستهلك (Consumer-Driven Contract Testing) يكتب المستهلكون العقد من خلال اختباراتهم، فيعرف المزوّد بالضبط أيّ الحقول يستخدمها كل مستهلك، ويغيّر ما سواها بحرية. والكلفة أن على كل فريق مستهلك أن يكتب هذه الاختبارات ويصونها، وعلى المزوّد أن يشغّلها؛ لذا يناسب الخدماتِ داخل مؤسسة واحدة، لا واجهةً عامة مستهلكوها مجهولون.

وتعمل Pact، وهي أداة مفتوحة المصدر لهذا الأسلوب، في خمس خطوات (ملف العقد الذي تنتجه معروض أدناه):

• اختبار المستهلك: تستدعي شيفرة العميل مزوّداً محاكى (Mock Provider) يجيب كما يصرّح الاختبار، فيثبت الاختبار أن المستهلك يتعامل مع تلك الاستجابة تعاملاً صحيحاً.
• ملف العقد: يكتب التشغيل كل تفاعل في ملف Pact: الطلبات التي يرسلها المستهلك وحقول الاستجابة التي يتوقعها اختباره، وينبغي ألا تكون إلا الحقول التي يقرؤها فعلاً.
• رفع العقد (Publish): يخزّن وسيطٌ (Broker) العقدَ مع رقم إصدار المستهلك.
• تحقق المزوّد (Provider Verification): يهيّئ خط أنابيب المزوّد كل حالة مزوّد، ويعيد إرسال كل طلب إلى المزوّد الحقيقي، ويقارن الاستجابة بالمتوقعة، بالنوع أو بالنمط حين لا تهمّ القيمة بعينها؛ والحقول الإضافية مسموحة افتراضياً.
• فحص النشر (Deployment Check): قبل أن يُنشر أيّ من الطرفين، يؤكد الوسيط أن التحقق نجح بين هذا الإصدار والإصدارات الموجودة في البيئة المستهدفة (الأمر can-i-deploy في Pact).

{
  "consumer": { "name": "mobile-app" },
  "provider": { "name": "orders-api" },
  "interactions": [
    {
      "description": "a request for an existing order",
      "providerStates": [{ "name": "order ORD-1042 exists and is shipped" }],
      "request": { "method": "GET", "path": "/orders/ORD-1042" },
      "response": {
        "status": 200,
        "headers": { "Content-Type": "application/json" },
        "body": { "id": "ORD-1042", "status": "shipped", "total": 149.5 },
        "matchingRules": {
          "body": {
            "$.id": { "matchers": [{ "match": "regex", "regex": "^ORD-[0-9]+$" }] },
            "$.total": { "matchers": [{ "match": "type" }] }
          }
        }
      }
    }
  ],
  "metadata": { "pactSpecification": { "version": "3.0.0" } }
}

جرّبها: مقارنة عقود الاستجابات

اختبار العقد المبني على المواصفة باستخدام OpenAPI

هنا يكون مستند OpenAPI الخاص بالمزوّد هو العقد، وتسمّي بعض الفرق ذلك اختبار العقد المدفوع بالمزوّد. فالفحص الذي تعلّمته في درس التحقق من مخطط API يجري على كل استجابة في اختبارات المزوّد، بما فيها الأخطاء، ويبني المستهلكون بدائل المحاكاة من المستند نفسه.

ونقطته العمياء: إذا تغيّرت الشيفرة والمستند معاً، بقي المزوّد مطابقاً لمستنده. لذلك تُقارَن كل نسخة جديدة من المستند أيضاً بنسخة الإنتاج، وتُعلَّم التغييرات الكاسرة (Breaking Changes):

• كاسر: حذف عملية أو حقل استجابة أو إعادة تسميته، وتغيير نوع، وجعل حقل اختياري في الطلب إلزامياً، ورفض قيم في الطلب كانت مقبولة من قبل.
• آمن عادةً: إضافة عملية أو حقل اختياري في الطلب أو حقل في الاستجابة، إذا كان المستهلكون يتجاهلون الحقول المجهولة.
• يحتاج إلى قرار: قيمة enum جديدة أو null في استجابة؛ فالعميل الذي لا يتعامل إلا مع القيم المعروفة قد يتعطّل.
• الحدّ: يبيّن المستند ما يقدّمه المزوّد، لا ما يستخدمه كل مستهلك منه، فقد لا يمسّ تغييرٌ «كاسر» أحداً.

جرّبها: مدقّق عقود API جرّبها: مدقّق OpenAPI

مثال تطبيقي: إعادة تسمية حقل في واجهة الطلبات

لواجهة الطلبات مستهلكان لهما عقدان: تطبيق الجوال يقرأ id وstatus وtotal، وخدمة التوصيل تقرأ id وstatus وdeliveryCity. ويعيد إصدارٌ جديد تسمية total إلى grandTotal، ويحوّل createdAt من تاريخ نصي إلى رقم، ويضيف حقلاً اختيارياً giftMessage. وقد عُدِّل مستند OpenAPI أيضاً، فينجح الفحص مقابله.

• مقارنة المستندين تُعلّم تغييرين كاسرين: حذف total وتغيير نوع createdAt.
• يفشل تحقق المزوّد لعقد تطبيق الجوال عند $.total، وينجح عقد خدمة التوصيل لأنها لا تستخدم أياً من الحقلين.
• لا يقرأ أيّ عقد createdAt، فتغيير نوعه آمن للمستهلكَين المعروفَين، لا لمستهلكين خارج الوسيط.
• يوقف فحص النشر الإصدار. فيعيد الفريق total وgrandTotal معاً، ويعلّم total بأنه deprecated، ويحذفه حين لا يحتاجه أيّ إصدار مدعوم من التطبيق.
• أما تشغيل E2E فما كان ليُظهر إعادة التسمية إلا بعد نشر الخدمتين، في صورة شاشة طلب بلا مبلغ.

جرّبها: مقارنة JSON جرّبها: عارض OpenAPI

ما يكشفه اختبار العقد مقارنةً باختبار E2E

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

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

أسئلة شائعة

المراجع

• Contract Test (Martin Fowler)martinfowler.com · 2011اختبارات العقود: فحوص دورية تتأكد من أن الاستدعاءات الموجّهة إلى بديل الاختبار تعيد النتائج نفسها التي تعيدها الخدمة الخارجية الحقيقية.
• Introduction — Pact DocsPact Foundationاختبار العقود الموجّه بالمستهلك باستخدام Pact: يُختبر كل تطبيق بمعزل عن غيره مقابل عقد يتولّد أثناء تشغيل اختبارات المستهلك.
• OpenAPI SpecificationOpenAPI Initiativeالمعيار لوصف واجهات REST: المسارات والعمليات والمعاملات والمخططات والاستجابات وأنظمة الأمان.
• The Practical Test Pyramid (Ham Vocke)martinfowler.com · 2018شرح واسع الاستشهاد لكيفية الموازنة بين اختبارات الوحدة والتكامل والعقود والواجهة في محفظة الاختبارات الآلية.