DEV Community

Cover image for كيفية إرجاع بيانات Mock الشرطية في Apidog (القواعد المخصصة وسكربتات Mock)
Yusuf Khalidd
Yusuf Khalidd

Posted on • Originally published at apidog.com

كيفية إرجاع بيانات Mock الشرطية في Apidog (القواعد المخصصة وسكربتات Mock)

المحاكاة الذكية (Smart mock) تمنحك واجهة برمجة تطبيقات (API) وهمية في ثوانٍ. تقرأ مخطط نقطة النهاية (endpoint schema) وتعيد بيانات معقولة: بريد إلكتروني يبدو حقيقيًا، وطابع زمني منطقي، واسم ليس xJ8kQ. لمعظم أعمال الواجهة الأمامية، يكفي ذلك لإزالة العوائق.

جرّب Apidog اليوم

لكن ستصل سريعًا إلى حالات لا تستطيع المحاكاة الذكية التعامل معها. قد تريد أن يعيد POST /login القيمة 200 لمستخدم معروف و401 لغيره، أو أن يعيد /orders/{id} طلبًا مشحونًا لمعرف واحد وطلبًا ملغيًا لمعرف آخر، أو أن تفرض 500 لاختبار معالجة الأخطاء قبل الإنتاج. تعيد المحاكاة الذكية شكل استجابة واحدًا لكل نقطة نهاية، لذلك لا يمكنها التفريع حسب الطلب.

يغطي Apidog هذه الفجوة بميزتين:

  • توقعات المحاكاة (Mock expectations): استجابات شرطية مبنية على قواعد.
  • سكريبتات المحاكاة (Mock scripts): منطق JavaScript للحالات التي لا تكفي فيها القواعد.

إذا كنت جديدًا في الأساسيات، ابدأ بـنظرة عامة على محاكاة API. سنستخدم Apidog في الأمثلة، بينما توثق مبادرة OpenAPI سير العمل القائم على العقد أولًا.

ماذا تعني المحاكاة الشرطية بالفعل

المحاكاة الشرطية هي قاعدة بسيطة:

عندما يبدو الطلب الوارد بهذا الشكل، أعد هذه الاستجابة.

يبني Apidog هذه القواعد من طبقتين:

  1. تخصيص على مستوى الحقل داخل المخطط: ثبّت قيمة حقل، أو استخدم تعبير Faker.js ديناميكيًا. تتحكم هذه الطبقة في محتوى الحقول، لكنها لا تزال تعيد شكل استجابة واحدًا لنقطة النهاية.
  2. توقع محاكاة للاستجابة الكاملة: قاعدة مسماة تحتوي على شروط اختيارية، وجسم استجابة، ورمز حالة، ورؤوس.

يمكن أن يكون التوقع بلا شروط ليعمل كاستجابة افتراضية ثابتة، أو يحتوي على شروط ليُرجع بياناته فقط عند تطابق الطلب. عند تجميع عدة توقعات، تحصل على تفرع حقيقي:

  • استجابة B عندما يتحقق الشرط A.
  • جسم خطأ عند غياب رأس محدد.
  • حمولة مختلفة لكل معلمة مسار.

القيم الديناميكية على مستوى الحقل أولًا

قبل إنشاء التفرعات، من المفيد فهم كيفية توليد قيم الحقول. يمكن لأي حقل نصي في مخطط نقطة النهاية استخدام تعبير Faker.js بالشكل التالي:

{{$category.method}}
Enter fullscreen mode Exit fullscreen mode

يحل Apidog التعبير من جديد في كل استدعاء محاكاة، اعتمادًا على أنواع الحقول المعرفة في JSON Schema.

{
  "id": "{{$number.int(min=1000,max=9999)}}",
  "customer": "{{$person.fullName}}",
  "email": "{{$internet.email}}",
  "product": "{{$commerce.productName}}",
  "shippingAddress": "{{$location.streetAddress}}, {{$location.city}}",
  "orderedAt": "{{$date.between(from='2024-01-01',to='2024-12-31',format='yyyy-MM-dd')}}"
}
Enter fullscreen mode Exit fullscreen mode

تدعم الأساليب المعلمات، لذلك يحدد هذا التعبير نطاق الرقم:

{{$number.int(min=1000,max=9999)}}
Enter fullscreen mode Exit fullscreen mode

