إذا احتفظت بملف OpenAPI ولكن خدمتك قيد التشغيل تبتعد عنه ببطء، فإن Specmatic مصمم خصيصًا لتلك الفجوة. إنه يتعامل مع مواصفاتك كعقد قابل للتنفيذ، ثم يختبر خدمة حقيقية مقابلها ويقوم بتشغيل نفس المواصفات كوصلة ذكية. يشرح هذا الدليل ما يفعله Specmatic، وكيف يختلف اختبار العقود عن الاختبار القائم على الأمثلة، ومكان أداة Specmatic، مع ملاحظة حول كيفية مقارنتها بنهج منصة أوسع مثل اختبار عقد API من Apidog. أما بالنسبة لتنسيق المواصفات الأساسي، فإن مواصفات OpenAPI هي مصدر الحقيقة الذي يقرأ منه Specmatic.
ما هو Specmatic
Specmatic هي أداة مفتوحة المصدر لتطوير يعتمد على العقود. الفكرة الأساسية بسيطة: مواصفات API الخاصة بك هي العقد، وSpecmatic يجعل هذا العقد قابلاً للتنفيذ. قم بتوجيهها إلى ملف OpenAPI ويمكنها القيام بوظيفتين متكاملتين.
- تشغيل المواصفات كاختبارات مقابل خدمة مباشرة، والتحقق من أن الخدمة تلتزم بكل مسار، ورمز حالة، ومخطط تعدت به المواصفات.
- تشغيل المواصفات كخادم وهمي (stub server)، بحيث يمكن للمستهلكين التطوير مقابل نموذج يحاكي الاستجابة تمامًا كما ينص العقد.
تستخدم كلتا الوظيفتين نفس الملف. لا يوجد "تعريف اختبار" منفصل و "مواصفات" للحفاظ على التزامن، وهذا هو بيت القصيد. يتجاوز Specmatic أيضًا OpenAPI. أضاف الإصدار 2.0 دعم GraphQL و gRPC، ويدعم AsyncAPI لعقود الأحداث بنمط Kafka، بالإضافة إلى تنسيقات مثل WSDL و Avro. ومع ذلك، بالنسبة لمعظم الفرق، فإن نقطة الدخول هي ملف OpenAPI YAML أو JSON بسيط.
يمكنك تشغيله من سطر الأوامر أو صورة Docker، لذلك يندمج في CI بسهولة. تقدم الشركة التي تقف وراءه إضافات تجارية، لكن محرك العقود نفسه مجاني ومفتوح المصدر.
اختبار العقود مقابل الاختبار القائم على الأمثلة
هذا هو التمييز الذي يربك معظم الناس، لذا يستحق الأمر أن نكون دقيقين.
الاختبار القائم على الأمثلة هو ما تفعله في معظم عملاء API. تكتب طلبًا، وتتحقق من الاستجابة التي تلقيتها، ربما تتحقق من رمز الحالة وحقل أو اثنين. كل اختبار هو مثال مكتوب يدويًا. إذا كان لمواصفاتك 40 نقطة نهاية، فإنك تكتب وتحافظ على الكثير من الأمثلة، ومن السهل تفويت الثغرات.
اختبار العقود يقلب النموذج. بدلاً من التأكد من أمثلة محددة، فإنك تؤكد أن الخدمة تتوافق مع العقد. يقرأ Specmatic المخطط ويولد اختبارات منه. يتحقق من أن الاستجابات تتوافق مع الأنواع المعلنة، وأن الحقول المطلوبة موجودة، وأن رموز الحالة متوافقة، وأن الخدمة ترفض الطلبات غير الصالحة بالطريقة التي تشير إليها المواصفات. أنت لا تكتب التأكيدات واحدة تلو الأخرى. المواصفات هي التأكيد.
| الجانب | الاختبار القائم على الأمثلة | اختبار العقود باستخدام Specmatic |
|---|---|---|
| مصدر الحقيقة | حالات اختبار مكتوبة يدويًا | مواصفات OpenAPI نفسها |
| ما الذي تحافظ عليه | كل طلب وتأكيد | المواصفات، التي تحتفظ بها على أي حال |
| التغطية | فقط ما تذكرت أن تكتبه | كل عملية تعلن عنها المواصفات |
| اكتشاف الانحراف | يدوي | تلقائي عند تغيير المواصفات |
| الفشل النموذجي | تعطل مثال محدد | الخدمة لم تعد تتوافق مع العقد |
هناك محور ثانٍ يستحق الذكر. يأتي اختبار العقود بنكهات مختلفة، وSpecmatic يقع في نكهة محددة. يعتمد اختبار العقود الذي يقوده المستهلك على نمط Pact على قيام المستهلكين بنشر توقعاتهم إلى وسيط (broker)، ويتحقق المزودون من تلك التوقعات. Specmatic يقوم باختبار يعتمد على العقد بدلاً من ذلك: المواصفات هي العقد الواحد الذي يتفق عليه الطرفان، ويتحقق Specmatic من المزود مقابلها ويقوم بتوفير وصلة (stub) للمزود للمستهلكين. إنه ليس وسيط Pact، ولا يدير عقود Pact المنشورة من قبل المستهلكين. إذا كنت تريد الصورة الأوسع، فراجع هذا الملخص حول أدوات اختبار ومحاكاة عقود API.
كيف يعمل Specmatic
يمكنك تثبيت واجهة سطر الأوامر (CLI) مباشرة أو سحب صورة Docker. Docker هو الخيار الشائع في CI لأنه يتجنب إعداد وقت التشغيل المحلي.
تشغيل اختبارات العقود
يُوجه أمر الاختبار Specmatic إلى المواصفات وإلى خدمة قيد التشغيل. يبدو الحد الأدنى للتشغيل المحلي كالتالي:
# Native CLI
specmatic test api.yaml --testBaseURL=http://localhost:8080
# Docker
docker run -v "$(pwd):/usr/src/app" specmatic/specmatic \
test api.yaml --testBaseURL=http://host.docker.internal:8080
يقرأ Specmatic ملف api.yaml، وينشئ طلبات للعمليات التي يصفها، ويرسلها إلى عنوان URL الأساسي، ويتحقق من صحة كل استجابة مقابل المخطط. يعني الاختبار الفاشل أن الخدمة والعقد غير متفقين. تقوم بإصلاح أحدهما أو الآخر. هذه هي الدورة.
تشغيل المواصفات كوصلة (Stub)
الخادم الوهمي (stub server) هو النصف الآخر. ابدأ تشغيله وسيقوم Specmatic بتقديم استجابات تتطابق مع العقد، بحيث يمكن للواجهة الأمامية أو خدمة تابعة البناء عليها قبل وجود الواجهة الخلفية الحقيقية.
specmatic stub api.yaml --port=9000
يقوم بشكل افتراضي بإنشاء استجابات صالحة للمخطط أثناء التنفيذ. يمكنك أيضًا حفظ أمثلة محددة في دليل _examples بجانب المواصفات، وسيقوم الـ stub بإرجاعها عندما يتطابق الطلب. يمنحك هذا بيانات واقعية وقابلة للتحكم دون الحاجة إلى إعداد واجهة خلفية حقيقية. إذا كنت تقارن خيارات الـ stub والـ mock عبر الأدوات، فإن ملخص اختبار العقود وخوادم المحاكاة يضع Specmatic في سياقه الصحيح.
يمكن لـ Specmatic أيضًا مساعدتك في إنشاء المواصفات في المقام الأول. يمكنه العمل كوكيل أمام خدمة موجودة، والتقاط حركة المرور الحقيقية، وإنشاء مستند OpenAPI بالإضافة إلى ملفات أمثلة مما يراه. وهذا مفيد عندما يكون لديك خدمة ولكن لا توجد مواصفات حتى الآن.
نموذج المواصفات كعقد ووصلة (Stub)
إليك سبب أهمية تشغيل ملف واحد كاختبار ووصلة (stub) في نفس الوقت. عندما تكون المواصفات هي العقد، لا يمكن لجانب الاختبار وجانب الـ stub أن يختلفا أبدًا، لأنهما يقرآن نفس المستند.
- يقوم فريق المزود بتشغيل
specmatic testفي CI. إذا قاموا بتغيير API دون تحديث المواصفات، تفشل اختبارات العقد. - يقوم فريق المستهلك بتشغيل
specmatic stubمحليًا. يقومون بالتطوير مقابل استجابات مضمونة لتتوافق مع نفس العقد.
لذلك تصبح المواصفات اتفاقية حية، وليست مستندًا قديمًا لا يثق به أحد. هذا هو الفرق بين الـ stub والـ mock الأكثر ثراءً، ويستحق فهم الأفكار الأساسية في الـ stubbing مقابل الـ mocking في API قبل تصميم سير عمل حولها.
يضيف Specmatic أيضًا التحقق من التوافق مع الإصدارات السابقة. يقوم أمر backward-compatibility-check ببدء وصلة (stub) من الإصدار الجديد للمواصفات، وإنشاء اختبارات من الإصدار السابق، وتشغيلها مقابل الـ stub الجديد. إذا كان هناك شيء كان يعمل ولم يعد يعمل، فإنك تكتشف ذلك قبل النشر. وهذا حاجز حماية قوي للخدمات المصغرة التي تنتشر بشكل مستقل، وهو نكهة من الفكرة الأوسع التي تغطيها اختبار العقود ثنائي الاتجاه.
أين يتناسب Specmatic
يكسب Specmatic مكانه عندما تنطبق هذه الأمور على فريقك:
- مواصفات OpenAPI (أو AsyncAPI، GraphQL، gRPC) الخاصة بك حقيقية وكاملة بشكل معقول.
- لديك فرق مزود ومستهلك منفصلة أو خدمات تحتاج إلى البقاء متزامنة.
- تريد أن يؤدي انحراف المواصفات إلى فشل بناء (build) تلقائيًا، بدلاً من اكتشافه في المراجعة.
- أنت مرتاح لسير عمل يعتمد على سطر الأوامر و CI في المقام الأول.
إنه أقل ملاءمة إذا كنت لا تحتفظ بمواصفات، أو إذا كنت تريد مساحة عمل مرئية لتصميم واستكشاف واجهات برمجة التطبيقات، أو إذا كنت تريد أداة واحدة للتعامل أيضًا مع التصحيح المخصص والتوثيق والتعاون الجماعي. يركز Specmatic على محرك العقود، ويقوم بهذه المهمة الواحدة بشكل جيد.
هذا التركيز هو أيضًا المكان الذي تتخذ فيه منصة مثل Apidog شكلاً مختلفًا. Apidog مدفوعة بالمخططات بنفس الطريقة: تقرأ مواصفات OpenAPI الخاصة بك، وتتحقق من صحة الاستجابات مقابل المخطط، وتقوم بتشغيل خادم وهمي من مخطط OpenAPI الخاص بك بدون رمز برمجي. الفرق الصريح هو النطاق. Specmatic هي أداة عقود حادة، أصلية لواجهة سطر الأوامر. يجمع Apidog بين التصميم والاختبار والمحاكاة والتوثيق في مساحة عمل واحدة مع محرر مرئي، بحيث تعيش المواصفات والاختبارات والمحاكاة معًا وتبقى متزامنة أثناء عملك. Apidog ليس وسيط عقود يعتمد على المستهلك بنمط Pact أيضًا، لذا إذا كان فريقك يحتاج تحديدًا إلى وسيط Pact، فليست أي من الأداتين مناسبة لذلك.
إذا كنت ترغب في إنشاء اختبارات قابلة للتشغيل مباشرة من مواصفات داخل هذا النوع من مساحات العمل، فراجع كيف يتعامل Apidog مع إنشاء مجموعات اختبار API من مواصفات OpenAPI.
الأسئلة المتداولة
هل Specmatic مجاني؟
نعم. محرك العقود الأساسي مفتوح المصدر ومجاني للاستخدام من سطر الأوامر أو Docker. هناك عروض تجارية حوله، ولكن يمكنك تشغيل اختبارات العقود والخوادم الوهمية من مواصفات OpenAPI دون دفع. تحقق من الموقع الرسمي و GitHub للحصول على التفاصيل الحالية حول المستويات المدفوعة.
هل يعمل Specmatic فقط مع OpenAPI؟
لا. OpenAPI هي نقطة الدخول الأكثر شيوعًا، ولكن Specmatic يدعم أيضًا AsyncAPI لعقود الأحداث، بالإضافة إلى GraphQL و gRPC منذ الإصدار 2.0، إلى جانب تنسيقات مثل WSDL و Avro. النموذج هو نفسه في جميعها: المواصفات هي العقد القابل للتنفيذ. إذا كنت جديدًا على التنسيق نفسه، فابدأ بهذا البرنامج التعليمي لمواصفات OpenAPI.
هل Specmatic هو نفسه Pact؟
ليس تمامًا. يعتمد Pact على المستهلك: ينشر المستهلكون توقعاتهم إلى وسيط، ويتحقق المزودون منها. Specmatic يعتمد على العقد: المواصفات هي العقد المشترك الوحيد، ويتحقق Specmatic من المزود مقابلها بينما يقوم بتوفير وصلة للمزود للمستهلكين. كلاهما يقلل من مفاجآت التكامل، لكنهما ينظمان العقد بشكل مختلف.
هل يمكن لـ Specmatic إنشاء مواصفات OpenAPI لي؟
نعم. يمكن لـ Specmatic العمل كوكيل أمام خدمة موجودة، والتقاط حركة المرور الحقيقية للطلب والاستجابة، وإنشاء مستند OpenAPI بالإضافة إلى ملفات الأمثلة منه. وهذا مفيد عندما يكون لديك خدمة عاملة ولكن لا توجد مواصفات رسمية للاختبار مقابلها بعد.
الخلاصة
يحل Specmatic مشكلة حقيقية ومحددة: الحفاظ على خدمة قيد التشغيل متوافقة مع مواصفات OpenAPI التي من المفترض أن تتبعها. من خلال جعل المواصفات قابلة للتنفيذ، يمنحك اختبارات العقود ووصلة متطابقة من ملف واحد، مع فحوصات التوافق مع الإصدارات السابقة بالإضافة إلى ذلك. إذا كنت تعتمد على الطرفية و CI وتحتفظ بمواصفات قوية، فهو خيار مناسب تمامًا.
إذا كنت تفضل أن يكون العقد والاختبارات والمحاكاة والوثائق في مساحة عمل مرئية واحدة تقرأ نفس ملف OpenAPI، جرب Apidog. يتحقق من صحة الاستجابات مقابل المخطط الخاص بك، ويحاكي نقاط النهاية بدون رمز، ويحول المواصفات إلى مجموعات اختبار قابلة للتشغيل. قم بتنزيل Apidog لتوجيهه إلى مواصفاتك ورؤية دورة التصميم إلى الاختبار الكاملة في مكان واحد.