كيفية أتمتة اختبارات واجهات برمجة التطبيقات (API) في Travis CI باستخدام Apidog CLI

واجهة برمجة التطبيقات (API) الخاصة بك تعمل على جهازك. اختبارات الوحدة ناجحة. تقوم بدمجها ونشرها، وبعد ساعة يرسل لك زميل إشعارًا: نقطة نهاية /checkout تُرجع خطأ 500 لأي شخص لديه عربة تسوق فارغة. لم يكن الخطأ أبدًا في الكود الذي غيرته؛ بل كان في عقد بين خدمتين بعيدتين لم يقم أحد بإعادة اختباره. هذه هي الفجوة التي تملؤها اختبارات API على مستوى التكامل، وهي بالضبط نوع الفحص الذي تريد تشغيله تلقائيًا مع كل التزام (commit) بدلاً من أن يكون مجرد فكرة في ذهن أحدهم.

Travis CI هو أحد أقدم خدمات الدمج المستمر المستضافة، ولا يزال يؤدي مهمة واحدة بشكل جيد: يراقب مستودع Git الخاص بك، ويجهز بيئة نظيفة لكل دفع (push) وطلب سحب (pull request)، ويشغل أي أوامر تضعها في ملف .travis.yml. تستخدمه معظم الفرق لحلقات التجميع واختبار الوحدة. عدد أقل بكثير يستخدمونه لتشغيل اختبارات HTTP حقيقية ضد واجهة برمجة تطبيقات (API) قيد التشغيل، على الرغم من أن هذا هو المكان الذي تختبئ فيه الأخطاء المكلفة. السبب هو الاحتكاك. ربط أداة تشغيل اختبارات API بصندوق CI، وتمرير البيانات السرية بأمان، والحصول على إشارة نجاح/فشل مرة أخرى، أمر معقد بما يكفي ليتجاهله الناس.

يشرح هذا الدليل كيفية سد هذه الفجوة باستخدام أداة تشغيل سطر الأوامر من Apidog. تقوم بتصميم وتصحيح أخطاء اختبارات API الخاصة بك في تطبيق Apidog المكتبي، حيث يمكنك رؤية الطلبات والتأكيدات بشكل مرئي، ثم تشغيل نفس الاختبارات تمامًا بدون واجهة رسومية داخل Travis CI بأمر واحد. لا إعادة كتابة منطق الاختبار ككود، ولا الحفاظ على بيئة اختبار منفصلة. يغطي المقال المسار الكامل: ملف .travis.yml بسيط، تثبيت أداة التشغيل، تمرير رمز الوصول الخاص بك بأمان، اختيار ما سيتم تشغيله، إنشاء التقارير، وجعل البناء يفشل بوضوح عندما تتعطل نقطة نهاية. حمّل Apidog إذا كنت ترغب في المتابعة.

زر

لماذا تشغيل اختبارات API في CI على الإطلاق؟

تؤكد اختبارات الوحدة أن الدالة تُرجع القيمة الصحيحة. تؤكد اختبارات API أن دورة الطلب-الاستجابة بأكملها تعمل بشكل صحيح: المسار موجود، والمصادقة مفروضة، ورمز الحالة صحيح، ومخطط JSON متطابق، والقيم داخل الجسم سليمة. هذه أوضاع فشل مختلفة، والنوع الثاني هو الذي يواجهه المستخدمون فعلاً.

تشغيلها محليًا جيد حتى لا يكون كذلك. تعتمد عمليات التشغيل المحلية على تذكرك لتشغيلها، وعلى جهازك أن يطابق تكوين الإنتاج، وعلى عدم كونك في منتصف شرب قهوتك عندما يتسلل انحدار. يزيل الدمج المستمر كل هذه الأعذار الثلاثة. كل عملية دفع (push) تشغل نفس المجموعة في نفس البيئة، ويتم إرفاق النتيجة بالالتزام (commit) وطلب السحب (pull request) ليراها الجميع.