ويمكنك أيضًا دمج نص ثابت مع عدة تعبيرات في الحقل نفسه. إذا احتجت إلى بيانات مرتبطة بمنطقة معينة، يدعم Apidog لغات محاكاة قابلة للتخصيص لتتوافق الأسماء والعناوين وأرقام الهواتف مع لغة أو بلد محدد. راجع مرجع Faker.js في Apidog للكتالوج الكامل.

إعداد قيم Faker.js الديناميكية

هذه هي مساحة المحاكاة الذكية: ديناميكية، لكنها ليست شرطية. للتفرع حسب الطلب، استخدم التوقعات.

شرح تفصيلي: نقطة نهاية تسجيل دخول تعيد 200 أو 401

لنفترض أن لديك:

POST /login
Enter fullscreen mode Exit fullscreen mode

ويستقبل جسم JSON يحتوي على username وpassword.

المطلوب:

  • المستخدم المعروف يحصل على 200 ورمز مميز.
  • أي مستخدم آخر يحصل على 401.

1. افتح علامة التبويب الصحيحة

يعتمد مكان الإعداد على وضع العمل:

  • في وضع DEBUG، افتح نقطة النهاية ثم علامة التبويب Mock.

علامة تبويب Mock في وضع DEBUG

  • في وضع DESIGN، افتح نقطة النهاية ثم علامة التبويب Advanced mock.

علامة تبويب Advanced mock في وضع DESIGN

كلاهما يفتح قائمة التوقعات نفسها. إذا لم يكن التطبيق مثبتًا لديك، نزّل Apidog ثم أنشئ أو استورد نقطة النهاية /login.

2. أضف توقع النجاح

  1. انقر على توقع جديد.
  2. سمِّ التوقع login-success.
  3. أضف شرطًا من نوع معلمة جسم (Body parameter).
  4. استخدم username في حقل الاسم.
  5. اضبط المقارنة على القيمة alice@example.com.

إعداد شرط username لتوقع المحاكاة

شروط معلمات الجسم تعمل مع JSON فقط، وتُطابق عبر مسار JSON. للخصائص المتداخلة، استخدم مسارًا نقطيًا مثل:

user.email
Enter fullscreen mode Exit fullscreen mode

أضف بيانات استجابة النجاح:

{
  "token": "mock-jwt-{{$string.uuid}}",
  "user": {
    "id": 4821,
    "username": "alice@example.com",
    "role": "member"
  }
}
Enter fullscreen mode Exit fullscreen mode

احفظ التوقع. رمز حالة HTTP الافتراضي هو 200، لذلك لا تحتاج إلى تعديله لمسار النجاح.

3. أضف توقع الفشل

  1. انقر على توقع جديد مرة أخرى.
  2. سمِّه login-failure.
  3. اترك الشروط فارغة ليعمل كقاعدة شاملة.
  4. أضف جسم الخطأ التالي: 
{
  "error": "invalid_credentials",
  "message": "اسم المستخدم أو كلمة المرور غير صحيحة."
}
Enter fullscreen mode Exit fullscreen mode

افتح علامة التبويب المزيد للتوقع، ثم اضبط رمز حالة HTTP على 401.

من علامة التبويب نفسها يمكنك أيضًا:

  • ضبط تأخير الاستجابة بالمللي ثانية.
  • إضافة رؤوس استجابة مخصصة.
  • استخدام تأخير مثل 400 مللي ثانية لاختبار مؤشر التحميل في الواجهة.

4. رتّب التوقعات بشكل صحيح

يقيّم Apidog التوقعات من الأعلى إلى الأسفل، ويفوز أول تطابق.

لذلك يجب أن يكون ترتيبك كالتالي:

  1. login-success
  2. login-failure

إذا وضعت القاعدة غير المشروطة أولًا، فستطابق جميع الطلبات ولن تصل أبدًا إلى قاعدة النجاح.

اختبر المسارين باستخدام عنوان URL للمحاكاة:

# مستخدم معروف -> 200 مع رمز مميز
curl -X POST https://<your-mock-host>/login \
  -H "Content-Type: application/json" \
  -d '{"username":"alice@example.com","password":"whatever"}'

# أي مستخدم آخر -> 401
curl -X POST https://<your-mock-host>/login \
  -H "Content-Type: application/json" \
  -d '{"username":"stranger@example.com","password":"whatever"}'
Enter fullscreen mode Exit fullscreen mode

شرح تفصيلي: أجسام مختلفة لـ /orders/{id} حسب الحالة

