اختبارات العقود باستخدام Pact
الجزء الثالث من سلسلة اختبار العقود. هذه المرة يتركز الحديث على Pact – أداة أخرى تساعد المطورين على كتابة اختبارات العقود. تعرّف على كيفية عملها، وما المزايا التي تقدمها، وبماذا تختلف أساسًا عن Spring Cloud Contract.
هذا هو الجزء الثالث من سلسلة اختبار العقود. شرحتُ سابقًا ما هو اختبار العقود وما الفوائد التي يقدمها، ثم عرضتُ Spring Cloud Contract – أحد أكثر الأطر استخدامًا لهذا النوع من الاختبارات، خاصة في منظومة JVM.
يتناول هذا الجزء أداة شائعة أخرى تساعد المطورين على كتابة اختبارات العقود: إطار Pact. ستعرف كيف يعمل، وما المزايا التي يقدمها، وبماذا يختلف أساسًا عن Spring Cloud Contract. وبعد إنهاء هذه السلسلة ستكون لديك خلفية جيدة لاختبار التواصل بين الأنظمة المتكاملة عبر REST API.
تدور أمثلة هذه المقالة حول التواصل بين order-service وpayment-service، وهو تواصل يجري عبر REST API. تُكتب الاختبارات بلغة Groovy مع Spock، وتُبنى المشاريع باستخدام Gradle. وللتذكير، هكذا تتواصل الخدمتان:


تعريف العقد
مع Spring Cloud Contract يبدأ اختبار التواصل بتعريف العقد. أما إطار Pact فيسلك طريقًا مختلفًا. فبدلًا من كتابة عقد، نبدأ بوصف ما نتوقعه من التفاعلات بين الخدمات. وما الفرق؟ الفرق الوحيد أن ما نكتبه ليس تمامًا الوثيقة التي يتشاركها الطرفان المتواصلان – إذ يأخذ Pact هذه التوقعات ويولّد منها العقد النهائي. لنرَ كيف نفعل ذلك باستخدام Groovy وSpock.
class OrderCreatorPactSpec extends Specification {
(...)
def "should create order and execute online payment"() {
def accountIdVal = randomUUID()
def orderIdVal = randomUUID()
def quotaVal = BigDecimal.valueOf(1040.42)
given: 'payment-service executes online payment correctly'
def paymentService = new PactBuilder()
paymentService {
serviceConsumer "order-service"
hasPactWith "payment-service"
port 8088
uponReceiving('a request to execute online payment')
withAttributes(
method: 'PUT',
path: regexp("/payment/$UUID_REGEXP", "/payment/$orderIdVal"),
headers: [
"Accept" : APPLICATION_JSON_VALUE,
"Content-Type": APPLICATION_JSON_VALUE
]
)
withBody {
accountId uuid()
paymentType string("TRANSFER_ONLINE")
quota decimal()
dueDate datetime()
}
willRespondWith(
status: 200,
headers: ['Content-Type': APPLICATION_JSON_VALUE],
body: {
paymentExternalId("ext-$orderIdVal")
status('FINISHED')
}
)
}
when:
PactVerificationResult result = paymentService.runTest {
assert sut.createOrder(accountIdVal, orderIdVal, quotaVal, TRANSFER_ONLINE).paymentProcessed()
}
then:
result == new PactVerificationResult.Ok()
}
}
أول ما يجب ملاحظته أن هذه التوقعات تأتي على شكل اختبار في order-service، أي في المستهلك (consumer). يدعم Pact اختبار العقود الموجَّه من المستهلك فقط، لذلك تكون التوقعات عادةً في جانب المستهلك.
إلى جانب تعريف ما نتوقعه من التفاعل، يتحقق الاختبار أعلاه أيضًا من أن المستهلك يفي بهذه التوقعات. تحديدًا، يشغّل الاختبار منطق إنشاء الطلب، الذي يستخدم عميل HTTP داخليًا. ثم يتحقق في قسم ‘then’ من أن العميل يلبي التوقعات المعرَّفة.
وعلى خلاف Spring Cloud Contract¹، صُمم Pact منذ اليوم الأول أداةً محايدة تقنيًا. ولهذا يقدم واجهات برمجية ولغات DSL عديدة بلغات كثيرة – من لغات JVM (Java وGroovy وغيرهما)، مرورًا بـ Ruby وRust، وصولًا إلى C++. لنستعرض التوقعات في هذا الاختبار، وهي مكتوبة بـ Groovy DSL.
تقع التوقعات في قسم ‘given’ من الاختبار. توفر الفئة PactBuilder لغة DSL سلسة لوصف جوانب التواصل. وهنا تبدأ بتحديد الطرفين المتواصلين والمنفذ، مما يتيح معرفة العقود التي يجب التحقق منها عند تشغيل اختبارات المنتِج (producer).
serviceConsumer "order-service"
hasPactWith "payment-service"
port 8088
الطلب
تصف ثلاث دوال الطلب:
uponReceiving، التي تحدد ببساطة بداية التفاعلات وتتيح لنا وصف ما يطلق هذا التفاعل، مثلuponReceiving(‘a request to execute a payment’)withAttributes، التي تحدد طريقة نقطة النهاية في REST API ومسارها والترويسات المطلوبةwithBody، التي تسرد الحقول التي يجب أن يحتويها جسم الطلب
كما في Spring Cloud Contract، نتجنب إعطاء قيم متوقعة دقيقة كلما أمكن. وبدلًا من ذلك نصفها بأنماط عامة يجب أن تطابقها الحقول.
فمثلًا، لا يتضمن جسم الطلب accountId محددًا – بل يُعلن أنه أي uuid باستخدام uuid().
withBody {
accountId uuid()
paymentType string("TRANSFER_ONLINE")
quota decimal()
dueDate datetime()
}
أما المسار فيُوصف بتعبير نمطي:
path: regexp("/payment/$UUID_REGEXP", "/payment/$orderIdVal")
القيمة في الوسيط الثاني مطلوبة لأن الرد يشير إليها. وبفضل هذا التركيب، تستخدم اختبارات المنتِج القيمة المقدَّمة بدلًا من uuid يُولَّد عشوائيًا.
الرد
بالنسبة للطلب الموصوف أعلاه، يتوقع order-service أن يعيد المنتِج ردًا معينًا. يجب أن تكون حالته 200، وأن يتضمن ترويسة Content-Type مضبوطة على application/json وحقلين – paymentExternalId وstatus. يعرّف الاختبار هذه التوقعات بالدالة willRespondWith() من Groovy DSL. توجد دوال DSL كثيرة أخرى مفيدة لوصف العقد؛ راجع التوثيق للتفاصيل.
willRespondWith(
status: 200,
headers: ['Content-Type': APPLICATION_JSON_VALUE],
body: {
paymentExternalId("ext-$orderIdVal")
status('FINISHED')
}
)
اختبار المستهلك
بعد تحديد توقعات الـ API يمكننا الآن اختبار المستهلك. يجب أن يتحقق الاختبار من أن العميل يلتزم بمتطلبات التواصل. ولاختبار المستهلكين باستخدام Pact نحتاج إلى إضافة هذه الاعتمادية.
testImplementation 'au.com.dius.pact.consumer:groovy:4.4.4'
وهي لا تحتوي فقط على DSL الموصوفة أعلاه، بل أيضًا على واجهة برمجية لتشغيل الاختبار في Spock. يشغّل الاختبار منطق إنشاء الطلب، الذي يعتمد على عميل HTTP في الخلفية، ويتحقق من أن العميل يستدعي REST API الخاص بـ payment-service بشكل صحيح.
when:
PactVerificationResult result = paymentService.runTest {
assert sut.createOrder(accountIdVal, orderIdVal, quotaVal, TRANSFER_ONLINE).paymentProcessed()
}
then:
result == new PactVerificationResult.Ok()
عندما نبني تطبيق order-service يجب أن تنجح الاختبارات. وكنتيجة جانبية ينتج Pact العقد بصيغة JSON. هذا هو العقد الفعلي، المولَّد من التوقعات المعرَّفة في الاختبار، ويُستخدم ملف JSON لاختبار المستهلك، وكما سأوضح لاحقًا لاختبار المنتِج أيضًا. ستجد الملف في المجلد build/pact؛ وبالنسبة للتوقعات الموصوفة أعلاه يبدو هكذا (اختُصر المقطع لسهولة القراءة).
{
"consumer": {
"name": "order-service"
},
"interactions": [
{
"description": "a request to execute online payment",
"request": {
"body": {
"accountId": "e2490de5-5bd3-43d5-b7c4-526e33f71304",
(…)
},
"headers": {
"Accept": "application/json",
"Content-Type": "application/json"
},
"matchingRules": {
"body": {
"$.accountId": {
"combine": "AND",
"matchers": [
{
"match": "regex",
"regex": "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"
}
]
},
(…)
]
}
},
"method": "PUT",
"path": "/payment/f4d13515-8ffd-424a-9c71-f0a52e1ffa31"
},
"response": {
"body": {
"paymentExternalId": "ext-f4d13515-8ffd-424a-9c71-f0a52e1ffa31",
"status": "FINISHED"
},
"headers": {
"Content-Type": "application/json"
},
"status": 200
}
}
],
"provider": {
"name": "payment-service"
}
}
اختبار المنتِج
أعلن المستهلك عن توقعاته وولّد العقد. بعد ذلك علينا التأكد من أن الطرف الآخر من التواصل يلبيها، وهذا يعني أن العقد يجب أن يصل إلى المنتِج بطريقة ما. كيف نحقق ذلك؟
توجد طريقتان أساسيتان:
- كشف العقد بأنفسنا – مثلًا بإعطاء عنوان URL للعقد المستضاف على خادم، أو موقعه في نظام الملفات المحلي. وهذا نهج متعب إلى حد ما.
- استخدام Pact Broker – أداة لتخزين العقود وإدارتها وكشفها.
توصيتي هي Pact Broker، لأنه يبسّط الاختبار والإصدار كثيرًا.
Pact Broker
يمكن النظر إلى Pact Broker على أنه قاعدة بيانات مركزية تحتفظ بالعقود بين الخدمات. وهو يقدم عدة ميزات تسهّل العملية:
- يتيح اختبار الخدمات مقابل العقد، مما يضمن أن إصدارات الخدمات المحددة المختبَرة هي وحدها التي يمكن أن تذهب إلى الإنتاج
- يوفر توثيقًا وتصورات مرئية لكيفية تفاعل الخدمات
- يتولى إدارة إصدارات العقود وحل التعارضات
يمكنك تشغيل نسخة من Pact Broker وإعدادها وإدارتها بنفسك. وتوجد أيضًا نسخة تجارية مُدارة بالكامل وقابلة للتوسع من الأداة – Pact Flow.
نشر العقود في Pact Broker
يتطلب نشر العقود في Pact Broker إضافة Gradle. يحدد الإعداد أدناه أن الـ broker يعمل على localhost، المنفذ 9292.
plugins {
id "au.com.dius.pact" version "4.3.6"
}
(...)
pact {
publish {
pactBrokerUrl = 'http://localhost:9292/'
}
}
وبهذا الإعداد يمكن نشر العقود بالمهمة pactPublish.
./gradlew pactPublish
أصبحت العقود بين order-service وpayment-service الآن في Pact ويمكن عرضها في واجهة الـ broker الرسومية.
يؤدي النقر على أيقونة الملف إلى عرض تفاصيل العقد. تظهر هنا التفاعلات التي حددناها كتوقعات في اختبارات المستهلك بصيغة JSON.
تنفيذ اختبارات المنتِج
يجب إعداد تطبيق المنتِج بحيث يتكامل جيدًا مع Pact Broker ويتحقق مما إذا كان يلبي متطلبات العقد. هذه الخدمة مبنية بـ Spring Boot، لذا يجب أن تتكامل الاختبارات معه. أولًا نضيف الاعتمادية التي توفر واجهة برمجية لتشغيل اختبارات المنتِج.
testImplementation 'au.com.dius.pact.provider:junit5spring:4.2.21'
يحتاج محرك الاختبار إلى معرفة مكان Pact Broker، لذلك نحدده في ملف application.properties الخاص بالاختبار.
pactbroker:
host: localhost
port: 9292
وأخيرًا ننفذ فئة اختبار تشغّل فحوصات المنتِج مقابل العقد المنشور في Pact Broker.
@SpringBootTest(webEnvironment = RANDOM_PORT)
class ContractVerificationSpec extends Specification {
@LocalServerPort
private int port
@Shared
ProviderInfo serviceProvider
ProviderVerifier verifier
def setupSpec() {
serviceProvider = new ProviderInfo("payment-service")
serviceProvider.hasPactsFromPactBroker("http://localhost:9292")
}
def setup() {
verifier = new ProviderVerifier()
serviceProvider.port = port
}
def 'verify contract with #consumer'() {
expect:
verifyConsumerPact(consumer) instanceof VerificationResult.Ok
where:
consumer << serviceProvider.consumers
}
private VerificationResult verifyConsumerPact(ConsumerInfo consumer) {
verifier.initialiseReporters(serviceProvider)
def testResult = verifier.runVerificationForConsumer([:], serviceProvider, consumer)
if (testResult instanceof VerificationResult.Failed) {
verifier.displayFailures([testResult])
}
testResult
}
}
قد يبدو الأمر معقدًا إلى حد ما، فلنستعرض ما يحدث خطوة بخطوة.
يجعل التعليق التوضيحي ‘@SpringBootTest’ على الفئة الخادمَ يبدأ بإعدادات الاختبار على منفذ عشوائي.
بعد ذلك نعلن عن كائنين لازمين لتشغيل التحقق من العقد:
- ProviderInfo – يصف إعدادات الخدمة قيد الاختبار (payment-service)، مثل اسمها ومضيفها ومنفذها ومسار الطلب وغير ذلك.
- ProviderVerifier – يتحقق من المنتِج مقابل المستهلكين المعرَّفين.
في دوال الإعداد في Spock، ضبطنا المزوّد باسم payment-service والمنفذ الذي يستخدمه SpringBoot. كما حددنا أن العقود موجودة في الـ broker الذي يمكن الوصول إليه على localhost:9292. ونتيجة لذلك يجري جلب المستهلكين الذين لديهم عقد مع هذا المنتِج من الـ broker مع تفاعلاتهم المتوقعة. وهذا يعني أننا لا نحتاج إلى تحديث الاختبار عندما يتغير تفاعل ما، مثلًا، أو عندما يريد مستهلك جديد التكامل مع payment-service. وفي كل مرة تعمل فيها اختبارات payment-service، تُجلب كل العقود من كل المستهلكين من Pact وتُختبر.
إذا بنيت هذا التطبيق الآن فيجب أن ينجح الاختبار. لكن إذا لم تطابق الـ API التوقعات في العقد، يفشل الاختبار ويبلغ عمّا حدث.
هذه ليست سوى إحدى طرق تشغيل اختبارات العقود في جانب المنتِج. اخترتها لأن كل الأمثلة في هذه السلسلة تستخدم Spock. غير أن خيارًا آخر موصى به هو إضافة Gradle للتحقق من المنتِج، التي تقلل الشيفرة اللازمة لاختبار المنتِج. لكن هذا النوع من الاختبار خارج نطاق هذه المقالة.
عند استخدام Pact مع Pact Broker، من الممارسات الجيدة نشر نتائج الاختبار في الـ broker. فهذا يوضح ما إذا كان إصدار معين من الخدمة يلبي توقعات المستهلكين. ولتفعيله نحتاج إلى ضبط خاصيتين للنظام:
pact.verifier.publishResults– عند ضبطها على true تُنشر النتائج في الـ brokerpact.provider.version– إصدار الخدمة المراد نشره
test {
useJUnitPlatform()
systemProperty 'pact.provider.version', project.version
systemProperty 'pact.verifier.publishResults', 'true'
}
وبهذا الإعداد تُرسل النتائج إلى الـ broker بعد انتهاء الاختبارات. ثم تُظهر الصفحة الرئيسية لواجهة الـ broker الرسومية أن العقد بين الخدمتين جرى التحقق منه مؤخرًا وأن الاختبارات نجحت.
يحتفظ Pact Broker بمصفوفة إصدارات لكل تكامل ويعرضها. يمكنك فتحها بالنقر على أيقونة الشبكة في قائمة العقود.
وهي تعرض تاريخ التحقق من العقد بين الخدمتين. نرى أن الإصدار 1.1.0 يحتوي على خطأ، لذا لا ينبغي نشره. لكن كيف يعرف خط CD ما إذا كان إصدار معين قد اختُبر ويمكن أن يذهب إلى الإنتاج؟ هنا تأتي أداة can-i-deploy. فبواسطة أداة سطر الأوامر هذه يمكننا ‘سؤال’ Pact Broker عما إذا كانت الخدمة متوافقة مع العقود المنشورة وتلتزم بها. فمثلًا، يمكننا التحقق مما إذا كان أحدث إصدار من payment-service يمكن نشره في الإنتاج بأمان.
pact-broker can-i-deploy --pacticipant payment-service --latest
تخبرنا ‘can-i-deploy’ أن هذا الإصدار سليم.
أما إذا سألنا عن الإصدار 1.1.0، الذي تُظهر المصفوفة أعلاه أنه غير متوافق، فسيُبلَّغ عن فشل.
pact-broker can-i-deploy --pacticipant payment-service --version 1.1.0
يمكن ربط هذه الأداة بخط CD لدينا للتحقق من توافق الخدمات قبل أن يذهب أي شيء إلى الإنتاج، مما يحمينا من نشر إصدارات خدمات غير متوافقة.
الخلاصة
شرحت هذه المقالة كيف يعمل إطار Pact. كتبنا اختبارات مستهلك تؤكد أن شيفرة خدمة الطلبات تلتزم بعقود التواصل، وأوضحتُ كيف يُولَّد العقد بصيغة JSON الخاصة بـ Pact ليمكن مشاركته مع المنتِج.
كما عرضتُ Pact broker بوصفه الطريقة الموصى بها لمشاركة العقود بين الطرفين. فهو يتيح تشغيل اختبارات المنتِج مقابل العقود التي يعرّفها كل مستهلك، دون أن تعرف اختبارات المنتِج حتى من هم هؤلاء المستهلكون.
وأخيرًا، بيّنتُ كيف يمكن استخدام Pact Broker وأداة ‘can-i-deploy’ في خط CD لمنع نشر الخدمات غير المتوافقة في الإنتاج.
وفي أثناء ذلك أشرتُ إلى الفروق الأساسية بين Spring Cloud Contract وإطار Pact. وأهمها:
- يدعم Pact النهج الموجَّه من المستهلك فقط، بينما يدعم Spring Cloud Contract أيضًا النهج الموجَّه من المنتِج.
- عقود Pact مستقلة عن اللغة (JSON) وتُولَّد من اختبارات المستهلك. أما Spring Cloud Contract فيتطلب كتابة العقد يدويًا بإحدى لغات DSL الخاصة به.
- في Spring Cloud Contract تُحفظ العقود مثلًا في مستودع Git وتُشارك بين الطرفين كلما احتاج الأمر، كأن يجري تحديثها. أما Pact فيأتي مع broker يسهّل مشاركة العقود وإدارتها.
- يحتاج Spring Cloud Contract إلى stub للمنتِج لتنفيذ اختبار المستهلك. ويُبنى هذا الـ stub من العقود التي توجد عادةً في مستودع المنتِج. أما مع Pact فنبدأ بكتابة اختبارات المستهلك، ويمكن إتمامها دون أي stub خارجي (توقعات التكامل جزء من الاختبارات).
- يقدم Pact ميزات إضافية تسهّل إدارة النشر، مثل can-i-deploy.
آمل أن تكون الآن قد كوّنت فهمًا أساسيًا لمفاهيم اختبار العقود، إلى جانب بعض المعرفة بهذين الإطارين. وينبغي أن يكفي ذلك لبدء كتابة اختبارات العقود لـ REST API في مشروعك، سواء باستخدام Spring Cloud Contract أو Pact.
ستتناول مقالة لاحقة كيفية اختبار التواصل المعتمد على الأحداث مع وسطاء Kafka.
¹يدعم Spring Cloud Contract الآن أيضًا اللغات غير المرتبطة بـ Spring وغير JVM.