DEV Community

Cover image for كيفية استخدام سكربتات Pre-Request و Post-Response في Apidog
Yusuf Khalidd
Yusuf Khalidd

Posted on • Originally published at apidog.com

كيفية استخدام سكربتات Pre-Request و Post-Response في Apidog

تتطلب بعض طلبات API منطقًا قبل الإرسال أو بعد وصول الاستجابة: توقيع HMAC، توليد طابع زمني، استخراج رمز مصادقة، أو التحقق من رمز الحالة ومعرف الطلب. تنفيذ ذلك يدويًا يصبح هشًا عند مشاركة الطلبات مع الفريق. في Apidog، يمكنك تشغيل JavaScript تلقائيًا قبل الطلب وبعده باستخدام واجهة pm المتوافقة بدرجة كبيرة مع Postman.

جرّب Apidog اليوم

يمكنك كتابة سكريبتات JavaScript مرتبطة بكل طلب: معالجات مسبقة لتجهيز الطلب، ومعالجات لاحقة للتحقق من الاستجابة واستخراج قيم منها. راجع توثيق JavaScript ووثائق Apidog للبرمجة النصية للتفاصيل الكاملة.

ما تفعله المعالجات المسبقة واللاحقة

يشغّل Apidog السكريبتات في مرحلتين:

  • المعالجات المسبقة (Pre Processors): تعمل قبل إرسال الطلب. استخدمها لتوليد طابع زمني، حساب توقيع، تعيين معرف طلب، أو تجهيز الرؤوس.
  • المعالجات اللاحقة (Post Processors): تعمل بعد وصول الاستجابة. استخدمها للتحقق من الحالة، اختبار بنية JSON، واستخراج رمز أو معرف مورد للاستخدام لاحقًا.

القاعدة الأساسية:

  • لا تستخدم pm.response في المعالج المسبق، لأن الاستجابة لم تصل بعد.
  • استخدم المتغيرات لتمرير القيم بين المراحل والطلبات، مثل pm.environment.set() وpm.environment.get().

إذا كنت تستخدم Postman، ستتعرف على واجهة pm، لكن أسماء التبويبات في Apidog مختلفة:

Postman Apidog
Pre-request Script Pre Processors
Tests Post Processors

الإعداد: إضافة سكريبت إلى طلب

افتح الطلب داخل Apidog، ثم انتقل إلى أحد التبويبين:

  • Pre Processors
  • Post Processors

اختر Add a Custom Script واكتب JavaScript في المحرر.

يعالج Apidog المتغيرات حسب الأولوية التالية:

المتغيرات المحلية (Local Variables) > متغيرات البيئة (Environment Variables) > المتغيرات العامة المشتركة داخل المشروع (Global Variables Shared within Project) > المتغيرات العامة المشتركة داخل الفريق (Global Variables Shared within Team)

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

مثال: توقيع طلب HMAC في معالج مسبق

لنفترض أن نقطة نهاية الدفع تتطلب توقيع HMAC-SHA256 مبنيًا على طابع زمني ونص الطلب. هذا نمط شائع في التحقق من الطلبات وwebhooks، وتشرح وثائق Stripe للتوقيع الفكرة نفسها.

1. أضف السكريبت

في تبويب Pre Processors، أضف السكريبت التالي:

// المعالج المسبق: توقيع الطلب قبل إرساله
const CryptoJS = require('crypto-js');

// طابع Unix زمني بالثواني
const timestamp = Math.floor(Date.now() / 1000).toString();

// المفتاح السري من البيئة
const secret = pm.environment.get('payments_api_secret');

// بناء النص المراد توقيعه
const body = pm.request.body ? pm.request.body.toString() : '';
const payload = timestamp + '\n' + body;

// HMAC-SHA256 بتنسيق hexadecimal
const signature = CryptoJS
  .HmacSHA256(payload, secret)
  .toString(CryptoJS.enc.Hex);

// حفظ القيم لاستخدامها في الرؤوس
pm.environment.set('x_timestamp', timestamp);
pm.environment.set('x_signature', signature);

pm.console.log('تم توقيع الطلب في ' + timestamp);
Enter fullscreen mode Exit fullscreen mode

2. أضف الرؤوس

في تبويب Headers، أضف:

X-Timestamp: {{x_timestamp}}
X-Signature: {{x_signature}}
Enter fullscreen mode Exit fullscreen mode