هناك فائدة أعمق لفرق API على وجه التحديد. عندما تعيش اختباراتك بجانب تصميم API الخاص بك، يظهر التغيير الجذري كتأكيد فاشل لحظة دفعه، وليس كتذكرة دعم. إذا كنت تريد الخلفية المفاهيمية حول مكان هذا في خط أنابيب التسليم، فإن شرح "ما هو CI/CD" هو قراءة مصاحبة جيدة؛ يركز هذا المقال على بناء Travis CI العملي.

ماذا تحتاج قبل البدء

ثلاثة أشياء، ومن المحتمل أن يكون لديك اثنان منها بالفعل.

مستودع Git متصل بـ Travis CI. الطبقة المجانية على travis-ci.com تعمل للمستودعات العامة والخاصة ضمن حدود الاستخدام.

مشروع Apidog يحتوي على سيناريو اختبار واحد على الأقل قمت ببنائه وتشغيله بنجاح في التطبيق المكتبي. سيناريو الاختبار في Apidog هو مجموعة مرتبة من طلبات API مع تأكيدات؛ فكر في الأمر كتدفق شامل من البداية إلى النهاية، مثل "تسجيل الدخول، إنشاء طلب، جلب الطلب، حذفه".
Node.js. يعمل Apidog CLI على Node، ويحتاج إلى الإصدار 16 أو أحدث. يوفر Travis Node جاهزًا في بيئة لغة node_js، لذا فهذا في الغالب إعلان سطر واحد.

إذا لم تكن قد بنيت سيناريو اختبار بعد، فافعل ذلك أولاً في التطبيق. الهدف من سير العمل هذا هو أن تقوم بتصحيح الأخطاء بصريًا مرة واحدة، ثم أتمتة العملية إلى الأبد. محاولة تأليف الاختبارات بشكل أعمى داخل سجل CI هي المسار البطيء. لأساسيات كتابة الفحوصات الجيدة، يغطي "تأكيدات API: دليل عملي" كيفية التحقق من رموز الحالة، وأجسام الاستجابة، ومخطط JSON قبل أن تدفع (push) أي شيء.

الخطوة 1: احصل على رمز الوصول ومعرف السيناريو الخاص بك

يقوم Apidog CLI بتشغيل اختباراتك المخزنة في السحابة بدون واجهة رسومية (headlessly)، لذا فهو يحتاج إلى جزأين من الهوية:

رمز وصول يثبت أن أداة التشغيل مسموح لها بقراءة مشروعك. أنشئه من إعدادات حساب Apidog الخاص بك ضمن رموز الوصول. عامله ككلمة مرور؛ فهو يمنح وصول API إلى بيانات مشروعك.
معرف سيناريو اختبار. افتح السيناريو في التطبيق المكتبي وانسخ المعرف الخاص به، أو استخدم خيار "تشغيل في CI/CD"، الذي ينشئ أمرًا جاهزًا مع معرف تم ملؤه مسبقًا.

أسهل طريقة للحصول على أمر صحيح أول مرة هي أن تدع Apidog يكتبه لك. داخل سيناريو الاختبار، ينتج خيار تشغيل CI/CD شيئًا مثل هذا:

apidog run --access-token <your-access-token> -t 5564321 -e 4417023 -r cli

هذا هو الشكل الكامل للأمر: المصادقة، الإشارة إلى سيناريو (-t)، الإشارة إلى بيئة (-e)، واختيار مُبلغ (-r). انسخ هذا، وتأكد من تشغيله على جهاز الكمبيوتر المحمول الخاص بك أولاً، وعندئذٍ فقط انقله إلى Travis. التحقق محليًا يوفر عليك عشرات الإنشاءات الفاشلة التي تستهلك وقتًا في تصحيح خطأ إملائي في الرمز.

الخطوة 2: تخزين الرمز كمتغير Travis مشفر

لا تلصق رمز الوصول الخاص بك أبدًا في ملف .travis.yml. هذا الملف ملتزم بـ Git، ورمز مسرب يمنح أي شخص إمكانية قراءة مشروع API الخاص بك. لدى Travis خياران آمنان.

