دليل إعداد ReadyAPI Jenkins CI: بديل أسهل

باختصار

يمكن تشغيل اختبارات ReadyAPI في Jenkins عبر أداة سطر الأوامر testrunner ومكون SmartBear Jenkins الإضافي، ولكنها تتطلب تثبيت ReadyAPI على وكلاء البناء وتتضمن صعوبات متكررة في التكوين. يعمل دمج Apidog في CI/CD من خلال واجهة سطر أوامر بسيطة مثبتة عبر npm، دون الحاجة إلى متطلبات برمجيات الوكيل ودون ترخيص لكل عملية تشغيل.

💡

Apidog هو نظام أساسي مجاني وشامل لتطوير واجهات برمجة التطبيقات (API) مزود بمشغل CLI خفيف الوزن يتكامل مع Jenkins و GitHub Actions وخطوط الأنابيب الأخرى دون الحاجة إلى ترخيص إضافي. جرب Apidog مجانًا، لا يلزم وجود بطاقة ائتمان.

زر

مقدمة

يعد دمج اختبارات واجهة برمجة التطبيقات (API) في مسار CI/CD أحد أكثر الإجراءات قيمة التي يمكن لفريق الاختبار القيام بها. إن اكتشاف الأخطاء التراجعية في كل طلب سحب، قبل وصول الكود إلى بيئة الاختبار أو الإنتاج، يستحق جهد الإعداد.

يدعم ReadyAPI التكامل مع Jenkins من خلال آليتين: أداة سطر الأوامر testrunner والمكون الإضافي الرسمي SmartBear Jenkins. كلاهما يعمل، ولكن كل واحد منهما يأتي مع تعقيدات. يغطي هذا الدليل كيفية إعداد ReadyAPI مع Jenkins، والمشكلات الشائعة التي ستواجهها، وكيف يوفر Apidog نفس التكامل مع خط الأنابيب بتكاليف بنية تحتية أقل.

إعداد ReadyAPI في Jenkins: نهج testrunner

testrunner هو محرك تنفيذ سطر الأوامر الخاص بـ ReadyAPI. عندما يحتاج Jenkins إلى تشغيل اختبارات ReadyAPI بدون واجهة رسومية (headless)، فإنه يستدعي testrunner مع وسيطات تشير إلى ملف مشروع.

المتطلبات الأساسية:

يجب تثبيت ReadyAPI على كل وكيل Jenkins يقوم بتشغيل اختبارات API. هذا هو أكبر متطلب تشغيلي. إذا كان لديك خمسة وكلاء بناء وتُشغل اختبارات ReadyAPI على أي منهم، فستحتاج جميع الوكلاء الخمسة إلى تثبيت ReadyAPI. هذا يخلق:

عبء صيانة التثبيت عند تحديث ReadyAPI.
سؤال حول الترخيص: هل يتطلب كل تثبيت للوكيل ترخيصًا خاصًا به؟ تختلف سياسة ترخيص CI/CD الخاصة بـ SmartBear حسب العقد. تأكد مع فريق حسابك.
زيادة حجم صورة الوكيل ووقت بدء التشغيل للوكلاء المستندين إلى السحابة.

أمر testrunner الأساسي:

على نظامي Linux/macOS:

/path/to/ReadyAPI/testrunner.sh \
  -r \
  -f /path/to/results \
  -s "TestSuiteName" \
  -c "TestCaseName" \
  /path/to/project.xml

على نظام Windows:

C:\ReadyAPI\testrunner.bat ^
  -r ^
  -f C:\results ^
  -s "TestSuiteName" ^
  -c "TestCaseName" ^
  C:\projects\project.xml

علامات testrunner الرئيسية:

-r: إنشاء تقرير XML متوافق مع JUnit
-f <directory>: دليل الإخراج للنتائج
-s <name>: تشغيل مجموعة اختبار محددة (تجاهلها لتشغيل الكل)
-c <name>: تشغيل حالة اختبار محددة (تجاهلها لتشغيل الكل)
-e <environment>: تحديد البيئة المراد استخدامها
-P <name>=<value>: تجاوز خصائص المشروع

خطوة مسار Jenkins:

في ملف Jenkinsfile:

stage('API Tests') {
  steps {
    sh '''
      /opt/readyapi/testrunner.sh \
        -r \
        -f ${WORKSPACE}/test-results \
        -e ${ENVIRONMENT} \
        ${WORKSPACE}/project.xml
    '''
    junit 'test-results/*.xml'
  }
}

تنشر خطوة junit النتائج إلى Jenkins حتى تظهر الإخفاقات في تقرير البناء.

استخدام مكون SmartBear Jenkins الإضافي

تحتفظ SmartBear بمكون إضافي لـ Jenkins خاص بـ ReadyAPI ومتاح من دليل مكونات Jenkins الإضافية. يوفر المكون الإضافي خطوة بناء في واجهة مستخدم Jenkins بدلاً من مطالبتك بكتابة أوامر shell يدويًا.

