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


تعريف العقد
العقود هي العنصر المحوري في هذا النوع من الاختبار. يتيح لنا Spring Cloud Contract وصفها بلغة DSL (لغة خاصة بمجال محدد) مريحة، يمكن كتابتها بـ Groovy أو Java أو Kotlin أو حتى YAML. يحدد العقد كيفية تواصل المُنتِج (producer) مع مستهلكيه (consumers). يصف العقد أدناه كيف يستخدم order-service واجهة REST API الخاصة بـ payment-service. وهو مكتوب بـ Groovy ويغطي المسار السعيد لعملية دفع عبر الإنترنت.
Contract.make {
name "should execute online payment"
request {
method 'PUT'
urlPath $(consumer(regex('/payment/' + uuid())))
body([
accountId : $(consumer(anyUuid())),
quota : $(consumer(regex('^(\\d+\\.\\d+)$')), producer(1024.50)),
paymentType: $(consumer(regex('^TRANSFER_(OFFLINE|ONLINE)$')), producer('TRANSFER_ONLINE')),
dueDate : $(consumer(anyDateTime()))
])
headers {
accept 'application/json'
contentType 'application/json'
}
}
response {
status OK()
body([
paymentExternalId: "ext-${fromRequest().path(1)}",
status : "FINISHED",
])
headers {
contentType('application/json')
}
}
}
مكان العقود هو /src/contractTest/resources، حيث يمكن ترتيبها في مجلدات ومجلدات فرعية – مثلًا مجلد لكل مستهلك. هنا يوجد العقد في payment-service/src/contractTest/resources/contracts/orderService، لأنه يخص order-service.
الطلب (Request)
الجزءان الأساسيان في العقد هما كتلتا الطلب والاستجابة. تحدد كتلة الطلب كيف ينبغي أن يبدو الاستدعاء الموجَّه إلى الواجهة. فهي تعلن الطريقة PUT ومسارًا معطى كتعبير نمطي: /payment/ متبوعًا بـ UUID. قد تبدو هذه الصياغة غامضة بعض الشيء في البداية، وسأعود إليها بعد قليل.
يلي ذلك جسم الطلب المتوقع، بأربعة حقول إلزامية: accountId, quota, paymentType، وdueDate. قد تبدو قيمها معقدة، لكننا سنفككها بعد لحظات. والجزء الأخير من كتلة الطلب يسرد الترويسات المطلوبة: تتوقع الواجهة Accept وContent-Type، وكلاهما مضبوط على application/json.
بعد أن غطّينا الأساسيات، لنفكّ الأجزاء التي تجاوزناها، بدءًا من تعريف عنوان URL.
urlPath $(consumer(regex('/payment/' + uuid())))
التعبير $(consumer(…)) هو الطريقة التي نعلن بها ما يسمى بالخصائص الديناميكية – وهي قيم نفضّل ألا نثبّتها في العقد، مثل المعرّف أو الطابع الزمني. فتثبيتها سيجبر المستهلك على استخدام هذه القيم بعينها في اختباراته، وهذا بعيد عن المثالي. نريد أن يتمتع فريق المستهلك بحرية في كتابة اختباراته، ولذلك يكون التعبير النمطي هو الخيار الأفضل. هنا اعتمدنا على الدالة المضمّنة uuid()، التي توفّر تعبيرًا نمطيًا يطابق UUID.
ما كتبناه أعلاه هو في الحقيقة اختصار للتعبير التالي:
urlPath $(consumer(regex('/payment/' + uuid())), producer('/payment/42cc610b-575d-4a52-9fba-4a43e8d3cfe9'))
تحدد consumer() القيم المقبولة عند استدعاء هذه الواجهة، وهذه القيم هي التي تنتهي في الـ stub. هنا يُقبل أي عنوان URL يتكون من /payment/ وUUID صالح. بعبارة أخرى، يجوز لاختبارات المستهلك استخدام أي UUID بدل قيمة بعينها.
وتحدد producer() القيمة المستخدمة عند اختبار واجهة المُنتِج. لا يكفي هنا التعبير النمطي، لأن الاختبار يجب أن يستدعي الواجهة بعنوان URL محدد (مثل /payment/42cc610b-575d-4a52-9fba-4a43e8d3cfe9). ولأن التعبير الكامل طويل نسبيًا، يتيح Spring Cloud Contract حذف الجزء producer()، كما فعل عقدنا. وفي هذه الحالة تُولَّد القيمة المستخدمة في اختبار الواجهة من التعبير النمطي المعطى في consumer().
يُعرَّف الحقلان accountId وdueDate في جسم الطلب بالطريقة نفسها. أما quota وpaymentType فقد زوّدناهما بتعبيراتنا النمطية الخاصة.
quota : $(consumer(regex('^(\\d+\\.\\d+)$')), producer(1024.50)),
paymentType: $(consumer(regex('^TRANSFER_(OFFLINE|ONLINE)$')), producer('TRANSFER_ONLINE'))
يجب أن تكون quota عددًا عشريًا موجبًا، ومن المؤسف أن Spring Cloud Contract لا يوفر دالة مضمّنة لذلك، بخلاف UUID. القائمة الكاملة بدوال التعابير النمطية المضمّنة موجودة في التوثيق. وبالمثل، paymentType هو enum قيمته إما TRANSFER_ONLINE أو TRANSFER_OFFLINE. لذلك علينا كتابة التعابير النمطية بأنفسنا وتوفير القيمة المستخدمة في اختبار الواجهة (producer()).
الاستجابة (Response)
تصف كتلة response ما يرسله المُنتِج في المقابل للطلب المعطى. معظمها واضح بذاته: حالة HTTP وجسم الاستجابة والترويسات. الشيء الوحيد الذي قد يكون مفاجئًا هو تعريف paymentExternalId.
paymentExternalId: "ext-${fromRequest().path(1)}"
نريد أن يكون هذا الحقل دائمًا ext- متبوعًا بـ paymentId (الذي يستقبله payment-service كمعامل في مسار URL). ولأن paymentId معرَّف بتعبير نمطي (UUID صالح)، فلا يمكن تثبيته – بل يجب أن يكون تمامًا القيمة المرسلة في عنوان URL. وهنا يأتي دور الدالة fromRequest(): فهي تتيح للاستجابة الإشارة إلى قيم من الطلب. كنا بحاجة إلى paymentId، وهو العنصر الثاني في المسار، وتتيح لنا الدالة path(n) الوصول إليه. N هو فهرس عنصر المسار بدءًا من 0. وتوجد دوال مماثلة لقراءة القيم من جسم الطلب والترويسات وغيرها – وهي مسرودة هنا.
اختبار المُنتِج
بعد أن أصبح العقد جاهزًا، نريد التحقق مما إذا كانت واجهة المُنتِج تتصرف فعلًا كما هو موصوف. لا نحتاج إلى كتابة أي اختبارات يدويًا لذلك – فهي تُولَّد من العقود. ولتفعيل ذلك مع Spring Cloud Contract أضف الإضافة والاعتمادية التاليتين إلى مشروع المُنتِج.
plugins {
(...)
id 'org.springframework.cloud.contract' version '4.0.0'
}
(...)
dependencies {
(...)
testImplementation 'org.springframework.cloud:spring-cloud-starter-contract-verifier:4.0.0'
}
الإضافة (plugin) هي التي تولّد الاختبارات من العقود. يفترض المقتطف أعلاه أن مشروعك يحتوي أصلًا على الاعتماديات اللازمة لتشغيل تطبيق Spring Boot واختباره (مثل spring-boot-starter-web وspring-boot-starter-test).
يتطلب توليد اختبارات المُنتِج وتشغيلها قدرًا من إعداد Spring Cloud Contract.
contracts {
baseClassForTests = "pl.rmaciak.payment.BaseContractTestsSpec"
testFramework = "SPOCK"
}
كحد أدنى، لا بد من ضبط baseClassForTests فقط. ويحدد المعامل الثاني أن الاختبارات ينبغي كتابتها بـ Spock. يسمّي baseClassForTests الصنف الذي يرثه كل اختبار مولَّد، وعلى هذا الصنف أن يجهّز الخادم المستخدم أثناء الاختبارات. وهناك طريقتان لذلك:
- محاكاة الخادم (mock) باستخدام مثل RestAssured أو MockMvc. وهذه هي الطريقة الافتراضية والموصى بها.
- تشغيل الخادم، مثلًا بـ @SpringBootTest. عندها تتجه الاختبارات إلى خادم حقيقي بدل المحاكاة. ولاختبار بهذه الطريقة اضبط testMode في الإعدادات على EXPLICIT.
يستخدم مثالنا RestAssuredMockMvc. وخيارات الإعداد الأخرى موصوفة هنا.
أي خيار أختار؟
قد يبدو أن الاختبار على خادم حقيقي يستمع للطلبات أفضل من محاكاته. لكن تذكّر أن اختبار العقود يتعلق بالتواصل، فلا حاجة إلى تشغيل كود الإنتاج الكامل.
وعادةً ما يكفي خادم محاكى يعرض المتحكمات (controllers) مع استبدال اعتمادياتها بـ stubs. فهذه الطبقة هي التي تحدد كيفية عمل التواصل. أما منطق الأعمال الذي يستدعيه المتحكم فليس مطلوبًا ويمكن استبداله بـ stub.
لتوليد الاختبارات وتشغيلها نفّذ:
./gradlew check
عندما تطابق الواجهة العقد ينبغي أن ينجح البناء. وإلا فستحصل على خطأ يصف المشكلة.
هذا يؤكد أن الاختبارات وُلّدت وشُغّلت فعلًا. لنلقِ الآن نظرة تحت الغطاء لنرى ما حدث.
داخل مجلد البناء (build)، تحت generated-test-sources، ستجد الصنف OrderServiceSpec الذي ولّده Spring Cloud Contract تلقائيًا.
يرث الصنف BaseContractTestsSpec الذي ضبطناه في الإعدادات، ويحتوي على اختبار Spock (الذي ضُبط في الإعدادات أيضًا) يتحقق من أن الخادم يتصرف كما يحدد العقد. افتراضيًا يفحص الاختبار المولَّد الخادم عبر Spring MockMvc، لكن يمكن أيضًا اختبار الواجهة بالطرق التالية:
- SpringMockMvc من Rest assured. وهذا هو الافتراضي.
- SpringWebTestClient من Rest Assured. يتطلب ضبط testMode parameter على WebTestClient
- JaxRSClient. يتطلب ضبط testMode parameter على JaxRsClient
- وهناك أيضًا الوضع الخاص المذكور سابقًا – EXPLICIT، الذي يُشغَّل فيه الخادم وتُجرى استدعاءات HTTP حقيقية.
فيما يلي الاختبار المولَّد لعقدنا. يبني الطلب وفق العقد، ويستدعي الواجهة، ويتحقق من أن الاستجابة تطابق ما يتوقعه العقد. لا شيء لافت – سوى أن كل هذا الكود المتكرر وُلّد لنا فلم نضطر إلى كتابته. وهذا سيناريو واحد فقط. تخيّل السيناريوهات الأخرى: حالات تواصل محددة وحالات أخطاء وغيرها، مضروبة في كل نقطة نهاية (endpoint). هذا قدر كبير من العمل رُفع عن كاهلنا، أليس كذلك؟
def validate_should_execute_online_payment() throws Exception {
given:
MockMvcRequestSpecification request = given()
.header("Accept", "application/json")
.header("Content-Type", "application/json")
.body('''{"accountId":"f4459572-b7a8-4d2e-9f49-75009f9e7f6f","quota":1024.50,"paymentType":"TRANSFER_ONLINE","dueDate":"2018-08-18T12:23:34"}''')
when:
ResponseOptions response = given().spec(request)
.put("/payment/5ecbe91f-a1f7-baff-a9b3-55d48cbbf2fb")
then:
response.statusCode() == 200
response.header("Content-Type") ==~ java.util.regex.Pattern.compile('application/json.*')
and:
DocumentContext parsedJson = JsonPath.parse(response.body.asString())
assertThatJson(parsedJson).field("['paymentExternalId']").matches("ext-5ecbe91f-a1f7-baff-a9b3-55d48cbbf2fb")
assertThatJson(parsedJson).field("['status']").isEqualTo("FAILED")
}
مثل هذه الاختبارات (التي تغطي عادةً سيناريوهات أكثر) تتحقق من صحة الواجهة. والخطوة التالية هي التحقق من أن المستهلك يستدعي هذه الواجهة بشكل صحيح.
اختبار المستهلك
على الفريق المسؤول عن خدمة المستهلك أن يكتب اختبارات تؤكد أن خدمته تتكامل مع الواجهة بشكل صحيح. يمكن أن تعمل هذه الاختبارات على مستويات متعددة: فقد تغطي عميل HTTP فقط، أو قد تتحقق من أن منطق الخدمة يتصرف بشكل سليم عند التفاعل مع الخدمة الأخرى – وهذا ما تفعله اختبارات التكامل أساسًا. الفرق الجوهري أننا مع Spring Cloud Contract لا نكتب الـ stubs بأنفسنا. بل نستخدم تلك المولَّدة من عقد المُنتِج.
وبالنظر مرة أخرى إلى مجلد البناء في payment-service ستلاحظ ملف JAR إضافيًا – payment-service-0.0.0.1-SNAPSHOT-stubs.jar
يحتوي هذا الـ JAR على الـ stubs ويمكن استخدامه لتشغيل خادم WireMock في اختبارات المستهلك. ويتولى Spring Cloud Contract Stub Runner ذلك.
testImplementation 'org.springframework.cloud:spring-cloud-starter-contract-stub-runner:4.0.0'
ويوفر الإشارة التوضيحية (annotation) AutoConfigureStubRunner التي تقبل عدة معاملات. في أبسط إعداد يلزم المعامل ids فقط. وهو يحدد ملفات stubs JAR التي ينبغي أن يستخدمها Wiremock لمحاكاة الخادم.
@SpringBootTest(classes = [OrderApplication])
@AutoConfigureStubRunner(
ids = ["com.rmaciak:payment-service:0.0.1-SNAPSHOT:stubs:8088"],
stubsMode = StubRunnerProperties.StubsMode.LOCAL
)
class OrderCreatorWithContractSpec extends Specification {
(...)
}
هنا أشرت إلى ملف JAR المبني من العقود في payment-service. قد تبدو السلسلة داخل المصفوفة غريبة في البداية، فلنفككها.
- الجزء الأول هو groupId
- payment-service هو artifactId
- 0.0.0.1-SNAPSHOT – إصدار ملف stubs JAR. ويمكن أن يكون ‘+’، أي أن أحدث إصدار يُستخدم دائمًا
- stubs هو مُصنِّف (classifier) ملف JAR. وهو القيمة الافتراضية ويمكن حذفه.
- 8088 هو المنفذ الذي يستمع إليه خادم WireMock. وإذا لم يُحدَّد يُختار منفذ عشوائي.
أما معامل AutoConfigureStubRunner الآخر المستخدم في المثال فهو stubsMode.
وهو يقبل هذه القيم:
- LOCAL – تُجلب الـ stubs من المستودع المحلي (مثل مجلد /.m2 في Maven)، الذي ينبغي أن تعدّه أداة البناء لديك. وقد استخدمت هنا Maven.
- REMOTE – تُجلب الـ stubs من مستودع بعيد. وفي هذا الوضع يجب تحديد المستودع البعيد بالمعامل repositoryRoot.
- CLASSPATH – يُفحص مسار الأصناف (classpath) بحثًا عن الـ stubs المعرَّفة. وهذا هو الافتراضي.
معاملات الإشارة التوضيحية الأخرى مسرودة في التوثيق.
بعد تشغيل الـ stubs يمكننا اختبار الكود الذي يجري استدعاء HTTP إلى الخدمة الأخرى.
def "should create order and initiate offline payment"() {
given:
def accountId = randomUUID()
def orderId = randomUUID()
def quota = BigDecimal.valueOf(120.99)
expect:
sut.createOrder(accountId, orderId, quota, TRANSFER_OFFLINE).paymentProcessed()
}
لاحظ أنه لا يُعدّ هنا أي stub آخر – فـ Stub Runner يتولى كل ذلك.
عند هذه النقطة يكون كل من المُنتِج والمستهلك قد اختُبر مقابل العقد المتفق عليه. وعندما تنجح اختبارات الخدمتين في خط CI/CD يمكننا الاطمئنان إلى أنهما متكاملتان بشكل صحيح وشحنهما إلى الإنتاج بأمان.
وبطبيعة الحال، تعرض هذه المقالة عقدًا واحدًا فقط كمثال. أما القيام بذلك على الوجه الصحيح فسيتطلب على الأرجح عقودًا أكثر – مثلًا عند وجود استجابات خاصة بحالات استثنائية كالأخطاء. ومع ذلك، تذكّر الفخ الذي قد يقودك إليه اختبار العقود.
لننظر بعد ذلك كيف يتعامل Spring Cloud Contract مع نهجي Consumer Driven وProducer Driven.
اختبار العقود الموجَّه بالمستهلك باستخدام Spring Cloud Contract
للتذكير، في نهج Consumer Driven Contract يحدد المستهلك، وهو خدمة في الأعلى (upstream)، التواصل. ثم ينبغي للفريق المالك لخدمة المُنتِج (downstream) أن يبني الواجهة بالطريقة التي طلبها المستهلك (مع إعمال المنطق السليم). فيما يلي مثال على كيفية عمل فريق المستهلك.
يدعم Spring Cloud Contract سير العمل هذا. فعندما يرضى فريق المستهلك عن العقد يولّد الاختبارات (3) والـ stubs (5). ويمكنه بعدها أخذ ملف JAR المولَّد الذي يحتوي الـ stubs وتضمينه في مشروعه، وهذه هي طريقة عمل الوضع الافتراضي لـ stubsMode (CLASSPATH). لكن الخيار الأفضل هو نشرها في مستودع محلي، مثل مستودع Maven (.m2)، واستخدامها في اختبارات المستهلك – وهذا ما يفعله LOCAL stubsMode.
ينبغي أن يكون هذا حلًا مؤقتًا فقط إلى أن يبني فريق المُنتِج الواجهة. وعند الانتهاء ونجاح كل الاختبارات ينبغي نشر ملف stubs JAR إلى Artifactory البعيد (العام). عندها يمكن لفريق المستهلك تحويل stubsMode إلى REMOTE، فتُجلب الـ stubs دائمًا من Artifactory. اجمع ذلك مع ضبط إصدار الـ stub على الأحدث (+ في ids). عندها تعمل اختبارات المستهلك مقابل stubs تعكس العقد المتفق عليه مع المُنتِج، مما يجعلها جديرة بالثقة.
اختبار العقود الموجَّه بالمُنتِج باستخدام Spring Cloud Contract
لا يملك Spring Cloud Contract دعمًا مخصصًا لاختبار العقود الموجَّه بالمُنتِج (Producer Driven). في هذا النهج يملك المُنتِج العقود، ويقبلها المستهلكون ببساطة دون أن يكون لهم رأي. لذلك على فريق الدفع أن يكتب العقد ويبني الواجهة وفقه. بعد ذلك يمكن توليد الـ stubs وتسليمها إلى المستهلكين لاستخدامها في اختباراتهم. وتتوقف طريقة مشاركتها على الظروف – Artifactory أو Nexus أو مستودع Git وغيرها. وإلى جانب إتاحة اختبار التكامل، تعمل الـ stubs أيضًا كشكل من التوثيق لسلوك واجهة المُنتِج.
الخلاصة
عرضت هذه المقالة كيفية وصف عقد واجهة REST API باستخدام Spring Cloud Contract وكيفية اختبار كل من المُنتِج والمستهلك مقابله. وتعرّفت في أثناء ذلك على اللبنات الأساسية للإطار وإعداده الأولي. كما تناولت طريقتين لاستخدام Spring Cloud Contract في اختبار العقود – Consumer Driven وProducer Driven.
بعد قراءة هذه المقالة ينبغي أن تكون مستعدًا لاعتماد Spring Cloud Contract في مشروعك.