الطريقة النظيفة هي متغيرات بيئة المستودع المحددة في واجهة مستخدم Travis الويب. اذهب إلى إعدادات المستودع الخاص بك على Travis، وابحث عن متغيرات البيئة، وأضف:

APIDOG_ACCESS_TOKEN بقيمة الرمز الخاص بك
APIDOG_ENV_ID بمعرف البيئة الذي تريد الاختبار عليه

اترك خيار "عرض القيمة في سجل البناء" معطلاً حتى لا يطبع الرمز أبدًا. يحقن Travis هذه المتغيرات في كل بناء كمتغيرات بيئة حقيقية، ويشير التكوين الخاص بك إليها بالاسم. هذا يبقي الأسرار خارج المستودع تمامًا، وهذا هو السلوك الذي تريده؛ إذا قام مساهم بنسخ المستودع (fork)، فلن يأتي الرمز الخاص بك معه.

إذا كنت تفضل كل شيء في الملف، فإن Travis يدعم أيضًا المتغيرات المشفرة عبر واجهة سطر الأوامر الخاصة به:

travis encrypt APIDOG_ACCESS_TOKEN="your-token-here" --add env.global

هذا يكتب كتلة مشفرة في ملف .travis.yml يمكن لبناء مستودعك فقط فك تشفيرها. كلا النهجين يعملان. مسار واجهة المستخدم أبسط لمعظم الفرق وأسهل في التدوير عند انتهاء صلاحية الرمز.

الخطوة 3: كتابة ملف .travis.yml

فيما يلي تكوين كامل وبسيط يقوم بتثبيت Apidog CLI ويشغل سيناريو واحدًا في كل عملية دفع (push) وطلب سحب (pull request):

language: node_js
node_js:
  - "18"

cache:
  npm: true

install:
  - npm install -g apidog-cli

script:
  - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 5564321 -e $APIDOG_ENV_ID -r cli

ثلاث كتل تقوم بالعمل. language: node_js مع إصدار يمنحك بيئة تشغيل Node حديثة بما يكفي لواجهة سطر الأوامر (CLI). خطوة install تثبت apidog-cli بشكل عام بحيث يكون أمر apidog في المسار. خطوة script تشغل اختباراتك. المُبلغ -r cli يطبع ملخصًا واضحًا للنجاح/الفشل مباشرة في سجل Travis، وهو ما ستحدق فيه عندما يتعطل شيء ما.

لاحظ أن معرف السيناريو مكتوب بشكل ثابت ولكن الأسرار تأتي من متغيرات البيئة. هذا هو التقسيم الصحيح: المعرف غير حساس، الرمز هو الحساس. التزم بهذا الملف، ادفع، ويشغل Travis اختبارات API الخاصة بك تلقائيًا. أول بناء ناجح (أخضر) هو اللحظة التي تحصل فيها واجهة برمجة التطبيقات (API) الخاصة بك على شبكة أمان.

إذا كنت تحافظ على العديد من الخدمات وتريد نموذجًا ذهنيًا مشتركًا عبر أدوات التشغيل، فإن دليل "أتمتة اختبارات API في CI/CD" يوضح نفس النمط مطبقًا على منصات أخرى، وإصدار GitHub Actions متطابق تقريبًا في الروح إذا قمت بالترحيل في أي وقت.

الخطوة 4: اجعل البناء يفشل عندما يفشل الاختبار

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

الأخبار الجيدة: Apidog CLI يقوم بالشيء الصحيح بالفعل. عندما يفشل تأكيد، تخرج عملية apidog run برمز حالة غير صفري، ويعامل Travis أي خروج غير صفري في مرحلة script كفشل بناء. لذا، فإن التكوين البسيط أعلاه يفشل بشكل صحيح جاهزًا للاستخدام. لا تحتاج إلى ربط إضافي.

ما يمكنك تعديله هو كيف يتصرف التشغيل في منتصف السيناريو عندما يحدث خطأ في طلب واحد. تتحكم العلامة --on-error في ذلك:

--on-error end يوقف السيناريو عند أول فشل. أسرع تغذية راجعة، إخراج أقل.
--on-error continue يشغل الخطوات المتبقية لترى كل فشل في مرور واحد.
--on-error ignore يستمر ولا يدع الأخطاء توقف التشغيل.

بالنسبة لـ CI، continue هو عادة الخيار الأمثل: تريد الصورة الكاملة لما تعطل دون أن تتوقف المهمة بعد أول تأكيد فاشل، مع استمرار الانتهاء بخروج غير صفري حتى يفشل البناء. سطر برنامج نصي معقول يبدو كالتالي:

script:
  - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 5564321 -e $APIDOG_ENV_ID -r cli --on-error continue

تجنب إغراء إضافة || true إلى الأمر "لجعل البناء يمر." هذا يبتلع رمز الخروج ويعيد تقديم النقطة العمياء ذاتها التي سعيت لإزالتها.

الخطوة 5: إنشاء تقرير HTML والاحتفاظ به

المُبلغ cli جيد لإلقاء نظرة سريعة، ولكن عندما يفشل البناء، غالبًا ما تريد نتيجة أكثر تفصيلاً: أي طلب، أي تأكيد، وماذا كان جسم الاستجابة الفعلي. ينشئ CLI تقرير HTML باستخدام المُبلغ html، ويمكنك تجميع المُبلغين في تشغيل واحد.

script:
  - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 5564321 -e $APIDOG_ENV_ID -r cli,html --out-dir ./apidog-reports

-r cli,html يطبع إلى السجل ويكتب ملف HTML مستقل. --out-dir يحدد مكان تخزين التقرير، والافتراضي هو ./apidog-reports. لجعل هذا التقرير يبقى بعد انتهاء البناء، انشره في مكان يمكن لـ Travis النشر إليه، مثل حاوية S3 أو صفحات GitHub، في كتلة deploy. نمط شائع:

deploy:
  provider: pages
  skip_cleanup: true
  github_token: $GITHUB_TOKEN
  local_dir: apidog-reports
  on:
    branch: main

إذا كنت لا تفضل إدارة تخزين النتائج على الإطلاق، فيمكن لـ CLI دفع التقرير إلى سحابة Apidog باستخدام --upload-report، حيث يمكن لفريقك فتحه من رابط بدون أي استضافة إضافية. هذا هو الخيار الأقل صيانة للفرق الموزعة.

الخطوة 6: إضافة البيئات والبيانات وتشغيل المصفوفات

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

بيئات متعددة. تحدد علامة -e عناوين URL الأساسية والمتغيرات لأي بيئة سيتم استخدامها. قم بتشغيل نفس السيناريو مقابل بيئة التجربة (staging) في كل دفع (push) ومقابل بيئة الإنتاج في بناء cron ليلي عن طريق تبديل معرف البيئة. يتم تكوين مهام Travis cron لكل مستودع في واجهة إعدادات المستخدم.

تشغيل يعتمد على البيانات. علامة -d (الشكل الطويل --iteration-data) تغذي ملف CSV أو JSON في السيناريو الخاص بك بحيث يعمل مرة واحدة لكل صف. هذه هي الطريقة التي تغطي بها حالات الحافة: مدخلات صالحة، حقول مفقودة، حمولات كبيرة جدًا، أحرف خاصة، كل ذلك من تعريف سيناريو واحد. اقرنه بـ -n (--iteration-count) عندما تريد عددًا ثابتًا من التكرارات بدلاً من تكرارات مدفوعة بالملف.

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 5564321 -e $APIDOG_ENV_ID -d ./test-data.csv -r cli

سيناريوهات متوازية. تتيح لك مصفوفات بناء Travis تشغيل عدة سيناريوهات في وقت واحد عبر وظائف متوازية. حدد مصفوفة متغيرات البيئة حيث يحمل كل إدخال معرف سيناريو مختلفًا، وتشغل كل مهمة مصفوفة واحدًا. يصبح البناء ناجحًا (أخضر) فقط عندما تنجح جميعها.