حالة شائعة أخرى هي التفريع حسب معلمة المسار. تريد أن يعيد:

  • /orders/5001 طلبًا مشحونًا.
  • /orders/5002 طلبًا ملغيًا.
  • أي معرف آخر طلبًا عامًا معلقًا.

أنشئ توقعًا لكل حالة.

الطلب المشحون

أنشئ توقعًا باسم order-shipped:

  • الشرط: معلمة المسار id تساوي 5001. 
{
  "id": 5001,
  "status": "shipped",
  "total": 129.90,
  "trackingNumber": "1Z{{$string.alphanumeric(length=16)}}",
  "shippedAt": "{{$date.recent(days=3,format='yyyy-MM-dd')}}"
}
Enter fullscreen mode Exit fullscreen mode

الطلب الملغي

أنشئ توقعًا باسم order-cancelled:

  • الشرط: معلمة المسار id تساوي 5002. 
{
  "id": 5002,
  "status": "cancelled",
  "total": 0,
  "cancelledAt": "{{$date.recent(days=1,format='yyyy-MM-dd')}}",
  "refundIssued": true
}
Enter fullscreen mode Exit fullscreen mode

أضف قاعدة شاملة

أضف توقعًا أخيرًا بلا شروط يعيد طلبًا معلقًا عامًا. بهذه الطريقة، يحصل أي معرف آخر على استجابة صالحة بدلًا من عدم وجود تطابق.

رتّب القواعد من الأكثر تحديدًا إلى الأقل تحديدًا:

  1. order-shipped
  2. order-cancelled
  3. قاعدة شاملة للحالة الافتراضية

يمكنك أيضًا دمج الشروط. مثلًا، أضف شرط رأس بجانب شرط المسار؛ يجب أن يتحقق الشرطان معًا لأن Apidog يجمع الشروط بمنطق AND.

لا تقتصر الشروط على الجسم والمسار. يمكنك المطابقة باستخدام:

  • معلمات الاستعلام (Query parameters)
  • معلمات الرأس (Header parameters)
  • ملفات تعريف الارتباط (Cookie parameters)
  • عناوين IP

فرض حالات الخطأ عند الطلب

لا تحتاج إلى خلفية معطلة لاختبار واجهة تتعامل مع الأخطاء. أنشئ توقعًا بشرط تتحكم به من العميل.

لفرض 500:

  1. أضف توقعًا جديدًا.
  2. أضف شرط رأس: 
   X-Mock-Scenario = server-error
Enter fullscreen mode Exit fullscreen mode
  1. أضف جسم الخطأ.
  2. من علامة التبويب المزيد، اضبط رمز حالة HTTP على 500. 
{
  "error": "internal_error",
  "requestId": "{{$string.uuid}}",
  "message": "حدث خطأ ما من جانبنا. يرجى إعادة المحاولة."
}
Enter fullscreen mode Exit fullscreen mode

الآن تعيد نقطة النهاية نفسها استجابة 200 افتراضيًا، وتعيد 500 فقط عند إرسال الرأس التالي:

-H "X-Mock-Scenario: server-error"
Enter fullscreen mode Exit fullscreen mode

استخدم الأسلوب نفسه لاختبار حالات مثل:

  • 404
  • 429 مع رأس Retry-After
  • 503

إذا كنت تريد التحقق من هذه الاستجابات في اختبارات آلية، راجع دليل تأكيدات API.

في المشاريع المشتركة، يمكن تشغيل أو إيقاف كل توقع بشكل مستقل للمحاكاة المحلية والسحابية. مثلًا، اترك قاعدة 500 مفعلة محليًا ومعطلة في المحاكاة السحابية التي يستخدمها زملاؤك.

عندما لا تكون القواعد كافية: سكريبتات المحاكاة

التوقعات تصريحية: تطابق شرطًا ثم تعيد استجابة. لكنها لا تنفذ حسابات.

استخدم سكريبت محاكاة عندما تحتاج إلى:

  • حقل مشتق من بيانات الطلب.
  • إجمالي محسوب من بنود الطلب.
  • جسم استجابة يتغير حسب عدة مدخلات.
  • منطق لا يمكن التعبير عنه بشروط ثابتة.

سكريبت المحاكاة هو JavaScript يعمل على استجابة المحاكاة. ستجده في قسم سكريبت المحاكاة أسفل علامة التبويب Mock، ويجب تفعيله من مفتاح التبديل.