لتثبيته:

اذهب إلى Jenkins > إدارة Jenkins > مدير المكونات الإضافية.
ابحث عن "SmartBear ReadyAPI Functional Testing".
ثبت وأعد تشغيل Jenkins.

بعد التثبيت، يمكنك تكوين مسار تثبيت ReadyAPI في إعدادات Jenkins العامة، ثم إضافة خطوة اختبار ReadyAPI إلى مهمة البناء الخاصة بك عن طريق التحديد من القائمة المنسدلة لخطوات البناء.

يتعامل المكون الإضافي مع بناء الوسيطات لك ويدمج النتائج في تقارير اختبار Jenkins. بالنسبة للفرق التي تفضل تكوين واجهة المستخدم الرسومية (GUI) على نصوص مسار Groovy، يقلل المكون الإضافي من وقت الإعداد.

قيود المكون الإضافي: يرتبط المكون الإضافي بإصدارات معينة من Jenkins وإصدارات ReadyAPI. تتأخر تحديثات المكون الإضافي عن إصدارات ReadyAPI وإصدارات Jenkins على حد سواء. قد تواجه الفرق التي تستخدم أحدث إصدار من ReadyAPI مشكلات توافق تتطلب انتظار تحديث للمكون الإضافي.

المشكلات الشائعة في Jenkins + ReadyAPI

تعليق Testrunner عند بدء التشغيل. ReadyAPI هو تطبيق Java/Swing. عند تشغيله بدون واجهة رسومية (headless) في CI، يحاول أحيانًا تهيئة مكونات واجهة المستخدم الرسومية. قم بتعيين متغير البيئة DISPLAY أو استخدم وسيطات JVM -Djava.awt.headless=true إذا واجهت هذا.

فشل التحقق من الترخيص. يتحقق ReadyAPI من ترخيصه عند بدء التشغيل. إذا لم يتمكن وكيل CI من الوصول إلى خادم ترخيص SmartBear (وهو أمر شائع في الشبكات المغلقة للشركات)، تفشل الاختبارات بخطأ في الترخيص بدلاً من فشل الاختبار. تحتاج إلى تكوين إما إعدادات خادم الترخيص العائم أو الترخيص دون اتصال.

أخطاء نفاد الذاكرة. إعدادات كومة الذاكرة الافتراضية لـ JVM في testrunner متحفظة. قد تحتاج مجموعات الاختبار الكبيرة أو المشاريع التي تحتوي على العديد من ملفات البيانات إلى تعديل إعدادات -Xmx. قم بتحرير ملف testrunner.sh أو testrunner.bat لزيادة كومة الذاكرة:

-Xms128m -Xmx1024m

مشكلات المسار مع ملفات المشروع. تشير مشاريع ReadyAPI إلى الملفات الخارجية (مصادر البيانات، المخططات، النصوص البرمجية) باستخدام المسارات. عند التشغيل في CI، تعمل المسارات النسبية فقط إذا تم تعيين دليل العمل بشكل صحيح. تتسبب المسارات المطلقة في ملفات المشروع في مشكلات عند نقل المشروع بين الأجهزة. استخدم خصائص المشروع للمسارات وقم بتعيينها عبر علامات -P أثناء التشغيل.

تنجح الاختبارات محليًا ولكن تفشل في CI. غالبًا ما يحدث بسبب اختلافات البيئة: بيانات مختلفة في الملفات الخارجية، أو قيم مختلفة لمتغيرات البيئة، أو مسارات مشفرة. استخدم ميزة البيئة في ReadyAPI مع تحديد صريح للبيئة في وسيطة -e لـ testrunner.

دمج Apidog مع Jenkins: نهج أبسط

يتم تثبيت مشغل Apidog CLI عبر npm ولا يتطلب تطبيق سطح مكتب على وكيل البناء.

التثبيت على وكيل Jenkins:

npm install -g apidog-cli

أو في خطوة مسار:

npm ci
# apidog-cli is in devDependencies

تشغيل الاختبارات في ملف Jenkinsfile:

stage('API Tests') {
  steps {
    sh '''
      apidog run \
        --collection ${WORKSPACE}/apidog-collection.json \
        --environment staging \
        --reporter junit \
        --reporter-junit-export ${WORKSPACE}/results/report.xml
    '''
    junit 'results/report.xml'
  }
}

الاختلافات الرئيسية عن ReadyAPI:

لا يوجد تطبيق سطح مكتب على الوكلاء. Apidog CLI عبارة عن حزمة Node.js خفيفة الوزن. قم بتثبيته في ثوانٍ، وليس دقائق. لا توجد مشكلات في تهيئة واجهة المستخدم الرسومية، ولا متطلبات اتصال بخادم الترخيص.

لا توجد مخاوف بشأن الترخيص لكل عملية تشغيل. لا يفرض Apidog رسومًا لكل تنفيذ CI. قم بتشغيل أكبر عدد ممكن من دورات الاختبار يوميًا حسب متطلبات مسار عملك.