env:
  - SCENARIO_ID=5564321   # checkout flow
  - SCENARIO_ID=5564322   # auth flow
  - SCENARIO_ID=5564323   # search flow

script:
  - apidog run --access-token $APIDOG_ACCESS_TOKEN -t $SCENARIO_ID -e $APIDOG_ENV_ID -r cli

مع نمو المجموعات، فإن تنظيم السيناريوهات في مجموعات اختبار لاختبار API الآلي يحافظ على قابلية إدارة المصفوفة بدلاً من أن تصبح جدارًا من المعرفات.

لماذا يتفوق هذا على كتابة الاختبارات يدويًا في سكربت CI الخاص بك

يمكنك كتابة اختبارات API مباشرة في سكربت Travis باستخدام curl و jq، أو كتشغيل Newman لمجموعة مصدرة. كلاهما يعمل، وكلاهما يشيخ بشكل سيء.

يحول نهج curl بالإضافة إلى الشل كل تأكيد إلى مقارنة سلاسل نصية هشة. يصبح التحقق من حقل JSON متداخل تعويذة jq؛ ويصبح التحقق من المخطط مستحيلًا أساسًا؛ ولحظة إضافة واجهة برمجة التطبيقات (API) الخاصة بك حقلًا، يحتاج نصف عمليات البحث (greps) الخاصة بك إلى إعادة كتابة. ينتهي بك الأمر بالحفاظ على نسخة ثانية وأسوأ من معرفتك بـ API في Bash.

نهج تشغيل المجموعات أفضل ولكنه يربط CI الخاص بك بطقوس التصدير والمزامنة: تحرير الاختبارات في أداة واحدة، التصدير، الالتزام بـ JSON، على أمل ألا يبتعد عن الواقع. الانحراف حقيقي، وهو مصدر شكاوى "الاختبارات ناجحة ولكن API معطل". لقد كتبنا عن وضع الفشل هذا تحديدًا في "لماذا ليست مجموعات Postman الخاصة بك مصدرًا للحقيقة"، وإذا كنت تشغل مجموعات في CI اليوم، فإن "كيفية تشغيل مجموعات Postman في CI بدون Newman" يغطي مسار الترحيل.

يطوي نموذج Apidog الحلقة. تعيش اختباراتك وتصميم API وبيئاتك وخوادمك الوهمية في مكان واحد. يشغل CLI الإصدار الحي والحالي من تلك الاختبارات؛ لا يوجد شيء للتصدير ولا شيء للانحراف. تقوم بتصحيح خطأ في تأكيد غير مستقر بصريًا في التطبيق، تحفظ، وتشغيل CI التالي يلتقط التغيير. هذا المصدر الوحيد للحقيقة هو السبب الرئيسي لاستخدام أداة تشغيل مخصصة بدلاً من كومة من سكربتات الشل. إذا كنت تقيمه مقابل إعدادك الحالي، فإن "أفضل بدائل Postman لاختبار API" يضع الخيارات جنبًا إلى جنب.

ملاحظة حول Travis CI تحديدًا

كان Travis هو CI الافتراضي مفتوح المصدر لسنوات، ولا تزال العديد من المستودعات القديمة تعمل عليه. إذا كنت تبدأ من جديد في عام 2026، فمن الجدير بالمعرفة أن المجال قد تحول؛ حيث تحمل GitHub Actions و GitLab CI و CircleCI الآن معظم المشاريع الجديدة، وتوضح مقارنتنا لأفضل أدوات CI/CD مكان كل منها. الخبر الجيد هو أن Apidog CLI محايد للمنصات بطبيعته. نفس الأمر apidog run تمامًا الذي يعمل في ملف .travis.yml الخاص بك يعمل في خطوة GitHub Actions، أو ملف .gitlab-ci.yml في GitLab، أو مرحلة Jenkins. إذا انتقلت من Travis في أي وقت، فإن اختبارات API الخاصة بك تنتقل معك دون تغيير؛ تختلف فقط مفاتيح YAML المحيطة. هذه قابلية النقل هي فائدة هادئة ولكنها حقيقية لإبقاء منطق الاختبار خارج بناء الجملة الخاص بـ CI.

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