يوفر السكريبت متغيرين عامين:

  • $$.mockRequest: لقراءة الطلب الوارد عبر getParam(key)، وheaders، وcookies، وbody، وformdata، وurlencoded.
  • $$.mockResponse: لتشكيل الاستجابة عبر setBody()، وsetCode()، وsetDelay()، وjson()، وخصائص headers وcode.

هذا مثال يحسب إجمالي طلب من عناصر منشورة ويعيد العملة المستخدمة:

const body = $$.mockRequest.body;
const items = body.items || [];

const subtotal = items.reduce((sum, item) => {
  return sum + item.price * item.quantity;
}, 0);

const currency = $$.mockRequest.headers["x-currency"] || "USD";

$$.mockResponse.setCode(201);
$$.mockResponse.setBody({
  orderId: Math.floor(Math.random() * 90000) + 10000,
  currency: currency,
  subtotal: subtotal,
  tax: Number((subtotal * 0.08).toFixed(2)),
  total: Number((subtotal * 1.08).toFixed(2))
});
Enter fullscreen mode Exit fullscreen mode

التدفق العملي هو:

  1. تنشئ المحاكاة الذكية استجابة أولية.
  2. يقرأ السكريبت $$.mockRequest و$$.mockResponse.
  3. يطبق منطقك.
  4. يستدعي setBody() وsetCode() أو setDelay() حسب الحاجة.
  5. يعيد المحرك الاستجابة النهائية.

يمكنك الرجوع إلى مرجع MDN JavaScript عند الحاجة إلى عمليات أكثر تقدمًا على المصفوفات أو التواريخ.

القاعدة المهمة: لا تخلط السكريبتات مع التوقعات

تعمل سكريبتات المحاكاة مع المحاكاة الذكية فقط. لا تعمل مع توقعات المحاكاة أو أمثلة الاستجابة.

إذا تطابق توقع مع الطلب:

  • يُعاد التوقع.
  • لا يتم تشغيل سكريبت المحاكاة.

لذلك اختر نهجًا واحدًا لكل نقطة نهاية:

  • استخدم التوقعات للتفرع بناءً على شروط ثابتة.
  • استخدم السكريبتات للنواتج المحسوبة المبنية على استجابة المحاكاة الذكية.

كيف يتم حل ترتيب الأولوية

يتبع Apidog هذا الترتيب لكل طلب محاكاة:

  1. يتحقق من التوقعات من الأعلى إلى الأسفل.
  2. يفوز أول توقع تتطابق جميع شروطه.
  3. إذا لم يتطابق أي توقع، يعود إلى أولوية طريقة المحاكاة (Mock method priority) في: إعدادات المشروع → إعدادات الميزة → إعدادات المحاكاة.
  4. عندها تنشئ المحاكاة الذكية الاستجابة، ويعمل سكريبت المحاكاة المرفق بها إن وجد.

النموذج الذهني بسيط:

قواعد محددة أولًا، وبيانات مولدة ثانيًا.

رتّب توقعاتك من الأكثر تحديدًا إلى الأقل، وأضف قاعدة شاملة في الأسفل إذا أردت استجابة افتراضية محددة. للحصول على أمثلة إضافية، راجع حالات استخدام محاكاة API.

ملاحظات تستحق المعرفة قبل النشر

ضع هذه القيود في الحسبان لتجنب جلسات تصحيح مربكة:

  • شروط المعلمات لا تدعم {{variables}}. متغيرات المشروع والبيئة في Apidog غير متاحة داخل توقعات المحاكاة.
  • شروط معلمات الجسم تدعم JSON فقط، ويجب أن تستخدم مسار JSON في حقل الاسم.
  • يجب أن يطابق تنسيق جسم الطلب مواصفات API. استخدم وضع form-data لنقاط نهاية النماذج بدل JSON.
  • لا توجد دالة logging داخل سكريبتات المحاكاة.
  • كائن pm غير متاح داخل سكريبتات المحاكاة، لأنه يخص بيئة مختلفة عن سكريبتات الاختبار.
  • لا يمكن استخدام متغيرات Apidog داخل سكريبتات المحاكاة؛ اجعل منطق السكريبت مستقلًا.

أتمتة سير العمل باستخدام Apidog CLI

المحاكاة في Apidog قدرة واجهة مستخدم وسحابية. يقدم محرك المحاكاة نقاط النهاية من عناوين URL للمحاكاة المحلية والسحابية، ولا يوجد أمر CLI ينشئ خادم محاكاة قيد التشغيل.