تكوين البيئة عبر متغيرات البيئة أو العلامات. قم بتمرير بيانات الاعتماد وعناوين URL الأساسية كمتغيرات بيئة مباشرة من مخزن بيانات اعتماد Jenkins:

withCredentials([string(credentialsId: 'api-key', variable: 'API_KEY')]) {
  sh 'apidog run collection.json -e production --env-var "apiKey=${API_KEY}"'
}

مقارنة مع GitHub Actions:

بالنسبة للفرق التي تستخدم GitHub Actions أيضًا، فإن نهج Apidog نظيف بنفس القدر:

- name: Run API tests
  run: |
    npm install -g apidog-cli
    apidog run collection.json --environment staging
  env:
    API_BASE_URL: ${{ vars.STAGING_URL }}
    API_KEY: ${{ secrets.API_KEY }}

يتطلب مكافئ ReadyAPI إما مشغلًا مستضافًا ذاتيًا مع تثبيت ReadyAPI أو بناء صورة Docker معقدة. لا يوجد أي منهما بهذه البساطة.

ترحيل CI/CD من ReadyAPI إلى Apidog

إذا كنت تقوم بترحيل مجموعة الاختبار الخاصة بك وتحتاج إلى تحديث تكوين CI/CD في نفس الوقت:

قم بتصدير تعريفات API الخاصة بك من ReadyAPI واستوردها إلى Apidog.
قم بتثبيت Apidog CLI على وكلاء Jenkins الخاصين بك.
أضف خطوة اختبار Apidog إلى مسار عملك جنبًا إلى جنب مع خطوة ReadyAPI الحالية.
قم بتشغيل كليهما بالتوازي. قارن معدلات الفشل وتغطية الاختبار.
أزل خطوة ReadyAPI بمجرد أن تثق في تغطية Apidog.
أزل ReadyAPI من وكلاء البناء أثناء التحديث التالي لصورة الوكيل.

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

هل يتطلب testrunner الخاص بـ ReadyAPI ترخيص CI منفصلاً؟تختلف سياسة ترخيص SmartBear لاستخدام CI/CD حسب العقد. تتضمن بعض الاتفاقيات حقوق تنفيذ CI/CD في الترخيص القياسي؛ بينما تتطلب اتفاقيات أخرى اتفاقية منفصلة. تحقق من عقدك أو اتصل بمدير حساب SmartBear الخاص بك قبل افتراض أن عمليات تشغيل CI مشمولة.

هل يمكن تشغيل اختبارات ReadyAPI في حاويات Docker؟نعم، بجهد. يمكنك بناء صورة Docker مع تثبيت ReadyAPI واستخدامها كحاوية وكيل Jenkins. الصورة كبيرة (ReadyAPI هو تطبيق سطح مكتب) وتتطلب تكوينًا بدون واجهة رسومية. يعمل، ولكنه يضيف تعقيدًا مقارنة بالأدوات المصممة لبيئات CI المعتمدة على الحاويات.

هل يدعم Apidog تنفيذ الاختبار المتوازي في Jenkins؟نعم. يمكنك تشغيل عدة مثيلات من Apidog CLI في مراحل Jenkins المتوازية، كل منها يشغل مجموعة مختلفة أو بيئة مختلفة. يتم التحكم في التنفيذ المتوازي من خلال ملف Jenkinsfile الخاص بك، وليس من خلال Apidog CLI.

ما هو تنسيق تقرير الاختبار الذي ينتجه Apidog لـ Jenkins؟يمكن لـ Apidog CLI إنتاج تقارير JUnit XML، والتي يقوم Jenkins بتحليلها وعرضها بشكل أصلي في قسم نتائج الاختبار. التنسيق هو نفسه الذي ينتجه testrunner الخاص بـ ReadyAPI.

هل تعمل نصوص اختبار Apidog البرمجية في نفس عملية تشغيل CLI؟نعم. يتم تنفيذ نصوص اختبار JavaScript البرمجية ضمن عملية Node.js الخاصة بـ Apidog CLI. لا توجد بيئة تنفيذ نصوص برمجية منفصلة لتكوينها.

هل يوجد مكون إضافي رسمي لـ Apidog Jenkins؟يعمل Apidog CLI كخطوة shell في Jenkins، ولا يتطلب مكونًا إضافيًا مخصصًا. هذا النهج أبسط في الصيانة من عمليات التكامل المعتمدة على المكونات الإضافية التي تحتاج إلى تحديث عند إصدار Jenkins أو Apidog لإصدارات جديدة.

يعمل تكامل ReadyAPI مع Jenkins، ولكنه يتطلب إدارة بنية تحتية كبيرة. بالنسبة للفرق التي ترغب في تبسيط إعداد CI/CD الخاص بها مع الحفاظ على تغطية اختبار API شاملة، فإن نهج Apidog CLI يزيل نقاط الضعف الأكثر شيوعًا: متطلبات برمجيات الوكيل، واعتماد خادم الترخيص، وتكوين البيئة المعقد.