عند الإرسال، ينفذ Apidog المعالج المسبق أولًا، ثم يستبدل {{x_timestamp}} و{{x_signature}} بالقيم المحسوبة.

استخدم require('crypto-js') لاستيراد المكتبة كاملة. لا تستخدم مسار وحدة فرعية مثل require('crypto-js/sha256').

لمزيد من أمثلة أنماط التوقيع المتوافقة مع Postman، راجع سكريبتات Postman ما قبل الطلب.

مثال: استخراج رمز مميز والتحقق من الاستجابة

افترض أن طلب تسجيل الدخول يعيد الاستجابة التالية:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 4812,
    "email": "dana@example.com"
  },
  "expires_in": 3600
}
Enter fullscreen mode Exit fullscreen mode

في تبويب Post Processors، أضف السكريبت التالي:

// المعالج اللاحق: التحقق من الاستجابة ثم استخراج الرمز
pm.test('الحالة هي 200', function () {
  pm.response.to.have.status(200);
});

const jsonData = pm.response.json();

pm.test('الاستجابة تُرجع رمزًا مميزًا', function () {
  pm.expect(jsonData.token).to.be.a('string').and.not.empty;
});

pm.test('معرف المستخدم موجود', function () {
  pm.expect(jsonData.user.id).to.be.a('number');
});

// حفظ الرمز لاستخدامه في طلبات لاحقة
pm.environment.set('auth_token', jsonData.token);

pm.console.log('تم حفظ الرمز المميز للمستخدم ' + jsonData.user.email);
Enter fullscreen mode Exit fullscreen mode

بعد تنفيذ طلب تسجيل الدخول، يمكن للطلبات الأخرى استخدام الرمز مباشرة:

Authorization: Bearer {{auth_token}}
Enter fullscreen mode Exit fullscreen mode

تساعد pm.test() وpm.expect() على تحويل الفحص اليدوي إلى اختبار قابل للتكرار. راجع تأكيدات واجهة برمجة التطبيقات في Apidog لتوسيع الاختبارات، وFaker.js في Apidog عند الحاجة إلى بيانات اختبار واقعية.

انتبه إلى السلوكين التاليين:

  • pm.iterationData للقراءة فقط.
  • pm.cookies يمثل ملفات تعريف الارتباط الواردة مع الاستجابة، وليس ملفات تعريف الارتباط المرسلة مع الطلب.

إعادة استخدام المنطق عبر Public Scripts

لا تنسخ سكريبت HMAC إلى عشرات الطلبات. استخدم Public Scripts بدلًا من ذلك.

  1. افتح Settings > Public Scripts.
  2. أنشئ السكريبت المشترك.
  3. أضفه إلى قائمة Pre Processors أو Post Processors في الطلبات المطلوبة.

ترتيب التنفيذ مهم:

  1. تعمل Public Scripts أولًا.
  2. تعمل Custom Scripts بعدها.
  3. عند وجود عدة Public Scripts، تعمل من الأعلى إلى الأسفل.

إذا أردت استدعاء دالة من Public Script داخل Custom Script، يجب تعريفها كدالة عامة:

// Public Script
sign = function (payload, secret) {
  const CryptoJS = require('crypto-js');

  return CryptoJS
    .HmacSHA256(payload, secret)
    .toString(CryptoJS.enc.Hex);
};
Enter fullscreen mode Exit fullscreen mode

ثم استدعها في السكريبت المخصص الذي يليها:

// Custom Script
const timestamp = Math.floor(Date.now() / 1000).toString();
const secret = pm.environment.get('payments_api_secret');

pm.environment.set('x_timestamp', timestamp);
pm.environment.set('x_signature', sign(timestamp, secret));
Enter fullscreen mode Exit fullscreen mode

لا تستخدم const أو let أو var عند تعريف الدالة المشتركة، وإلا ستبقى محلية داخل السكريبت الأول.

المكتبات والحزم والتصحيح

يوفر Apidog عدة مكتبات مدمجة يمكنك استيرادها عبر require():

  • crypto-js للإصدارات والتوقيعات HMAC
  • jsrsasign لعمليات JWT وRSA، ويتطلب Apidog 1.4.5 أو أحدث
  • chai لتأكيدات الاختبار
  • lodash
  • moment
  • uuid
  • xml2js
  • cheerio
  • postman-collection
  • atob
  • btoa
  • csv-parse/lib/sync
  • tv4
  • ajv

كما تتوفر مكتبات Node مدمجة، مثل:

path, assert, buffer, util, url, querystring, stream, events
Enter fullscreen mode Exit fullscreen mode

إذا لم تكن الحزمة متوفرة، استخدم $$.liveRequire() لتحميلها وقت التشغيل:

$$.liveRequire('nanoid', (nanoid) => {
  const id = nanoid.nanoid();
  pm.environment.set('request_id', id);
});
Enter fullscreen mode Exit fullscreen mode

يتطلب $$.liveRequire() اتصالًا بالإنترنت، بينما لا تحتاج المكتبات المدمجة إلى ذلك.

تصحيح السكريبتات

استخدم أحد الخيارين التاليين:

pm.console.log('قيمة التوقيع:', signature);
Enter fullscreen mode Exit fullscreen mode 
console.log('رمز المصادقة:', jsonData.token);
Enter fullscreen mode Exit fullscreen mode

ستظهر المخرجات في لوحة تحكم Apidog بعد تشغيل الطلب.

قيود مهمة

  • يستخدم pm.sendRequest() نمط callback، وليس async/await.
  • pm.nextRequest() غير مدعوم.
  • لتنسيق تدفق متعدد الخطوات، استخدم سيناريوهات الاختبار في Apidog مع خطوات Condition وIf-Else.

أتمتة السيناريوهات باستخدام Apidog CLI

تعمل المعالجات المسبقة واللاحقة أيضًا عند تشغيل Test Scenario عبر CLI، ما يجعل توقيع الطلبات واستخراج الرموز جزءًا من CI.

ثبّت CLI، ثم سجّل الدخول وشغّل السيناريو:

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <SCENARIO_ID> -e <ENV_ID> -r cli
Enter fullscreen mode Exit fullscreen mode

المعاملات الأساسية:

المعامل الوصف
-t معرف Test Scenario
-e معرف البيئة
-r نوع التقرير: cli أو html أو junit

يمكنك فصل عدة تقارير بفواصل في -r.

تأكد من أن سكريبتاتك لا تعتمد على ملفات محلية أو حزم متاحة فقط على جهازك. استخدم المكتبات المدمجة أو $$.liveRequire() لتعمل السكريبتات بالطريقة نفسها على سطح المكتب وداخل CI.

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

هل سكريبتات Apidog متوافقة مع Postman؟

نعم، في معظم الحالات. تدعم Apidog واجهة pm، بما في ذلك:

pm.environment.set();
pm.response.json();
pm.test();
pm.expect();
Enter fullscreen mode Exit fullscreen mode

الاختلاف الرئيسي هو أسماء التبويبات وبعض الاستدعاءات غير المدعومة مثل pm.nextRequest().

لماذا تكون pm.response غير معرفة في المعالج المسبق؟

لأن الاستجابة لم تصل بعد. انقل أي كود يقرأ الحالة أو الرؤوس أو النص الأساسي إلى Post Processors. إذا احتجت بيانات قبل الإرسال، اقرأها من pm.request أو من المتغيرات. راجع استرجاع معاملات الطلب في سكريبتات ما قبل وما بعد الطلب.

كيف أشارك سكريبتًا بين عدة طلبات؟

استخدم Settings > Public Scripts، ثم أرفق السكريبت بكل طلب يحتاجه. تذكر أن Public Scripts تعمل قبل Custom Scripts في القائمة نفسها.

هل يمكن استيراد حزم npm خارجية؟

نعم، باستخدام:

$$.liveRequire('اسم-الحزمة', (pkg) => {
  // استخدم الحزمة هنا
});
Enter fullscreen mode Exit fullscreen mode

أما الحزم المدمجة مثل crypto-js وmoment وuuid، فاستخدم معها require() مباشرة.

أين أرى مخرجات console.log()؟

استخدم pm.console.log() أو console.log()، ثم افتح لوحة تحكم Apidog بعد إرسال الطلب.

الخلاصة

استخدم Pre Processors لتجهيز الطلبات: التواقيع، الطوابع الزمنية، والمعرفات. واستخدم Post Processors للتحقق من الاستجابات، واستخراج الرموز، وتخزين البيانات للطلبات اللاحقة.

انقل المنطق المتكرر إلى Public Scripts، وشغّل السيناريوهات عبر CLI عند دمج الاختبارات في CI. ابدأ بفتح Apidog، واختر طلبًا واحدًا، وأضف أول Custom Script للتحكم في دورة الطلب والاستجابة.

Top comments (0)