هل أحتاج إلى تثبيت تطبيق Apidog المكتبي على صندوق CI؟ لا. التطبيق المكتبي مخصص لتصميم الاختبارات وتصحيحها. يحتاج Travis فقط إلى حزمة npm apidog-cli ووقت تشغيل Node 16+، والذي توفره بيئة لغة node_js بالفعل. يقوم CLI بجلب وتشغيل سيناريوهاتك المخزنة في السحابة بدون واجهة رسومية.

أين أجد رمز الوصول ومعرف السيناريو الخاص بي؟ أنشئ رمز الوصول في إعدادات حساب Apidog الخاص بك ضمن "رموز الوصول". معرف السيناريو مرئي في التطبيق المكتبي لكل سيناريو اختبار؛ يوفر خيار "تشغيل في CI/CD" المدمج أيضًا أمرًا كاملاً بمعرف مملوء مسبقًا، وهي أسرع طريقة للحصول على أساس عملي.

كيف أحافظ على الرمز خارج مستودعي؟ اجعله متغير بيئة للمستودع في واجهة مستخدم Travis الويب مع إيقاف تشغيل عرض سجل البناء، ثم أشر إليه كـ $APIDOG_ACCESS_TOKEN في التكوين الخاص بك. بدلاً من ذلك، استخدم travis encrypt لتخزين قيمة مشفرة في ملف .travis.yml. لا تلتزم بالرمز الخام أبدًا.

هل سيفشل البناء بالفعل إذا فشل اختبار؟ نعم. يخرج الأمر apidog run بقيمة غير صفرية عندما يفشل تأكيد، ويعامل Travis أي خروج غير صفري في مرحلة script كبناء فاشل. فقط لا تقمع رمز الخروج باستخدام || true. استخدم --on-error continue إذا كنت تريد الإبلاغ عن كل فشل في تشغيل واحد مع استمرار فشل البناء.

هل يمكنني تشغيل الاختبارات مقابل بيئات متعددة أو مع مجموعات بيانات متعددة؟ نعم. استخدم -e لتبديل البيئات (التجريبية عند الدفع، والإنتاجية في مهمة cron ليلية)، و -d لتغذية ملف بيانات CSV أو JSON للتكرارات المدفوعة بالبيانات، ومصفوفة بناء Travis لتشغيل عدة سيناريوهات في مهام متوازية.

هل يمكنني استخدام هذا إذا لم أكن أستخدم Travis CI؟ نعم. أمر CLI متطابق عبر المنصات. استبدل YAML المحيط لـ GitHub Actions، أو GitLab CI، أو Jenkins وسيبقى سطر apidog run كما هو.

خاتمة

إدخال اختبارات API إلى Travis CI يتركز في أربع خطوات: تخزين رمز الوصول الخاص بك كمتغير مشفر، تثبيت apidog-cli في خطوة التثبيت، تشغيل السيناريو الخاص بك باستخدام apidog run في خطوة السكربت، وترك رمز الخروج غير الصفري يفشل البناء. من هناك، يمكنك إضافة تقارير HTML، وبيئات متعددة، وتكرارات مدفوعة بالبيانات، ومصفوفة متوازية مع نمو مجموعتك.

السبب في القيام بذلك باستخدام أداة تشغيل مخصصة بدلاً من جدار من استدعاءات curl هو مصدر الحقيقة الوحيد. تقوم بالتصميم وتصحيح الأخطاء بصريًا، ثم تشغل الإصدار المباشر لتلك الاختبارات نفسها في كل التزام، دون خطوة تصدير قد تؤدي إلى عدم التزامن. سيتم اكتشاف انحدار /checkout الخاص بك في طلب السحب، وليس في بيئة الإنتاج.

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

زر