محاكاة API واختبارها ذاتياً على VPS
شغّل WireMock لمحاكاة التبعيات وHurl للاختبارات على VPS واحد. خزّن stubs في Git، وشغّل الاختبارات في CI، واحفظ التقارير بعد إعادة البناء.
مهمتان تشتركان في مستودع واحد
محاكاة واجهات API واختبارها ذاتياً مهمتان مختلفتان، والتعامل معهما كمهمة واحدة يضيّع أسبوعاً. يحل خادم المحاكاة محل تبعية لا يمكنك استدعاؤها من CI: مزوّد دفع، أو API لشريك، أو خدمة upstream تفرض حدوداً للمعدل، أو خدمة لم يطلقها فريق آخر بعد. يستدعي مشغّل اختبارات API نقاط النهاية الخاصة بك بترتيب ثابت، ويتحقق من الاستجابات، وينقل القيم من استجابة إلى الطلب التالي.
تؤدي بعض الأدوات المهمتين. تتمثل المهمة الرئيسية لخادم المحاكاة في الرد على الطلبات. ولا يبدي مشغّل الاختبارات أي افتراض بشأن الاستجابة التي يعيدها مزوّد الدفع عند رفض البطاقة. وينتهي الأمر بمعظم الفرق التي تستأجر خادماً بالفعل إلى تشغيل نسخة واحدة من كل نوع، ويبدأ تشغيلهما ملف Docker Compose نفسه، وتُراجع التغييرات عليهما في pull request نفسه.
لماذا تستضيف محاكاة API واختباراته ذاتياً؟
بيانات fixtures لديك تشبه بيانات الإنتاج. قد يكون نص الطلب في اختبار API سجلاً حقيقياً لعميل غُيّر اسمه، أو لم يُغيَّر لأن أحداً لم يتحقق منه. أما stubs المسجّلة فهي أسوأ؛ إذ يخزّن تسجيل proxy كل ما أعاده upstream فعلياً. لذلك قد يحتوي مجلد stubs الذي أُنشئ بالتسجيل على tokens نشطة وعناوين بريد إلكتروني للعملاء إلى أن يقرأ أحدهم كل ملف. في خدمة مستضافة، تتحول هذه البيانات إلى حادث أمني يخص جهة أخرى وإلى إفصاح منك.
السبب الثاني هو إمكانية الوصول. تحتاج خدمة مرتبطة بعنوان خاص إلى اتصال بشبكة خاصة قبل أن يتمكن runner مستضاف من الوصول إليها. لكل حل بديل تكلفة. نشر API على الإنترنت لاختباره يلغي سبب إبقائه خاصاً. أما tunnel أو نسخة staging عامة فهي نظام آخر يجب صيانته، كما أن نسخة staging تنحرف عن الإنتاج بين الإصدارات. يدعم GitHub-hosted runners أيضاً الوصول الخاص عبر طبقة WireGuard أو Azure Virtual Network. ويستدعي runner الموجود على الشبكة الخاصة نفسها الخدمة مباشرة، من دون الحاجة إلى أي من ذلك. وهذه هي الحجة العملية وراء runner ذاتي الاستضافة لـ GitHub Actions.
ما خادم المحاكاة الوهمي المستضاف ذاتياً الذي ينبغي تشغيله؟
يعمل كل خيار من هذه الخيارات كحاوية على خادم تملكه. السؤال الأهم هو ما الذي يعتبره كل خيار مصدر الحقيقة، لأن ذلك يحدد ما إذا كانت إعادة إنشاء الحاوية لن تكلفك شيئاً أو ستستغرق فترة طويلة من العمل.
- WireMock يحتفظ بكل stub كملف JSON في دليل
mappings/، ويضع أجسام الاستجابات الكبيرة في__files/. صورته هيwiremock/wiremock، ودليله الجذر داخل الحاوية هو/home/wiremock، كما يعمل كـproxy للتسجيل. وجود الملفات على القرص يعني أن المحاكي الوهمي يُدار في git مثل أي شفرة أخرى. - Mockoon CLI يحتفظ بواجهة API وهمية كاملة في ملف بيانات JSON واحد. ثبّته باستخدام
npm install -g @mockoon/cliوابدأ تشغيله باستخدامmockoon-cli start --data ./data-file.json، أو شغّل الصورةmockoon/cliمع ربط ذلك الملف بـbind mount. يحرر تطبيق سطح المكتب الملف نفسه، لذلك يظل التصميم عبر واجهة المستخدم الرسومية وإيداع النتيجة في المستودع متوافقين. - MockServer يعمل من الصورة
mockserver/mockserverويستمع على المنفذ 1080. تصل التوقعات عبر REST API الخاص به، وهذا مفيد من شفرة الاختبارات لكنه ينطوي على مخاطر عند النشر: يختفي التوقع الذي أُنشئ عبر طلب HTTP عند إعادة تشغيل الحاوية، وذلك افتراضياً. استخدم ملف تهيئة JSON الخاص به للـstubs التي يُفترض أن تكون دائمة. للاحتفاظ بالتغييرات وقت التشغيل، فعّلpersistExpectations، واحفظ ملف الإخراج خارج الحاوية، وحمّله عند بدء التشغيل عبرinitializationJsonPath. - Prism ينشئ المحاكي الوهمي من مستند OpenAPI بدلاً من ملفات stub منفصلة. ثبّته باستخدام
npm install -g @stoplight/prism-cli، ثم شغّله باستخدامprism mock openapi.yaml. داخل الحاوية، أضف-h 0.0.0.0، لأن Prism يرتبط بـlocalhost افتراضياً، وإلا فلن يكون قابلاً للوصول من خارج الحاوية. - Microcks هو الخيار الأكبر: يوفّر واجهة ويب تستورد مستندات OpenAPI ومجموعات Postman، ثم تعرضها كمحاكيات وهمية وتشغّل اختبارات العقود. يحتاج التثبيت الكامل إلى MongoDB وKeycloak، إضافة إلى Kafka لميزات المعالجة غير المتزامنة. تجمع الصورة
microcks-uberالكل في واحد نسخة MongoDB داخل الذاكرة، ويوثّق المشروع أنها مناسبة للاستخدام المؤقت؛ لذلك تعامل مع أي شيء تنشئه في واجهة المستخدم هذه على أنه مؤقت، واحتفظ بملفات المصدر في git.
أي مشغّل لاختبارات API ذاتية الاستضافة ينبغي أن تستخدم؟
المهمة هنا عبارة عن سلسلة: المصادقة، ثم إنشاء طلب، ثم قراءته، ثم التحقق من تغيّر حالته. يتطلب ذلك التقاط قيمة من استجابة واستخدامها في الطلب التالي. الأداة التي لا تستطيع الاحتفاظ بالحالة بين الاستدعاءات ليست سوى فحص للتوافر، وليست اختباراً لـAPI.
- Hurl يشغّل ملفات نصية عادية تحتوي على طلبات HTTP من ملف ثنائي واحد. يستخرج قسم
[Captures]القيم من الاستجابة، ويتحقق منها قسم[Asserts]، ويحوّلها قسم--testإلى مشغّل اختبارات يعرض ملخصاً ويرجع رمز خروج. الإصدار 8.0.1 هو الإصدار الحالي حتى August 2026. - Bruno CLI يشغّل مجلداً من ملفات
.bru. ثبّته باستخدامnpm install -g @usebruno/cli، ثم شغّله باستخدامbru run folder --env Local --reporter-junit results.xml. صُمّم تنسيق المجموعة على هيئة ملفات نصية داخل دليل، لذلك تكون الفروقات سهلة القراءة أثناء المراجعة. - Newman يشغّل مجموعات Postman خارج Postman:
npm install -g newman، ثمnewman run collection.json -r cli,junit --reporter-junit-export results.xml. لكن المشكلة في التنسيق. يشغّل Newman المجموعات المصدّرة بتنسيق JSON للإصدار v2.1. ويدعم Postman الآن أيضاً تنسيق المجموعات v3 وسير عمل Native Git عبر Postman CLI. توضح وثائق Postman أن Newman لن يتلقى مزيداً من التحديثات أو الإصلاحات، وتوصي بترحيل البرامج النصية وخطوط CI إلى Postman CLI. - Schemathesis هو نوع مختلف من الفحوص. يقرأ مخطط OpenAPI وينشئ حالات تحاول توليد استجابات يقول مخططك إنها مستحيلة:
uvx schemathesis run https://your.api/openapi.json. يعثر على حالات التعطل ومخالفات العقد، لكنه لا يعرف شيئاً عن قواعد عملك، لذلك يُستخدم إلى جانب مجموعة اختبارات مبرمجة بدلاً من استبدالها. - Hoppscotch ذاتية الاستضافة هي خيار واجهة الويب، وتتطلب مثيل Postgres. افهم هذه المقايضة قبل تثبيتها: تُخزَّن المجموعات في قاعدة بيانات، لا في مستودعك.
هناك أداة ينبغي تجنبها. لا تزال Step CI تظهر في قوائم الأدوات، كما أن تنسيق سير العمل بصيغة YAML فيها سهل القراءة، لكن المستودع تلقى آخر commit في August 2024. البرنامج الذي يقع بين CI وAPI لديك مكان سيئ لتشغيل تعليمات برمجية غير صيانتها مستمرة.
ضع خادم المحاكاة خلف جدار الحماية
يشغّل الإعداد أدناه WireMock بديلاً عن موفّر الدفع. إذا كان تنسيق ملف Compose جديداً عليك، يشرح Docker Compose على VPS أوامر دورة الحياة التي يفترضها هذا القسم.
services:
mock-payments:
image: wiremock/wiremock:3.13.2
command: ["--verbose"]
volumes:
- ./mocks/payments:/home/wiremock
ports:
- "127.0.0.1:8080:8080"
restart: unless-stoppedالبادئة 127.0.0.1: في المنفذ هي الجزء المهم. نشر المنفذ بصيغة 8080:8080 فقط يعرّض خادم المحاكاة على كل الواجهات، بما فيها عنوان IP العام، ويظل قابلاً للوصول حتى مع حظر ufw لذلك المنفذ، لأن Docker يوجّه حركة المرور المنشورة عبر جدول nat قبل أن تصل إلى قواعد INPUT الخاصة بـufw. اربط المنفذ بعنوان loopback حتى لا يكون المنفذ المنشور قابلاً للوصول إلا من المضيف، عند استخدام شبكة Docker الافتراضية bridge مع Engine 28.0.0 أو أحدث. تسمح الإصدارات الأقدم للمضيفين الموجودين على شبكة layer 2 نفسها بالوصول إلى المنافذ المنشورة على localhost. يظل الربط بعنوان واجهة خاصة يسمح بالوصول من الشبكات التي يمكنها التوجيه إلى ذلك العنوان.
بعد ذلك، وجّه خدمتك قيد الاختبار إلى خادم المحاكاة. عندما تعمل الخدمة في مشروع Compose نفسه، يكون عنوان URL الأساسي لخادم المحاكاة هو http://mock-payments:8080، لأن Compose يحل أسماء الخدمات على شبكته الخاصة. وعندما تعمل الخدمة على المضيف، يكون العنوان http://127.0.0.1:8080. اضبط ذلك عبر متغير بيئة، ولا تضعه في الشيفرة، وإلا سينتقل عنوان URL الخاص بالاختبار إلى بيئة الإنتاج.
ضع الـstubs في ./mocks/payments/mappings/، بحيث يحتوي كل ملف على JSON واحد.
{
"request": {
"method": "POST",
"urlPath": "/v1/charges",
"bodyPatterns": [{ "matchesJsonPath": "$.amount" }]
},
"response": {
"status": 201,
"headers": { "Content-Type": "application/json" },
"jsonBody": { "id": "ch_test_001", "status": "succeeded", "amount": 4200 }
}
}شغّله، ثم تحقّق مما تم تحميله فعلياً.
docker compose up -d --wait mock-payments
curl -fsS http://127.0.0.1:8080/__admin/mappingsينتظر --wait حتى يبلّغ الـcontainer عن سلامته، وهذا ممكن لأن صورة WireMock تتضمن HEALTHCHECK لنقطة النهاية /__admin/health. يعرض استدعاء mappings كل stub قرأه الخادم. إذا كان stub كتبته مفقوداً من هذه القائمة، فهذا يعني أنه لم يُحمّل قط: تحقّق من وجود الملف ضمن mappings/ وليس في جذر المسار المركّب، وتحقّق من إمكانية تحليل JSON.
عندما يصل طلب ولا يطابق أي stub، يجيب WireMock بـ 404. وإذا عثر على تطابق قريب، يبدأ جسم الاستجابة بـ Request was not matched، ثم يعرض فرقاً مقارنة بأقرب stub. عند عدم وجود أي تعيينات للـstubs، يكون جسم الاستجابة No response could be served as there are no stub mappings in this WireMock instance.. اقرأ الفرق عند وجوده قبل تغيير أي شيء، لأنه يحدد الحقل الدقيق المختلف. يكون هذا الحقل عادةً مساراً يتضمن /v1/charge، بينما يحدد الـstub القيمة /v1/charges.
اكتب الاختبار كسلسلة من الطلبات مع الاحتفاظ بالحالة بين الاستدعاءات
ملفات Hurl ملفات نصية عادية. ثبّت حزمة deb من إصدارات المشروع.
VERSION=8.0.1
curl --location --remote-name https://github.com/Orange-OpenSource/hurl/releases/download/$VERSION/hurl_${VERSION}_amd64.deb
sudo apt update && sudo apt install ./hurl_${VERSION}_amd64.debتوجد مجموعة اختبارات تختبر API الخاص بك مقابل الخادم الوهمي في tests/checkout.hurl.
POST {{base_url}}/orders
Content-Type: application/json
{
"sku": "ssd-1tb",
"amount": 4200
}
HTTP 201
[Captures]
order_id: jsonpath "$['id']"
GET {{base_url}}/orders/{{order_id}}
HTTP 200
[Asserts]
jsonpath "$.status" == "paid"
jsonpath "$.charge_id" == "ch_test_001"كتلة [Captures] هي ما يجعل هذا اختباراً لـAPI، وليس طلبين غير مرتبطين. تُقرأ order_id من الاستجابة الأولى، وتُدرج في عنوان URL للطلب الثاني. يمثل التأكيد على charge_id الهدف الأساسي من الاختبار: فهو يثبت أن خدمتك استدعت موفر الدفع وخزّنت الاستجابة التي أعادها، والقيمة التي يقارن بها هي القيمة التي كتبتها في إعداد WireMock الوهمي. يغطي ملف واحد الآن نصفي التدفق.
hurl --test --variable base_url=http://127.0.0.1:3000 \
--report-junit reports/junit.xml \
--report-json reports/json \
tests/يعرض التشغيل الناجح سطراً واحداً لكل ملف، ثم يعرض ملخصاً.
tests/checkout.hurl: Success (2 request(s) in 61 ms)
Executed files: 1
Executed requests: 2 (30.1/s)
Succeeded files: 1 (100.0%)
Failed files: 0 (0.0%)
Duration: 64 msيعرض الفشل error: Assert failure مع اسم الملف ورقم السطر، ثم يعرض القيمة التي حصل عليها مقابل القيمة المتوقعة، ويخرج hurl بحالة غير صفرية، لذلك تتوقف CI. إذا قرأت status القيمة pending بينما كنت تتوقع paid، فهذا يعني أن خدمتك لم تعالج استجابة الخادم الوهمي. اقرأ بعد ذلك سجل طلبات WireMock في /__admin/requests، فهو يوضح ما إذا كان الاستدعاء قد وصل إلى الخادم الوهمي أصلاً.
شغِّل مجموعة الاختبارات من مشغّل CI الخاص بك
عند تسجيل مشغّل على الخادم نفسه، يكون سير العمل قصيراً. المشغّل مجرد عملية عادية على المضيف، لذلك يجب تثبيت docker وhurl على ذلك المضيف. لا يرث المشغّل أي شيء من صورة مستضافة.
name: api-tests
on: [push]
jobs:
hurl:
runs-on: self-hosted
steps:
- uses: actions/checkout@v4
- name: Start the mock
run: docker compose up -d --wait mock-payments
- name: Run the suite
run: hurl --test --variable base_url=http://127.0.0.1:3000 --report-junit reports/junit.xml tests/
- name: Archive the reports
if: always()
run: install -d /srv/api-tests/reports/$GITHUB_SHA && cp -r reports/. /srv/api-tests/reports/$GITHUB_SHA/
- name: Stop the mock
if: always()
run: docker compose downوجود if: always() في خطوة الأرشفة مهم. من دونه، يؤدي فشل تشغيل الاختبارات إلى تخطي النسخ، فتفقد التقرير الذي أردت قراءته تحديداً. يجب أن تُحفظ النسخة أيضاً خارج مساحة العمل، لأن actions/checkout@v4 ينفّذ git clean -ffdx افتراضياً قبل الجلب، ما يزيل التقارير غير المتتبعة من دليل المستودع عند عملية checkout التالية.
احتفظ بالنتائج، وليس بنتيجة آخر تشغيل فقط
يجيب ملف JUnit XML واحد لكل commit عن سؤال واحد: هل نجح الاختبار؟ لكنه لا يوضح متى بدأ أحد endpoint في الاستجابة ببطء أكبر، لأن لا شيء يقرأ هذه الملفات بعد التوقف عن فتحها. لمتابعة الاتجاهات، أضف صفاً واحداً لكل تشغيل إلى قاعدة بيانات صغيرة على الخادم نفسه. يكفي جدول واحد يحتوي على SHA الخاص بـcommit، واسم الملف، وعدد حالات النجاح، وعدد حالات الفشل، والمدة. ويُعد SQLite في بيئة الإنتاج على VPS مكاناً مناسباً لذلك: ملف واحد، ومن دون عملية خادم، كما أن السجل الكامل ينتقل معك ضمن النسخة الاحتياطية التي تنشئها بالفعل. حلّل مخرجات Hurl بتنسيق --report-json للحصول على بيانات التشغيل التفصيلية؛ فكلا JSON وJUnit XML قابل للقراءة آلياً.
ما الذي يجب أن يبقى بعد إعادة بناء الحاوية
تعريفات المحاكاة ومجموعات الاختبار شيفرة مصدرية. يجب وضعها في مستودع بجانب الخدمة التي تصفها، وتغييرها في طلب السحب نفسه الذي يغيّر نقطة نهاية. يحتاج أي stub جرى تعديله في واجهة ويب، أو أي expectation أُرسلت إلى MockServer عبر REST API أثناء التشغيل، إلى إعداد للتصدير أو الاستمرارية حتى يبقى بعد إعادة البناء. يؤدي تشغيل docker compose down إلى فقدان ذاكرة الحاوية والطبقات القابلة للكتابة؛ أما البيانات المخزنة في bind mounts أو named volumes فتبقى. وإذا كانت مستودعاتك تعمل أيضاً على أجهزتك الخاصة، فإن خادم git مستضاف ذاتياً يبقي fixtures والخدمة داخل نطاق ثقة واحد.
إليك القواعد العملية. ثبّت وسوم الصور، لأن latest قد يغيّر طريقة مطابقة mock للطلبات من دون أي تغيير في مستودعك، ومن الصعب جداً ربط هذا الفشل بسببه. اربط أدلة stubs للقراءة فقط عندما لا تحتاج الأداة إلى الكتابة فيها. لا تضع stubs الخاصة بـmock في named Docker volume، لأن volume يصبح عندئذ مصدر الحقيقة، وتصبح النسخة الموجودة في git غير صحيحة بصمت.
هناك قاعدة أخرى، وهي تتسبب في أخطاء كثيرة. إذا أنشأت stubs بتسجيل حركة الشبكة الفعلية عبر proxy، فاقرأ كل ملف مُنشأ قبل إيداعه. يحتوي التسجيل على كل ما أعاده upstream حرفياً، بما في ذلك bearer tokens وعناوين البريد الإلكتروني للعملاء. يؤدي إيداعه إلى وضع هذه البيانات في مستودعك بشكل دائم، لأن git يحتفظ بالمحتوى المحذوف في السجل.
FAQ
ما الفرق بين خادم محاكاة API ومشغّل اختبارات API؟
يجيب خادم المحاكاة عن الطلبات. ويحل محل تبعية لا يمكنك استدعاؤها من CI؛ كما تنفّذ بعض الأدوات اختبارات التوافق وتبلغ عن نتائجها. يرسل مشغّل اختبارات API الطلبات إلى خدمتك، ويتحقق من الاستجابات، وينقل القيم من استدعاء إلى الاستدعاء التالي، وينتهي برمز غير صفري عند فشل أحد التحققات. يحل كل منهما مشكلة مختلفة. وعادةً ما يشغّلهما الإعداد معاً: يستدعي المشغّل خدمتك، بينما تستدعي خدمتك خادم المحاكاة.
هل يمكنني اختبار API داخلية من مشغّل CI مستضاف؟
نعم، باستخدام شبكة خاصة. تدعم المشغّلات المستضافة من GitHub شبكة WireGuard تراكبية أو Azure Virtual Network للوصول إلى الموارد الخاصة من دون نشر API للعامة. ويُعد نشر API أو تشغيل نفق أو الحفاظ على نسخة staging عامة خيارات أخرى، لكن كل خيار يضيف نظاماً يمكن أن يفشل أو يسرّب البيانات. يستدعي المشغّل الموجود على الشبكة الخاصة نفسها الخدمة مباشرة. وهذا هو السبب العملي الرئيسي لاستضافة الفرق لهذا العمل ذاتياً.
أين يجب أن توجد stubs المحاكاة ومجموعات اختبارات API؟
في git، بجوار الخدمة التي تصفها. تمنحك الأدوات التي تخزّن التعريفات في ملفات، مثل مجلد mappings/ في WireMock، وملف البيانات في Mockoon، وملفات Hurl، ومجلد .bru في Bruno، إمكانية مراجعة التعليمات البرمجية وإعادة بناء الحاوية دون تكلفة تُذكر. أما الأدوات التي تخزّن التعريفات في قاعدة بيانات أو واجهة ويب فتحتاج إلى خطة نسخ احتياطي وخطوة تصدير. وغالباً ما ينسى الأشخاص التصدير حتى تصبح الحاوية قد اختفت بالفعل.
لماذا يعيد mock لديّ الاستجابة 404 مع أن stub تبدو صحيحة؟
يقدّم WireMock stub فقط عندما يستوفي الطلب أدوات المطابقة المكوّنة لها. يحصل الطلب غير المطابق على 404؛ وعند وجود تطابق قريب، يبدأ نص الاستجابة بـ Request was not matched، ثم يعرض فرقاً مقارنةً بأقرب stub. ويسمّي هذا الفرق الحقل المختلف. عند عدم وجود تخطيطات stub، يوضّح نص الاستجابة بدلاً من ذلك أن المثيل لا يحتوي على أي تخطيطات. تشمل الأسباب الشائعة وجود شرطة مائلة زائدة في المسار، أو رأس Content-Type تتطلبه stub ولم يرسله العميل، أو استخدام urlPath حيث تحتاج stub إلى urlPathPattern لجزء متغير من المسار، أو عدم توافق أداة مطابقة النص مع الحمولة. افحص /__admin/requests أولاً للتأكد من أن الطلب وصل إلى mock أصلاً.
هل ما زلت أحتاج إلى mocks إذا كانت لديّ بيئة staging؟
نعم، لسببين. قد تتوقف نسخة staging من خدمة upstream لا تتحكم فيها، وقد تفرض أيضاً حدوداً على المعدل. لذلك قد تفشل مجموعة الاختبارات لأسباب لا علاقة لها بالتعليمات البرمجية لديك. كما أنها لا تستطيع إنتاج الاستجابات التي تحتاج إلى اختبارها أكثر من غيرها، مثل رفض بطاقة أو انتهاء مهلة البوابة. يعيد mock هذه الاستجابات عند الطلب وبسرعة الشبكة المحلية، فتحوّل مجموعة اختبارات تستغرق دقائق عند تشغيلها ضد sandbox إلى مجموعة تستغرق ثواني. احتفظ بـstaging للفحص النهائي قبل الإصدار، واستخدم mocks في CI.