ما يضيفه Apidog CLI هو التحكم في الموارد التي تُبنى منها المحاكاة.

بما أن استجابات المحاكاة تعتمد على مخطط نقطة النهاية، فإن دقتها تعتمد على دقة مواصفاتك. يمكن للـ CLI ولعوامل البرمجة بالذكاء الاصطناعي التي تديرها، مثل Cursor وClaude Code وTrae وCodex، إنشاء نقاط النهاية والمخططات وتحديثها داخل مشروعك.

بعد إزالة عوائق الواجهة الأمامية بالمحاكاة، شغّل سيناريوهات الاختبار نفسها بدون واجهة رسومية في CI للتحقق من الخلفية الحقيقية مقابل العقد:

apidog run -t <scenario_id> -e <env_id> -r cli
Enter fullscreen mode Exit fullscreen mode

ينفذ هذا الأمر سيناريوهات الاختبار ويبلغ عن النتائج، بحيث تشترك المحاكاة والتحقق في مصدر حقيقة واحد. راجع دليل تثبيت Apidog CLI للإعداد، ثم اربطه بخط الأنابيب عبر Apidog CLI في GitHub Actions.

الأسئلة الشائعة

لماذا يتم تجاهل توقعاتي رغم أن الشرط يبدو صحيحًا؟

غالبًا السبب هو الترتيب أو عدم تطابق التنسيق. يقيّم Apidog التوقعات من الأعلى إلى الأسفل، لذلك ستلتقط قاعدة واسعة بلا شروط كل الطلبات إذا وُضعت قبل قاعدة محددة.

تحقق أيضًا من أن جسم الطلب يطابق المواصفات:

  • استخدم مسار JSON لأجسام JSON.
  • استخدم وضع form-data لنقاط نهاية النماذج.

راجع نظرة عامة على محاكاة API إذا احتجت إلى مراجعة الإعداد الأساسي.

هل يمكنني استخدام سكريبت محاكاة وتوقع محاكاة في الاستجابة نفسها؟

لا. تعمل سكريبتات المحاكاة مع المحاكاة الذكية فقط، ولا تعمل مع التوقعات أو أمثلة الاستجابة. إذا تطابق توقع، فلن يُنفذ السكريبت.

استخدم التوقعات للتفرع القائم على القواعد، والسكريبتات للنواتج المحسوبة.

كيف أعيد 401 أو 500 دون كسر الاستجابة الافتراضية 200؟

أضف توقعًا مخصصًا بشرط تتحكم به من العميل، مثل رأس HTTP. ثم افتح علامة التبويب المزيد واضبط رمز حالة HTTP المناسب.

تظل الاستجابة الافتراضية 200، ولا تعمل حالة الخطأ إلا عند تطابق الشرط.

هل يمكن للشروط استخدام متغيرات البيئة؟

لا. قيم Apidog بالشكل {{variable}} غير متاحة داخل توقعات المحاكاة. استخدم قيمًا حرفية في الشروط.

ماذا يحدث عندما لا يتطابق أي توقع؟

يعود Apidog إلى أولوية طريقة المحاكاة في:

إعدادات المشروع → إعدادات الميزة → إعدادات المحاكاة
Enter fullscreen mode Exit fullscreen mode

هناك تنشئ المحاكاة الذكية استجابة من المخطط. أضف توقعًا شاملًا بلا شروط إذا أردت fallback محددًا بدل ذلك.

الخلاصة

تتعامل المحاكاة الذكية مع الحالة العامة، بينما تتعامل توقعات المحاكاة مع أي سيناريو يحتوي على منطق "إذا":

  • 200 لمستخدم معروف و401 لغيره.
  • جسم طلب مختلف لكل حالة.
  • 500 عند الطلب.
  • استجابات مقيدة برؤوس أو معلمات أو عناوين IP.

استخدم سكريبت المحاكاة فقط عندما تحتاج إلى ناتج محسوب لا تستطيع القواعد التعبير عنه، وتذكر أنه يعمل مع المحاكاة الذكية وحدها.

رتّب توقعاتك من الأكثر تحديدًا إلى الأقل، ثم دع البيانات المولدة تعالج كل ما لا يطابق قاعدة مخصصة. نزّل Apidog وأنشئ أول محاكاة شرطية لك.

Top comments (0)