يمكنك تشغيل اختبارات Apidog CLI API في Drone CI عن طريق إضافة خطوة Docker في مسار العمل تستخدم صورة Node، وتقوم بتثبيت apidog-cli، وتشغل apidog run مقابل بيئة معينة. يعيش رمز الوصول الخاص بـ Apidog الخاص بك في سر Drone ويتم حقنه من خلال from_secret. يرشدك هذا الدليل خلال ملف .drone.yml جاهز للنسخ واللصق، والتعامل مع الأسرار، وتحديد شروط التشغيل بناءً على الفروع، وكيفية عرض تقرير الاختبار نظرًا لعدم وجود متجر مدمج للتحف في Drone.
ما هو Drone CI وكيف يعمل؟
Drone هو نظام CI/CD مفتوح المصدر ومبني على الحاويات، وهو الآن جزء من Harness. يشير CI/CD إلى التكامل المستمر والتسليم المستمر، وهي ممارسة بناء واختبار الكود تلقائيًا مع كل تغيير. إذا كنت ترغب في مراجعة المفهوم نفسه، فراجع ما هو CI/CD.
السمة المميزة لـ Drone بسيطة: كل خطوة في مسار العمل تعمل داخل حاوية Docker الخاصة بها. لا يوجد وكيل بناء مشترك مع مجموعة من الأدوات المثبتة مسبقًا. يمكنك اختيار صورة لكل خطوة، ويقوم Drone بتشغيل أوامرك بداخلها. هذا يجعل عمليات البناء قابلة للتكرار وسهلة الفهم.
يمكنك تعريف مسار عمل في ملف .drone.yml في جذر مستودعك. يحتوي مسار عمل Docker على ثلاثة مفاتيح رئيسية علوية: kind و type و name. يتم العمل ضمن steps، حيث تعلن كل خطوة عن name و image وقائمة commands.
kind: pipeline
type: docker
name: api-tests
steps:
- name: greeting
image: alpine
commands:
- echo hello
- echo world
يقوم Drone بتشغيل commands كسكريبت شل باستخدام set -e و set -x، لذا يفشل البناء بسرعة عند أول رمز خروج غير صفري ويقوم بعرض كل أمر قبل تشغيله. تتجاوز الأوامر نقطة دخول الحاوية، ويكون دليل العمل هو جذر مستودعك.
لماذا تشغل اختبارات API في خطوة حاوية؟
تحمي اختبارات API من انحراف العقود. قد يؤدي تغيير الواجهة الخلفية الذي يغير شكل الاستجابة أو رمز الحالة بصمت إلى تعطيل كل عميل في المسار. يؤدي تشغيل هذه الاختبارات في كل عملية دفع إلى اكتشاف التراجع قبل نشره.
يتناسب Apidog مع هذا النموذج جيدًا. يمكنك بناء اختباراتك وصيانتها بصريًا في تطبيق Apidog، ثم تشغيل نفس سيناريوهات الاختبار بالضبط من سطر الأوامر باستخدام Apidog CLI. لا يوجد إعادة كتابة للسكريبت، ولا يوجد نظام اختبار منفصل. للحصول على إرشادات أوسع حول ربط اختبارات API بمسارات العمل، اقرأ أفضل ممارسات CI/CD لاختبار API.
Apidog هي منصة API شاملة للتصميم والتصحيح والاختبار والمحاكاة والتوثيق. CLI هو الجزء الذي يحول سيناريوهات الاختبار المحفوظة إلى أمر واحد قابل للتكرار، وهذا بالضبط ما تحتاجه خطوة Drone.
أمر Apidog CLI الذي ستشغله
قم بتثبيت CLI باستخدام npm، ثم قم بتشغيل سيناريو اختبار. في CI، تقوم بتوجيه التشغيل إلى سيناريو محفوظ باستخدام الأعلام، لذلك لا يوجد ملف مجموعة محلي لإدارته.
npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli
إليك ما يفعله كل علم:
--access-tokenيمرر رمز الوصول الخاص بـ Apidog الخاص بك. لا يوجد شكل مختصر.-tهو معرف سيناريو الاختبار الذي تريد تشغيله.-eهو معرف البيئة، وهو مطلوب. يحدد هذا أي عنوان URL أساسي ومتغيرات يستخدمها التشغيل.-rيسرد المُبلغين (reporters). القيم الصالحة هيcli،html،json، وjunit.
يمكنك إضافة المزيد من الأعلام حسب الحاجة:
-nأو--iteration-countيكرر التشغيل عددًا محددًا من المرات.-dأو--iteration-dataيأخذ مسار ملف CSV أو JSON، أو معرف مجموعة بيانات مخزنة رقمية، للتشغيل المدفوع بالبيانات.--out-dirيحدد دليل إخراج التقرير.--upload-reportيدفع نظرة عامة على التقرير إلى سحابة Apidog، حيث يمكنك عرضها في التطبيق. يمكنك استخدامها كعلم منفصل.--on-errorيتحكم في سلوك الفشل معcontinue،end، أوignore.--project <id>و--branch <name>يستهدفان فرع مشروع محدد.
للاطلاع الكامل على الأمر وخياراته، راجع الدليل الكامل لـ Apidog CLI والدليل التفصيلي حول اختبار REST API من سطر الأوامر.
ملف .drone.yml كامل لاختبارات Apidog
هنا مسار عمل يعمل. يستخدم صورة Node، ويثبت CLI، ويشغل سيناريو الخاص بك. يأتي الرمز من سر Drone بدلاً من أن يكون مشفرًا بشكل ثابت.
kind: pipeline
type: docker
name: apidog-api-tests
steps:
- name: run-api-tests
image: node:20-alpine
environment:
APIDOG_ACCESS_TOKEN:
from_secret: apidog_access_token
commands:
- npm install -g apidog-cli
- apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli
trigger:
branch:
- main
event:
- push
- pull_request
استبدل 1234567 بمعرف سيناريو الاختبار الخاص بك و 89012 بمعرف البيئة الخاص بك. كلاهما مرئي في تطبيق Apidog. نظرًا لأن الخطوة تستخدم المُبلغ cli، يتم طباعة تفاصيل النجاح/الفشل الكاملة مباشرة في سجل بناء Drone، حيث يمكن لأي شخص يراجع البناء قراءتها.
تخزين الأسرار في Drone CI
لا تقم أبدًا بتضمين رمز API في مستودعك. يحافظ Drone على الأسرار خارج YAML ويحقنها في وقت التشغيل.
يمكنك الإشارة إلى سر داخل كتلة environment في خطوة (أو كتلة settings في مكون إضافي) باستخدام from_secret. القيمة التي تكتبها هي اسم السر، وليس الرمز نفسه.
environment:
APIDOG_ACCESS_TOKEN:
from_secret: apidog_access_token
هناك طريقتان شائعتان لإنشاء السر. الأولى هي واجهة مستخدم Drone: افتح مستودعك، وانتقل إلى الإعدادات (Settings)، ثم الأسرار (Secrets)، وأضف سرًا باسم apidog_access_token مع رمزك كقيمة. الثانية هي أداة سطر أوامر Drone.
drone secret add \
--repository your-org/your-repo \
--name apidog_access_token \
--data your-apidog-token
تأكد من أسماء الأعلام الدقيقة مقابل وثائق Drone CLI لإصدارك، حيث يمكن أن تتغير أعلام CLI بين الإصدارات. يدعم Drone أيضًا متغير سر مشفر داخل المستودع حيث ينتج drone encrypt كائنًا ثنائيًا مشفرًا تقوم بتضمينه كوثيقة YAML منفصلة kind: secret. بالنسبة لمعظم الفرق، تعد أسرار المستودعات التي تضاف عبر واجهة المستخدم أو drone secret add أبسط ونقطة البداية الموصى بها.
يعد الاحتفاظ بالرمز في سر هو نفس الانضباط الذي ستطبقه في أي مكان آخر. لمزيد من المعلومات حول كيفية تعامل CLI مع بيانات الاعتماد، راجع الدليل الخاص بـ مصادقة Apidog CLI.
تحديد شروط التشغيل بناءً على الفرع والحدث
يمنحك Drone وسيلتين للتحكم في وقت تشغيل العمل: trigger على مستوى مسار العمل و when على مستوى الخطوة.
تقرر كتلة trigger ما إذا كان مسار العمل بأكمله سيتم تشغيله. يجب أن تكون جميع الشروط صحيحة، لذا فإن المثال أدناه يعمل فقط على عمليات الدفع وطلبات السحب التي تستهدف main.
trigger:
branch:
- main
event:
- push
- pull_request
تقع كتلة when داخل خطوة واحدة وتتحكم في تلك الخطوة فقط. هذا مفيد عندما تريد تشغيل معظم مسار العمل في كل مكان ولكنك تحتفظ بتمرير اختبار أثقل لفرع واحد.
steps:
- name: run-api-tests
image: node:20-alpine
commands:
- npm install -g apidog-cli
- apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli
when:
branch:
- main
event:
- push
تدعم كلتا الكتلتين أنماط glob ومفاتيح فرعية للتضمين/الاستبعاد. تتضمن أنواع الأحداث المدعومة push، pull_request، tag، promote، rollback، cron، و custom.
عرض تقارير الاختبار بدون متجر تحف
لا يحتوي Drone على استضافة تحف أصلية. هذا يغير كيفية التعامل مع التقارير، ولكن لديك خيارين نظيفين.
الأول هو الأبسط: استخدم المُبلغ cli بحيث تظهر النتائج في سجل البناء. بالنسبة لمعظم الفرق، هذا يكفي، حيث يظهر السجل بالفعل أي التأكيدات نجحت وأيها فشل.
الخيار الثاني هو إنشاء تقرير HTML وتحميله إلى مكان دائم. ينشر Drone مكونًا إضافيًا رسميًا لـ S3، plugins/s3، يقوم بتحميل الملفات إلى S3 أو أي متجر متوافق مع S3. قم بإنشاء التقرير باستخدام المُبلغ html و --out-dir، ثم أضف خطوة تحميل.
steps:
- name: run-api-tests
image: node:20-alpine
environment:
APIDOG_ACCESS_TOKEN:
from_secret: apidog_access_token
commands:
- npm install -g apidog-cli
- apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli,html --out-dir reports
- name: upload-report
image: plugins/s3
settings:
bucket: my-bucket
region: us-east-1
source: reports/**/*
target: /apidog-reports
access_key:
from_secret: aws_access_key
secret_key:
from_secret: aws_secret_key
يقرأ المكون الإضافي بيانات اعتماد AWS الخاصة به من الأسرار من خلال from_secret، وهي نفس الآلية التي استخدمتها لرمز Apidog. المفتاح source هو نمط glob للملفات التي سيتم تحميلها، و target هو بادئة الوجهة في التخزين.
إذا كنت ترغب في إلقاء نظرة أعمق على ما يحتويه التقرير وكيفية قراءته، فراجع تفاصيل تقارير اختبار Apidog CLI.
إضافة عمليات تشغيل مدفوعة بالبيانات
في بعض الأحيان يحتاج سيناريو واحد إلى التشغيل مقابل العديد من صفوف الإدخال: عشرة معرفات مستخدم، اثني عشر حمولة، مجموعة من حالات الحافة. يتعامل CLI مع هذا باستخدام -d، والذي يقبل مسار ملف CSV أو JSON أو معرف مجموعة بيانات مخزنة.
commands:
- npm install -g apidog-cli
- apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -d ./data.csv -r cli
يصبح كل صف في data.csv تكرارًا واحدًا، مع ربط قيم الأعمدة بمتغيرات السيناريو الخاصة بك. يغطي النمط الكامل في اختبار Apidog CLI المدفوع بالبيانات.
كيف يقارن هذا بأدوات CI الأخرى
نمط Drone، تثبيت CLI في حاوية نظيفة وتشغيل أمر واحد، ينطبق على جميع أنظمة CI تقريبًا. يختلف بناء الجملة المحيط، لكن خطوة Apidog هي نفسها.
إذا كنت تقوم أيضًا بتشغيل مسارات عمل في مكان آخر، فإن Apidog لديه أدلة تفصيلية مطابقة لـ GitHub Actions و Azure Pipelines. الفكرة المشتركة هي أن اختباراتك موجودة في Apidog وأداة CI تقوم ببساطة بتشغيلها.
ملاحظة صادقة حول النطاق: يقوم Apidog CLI بإجراء اختبارات وظيفية وعقود، وليس اختبار تحميل واسع النطاق. إذا كنت بحاجة إلى آلاف المستخدمين الافتراضيين المتزامنين لإجهاد نقطة نهاية، فاستخدم أداة مخصصة لاختبار التحميل. للتحقق من أن واجهة برمجة التطبيقات الخاصة بك تعمل بشكل صحيح في كل عملية تثبيت، فإن CLI في خطوة Drone يؤدي المهمة بشكل جيد.
بناء الاختبارات بصريًا، وتشغيلها بأمر واحد
سير العمل الذي يجعل هذا ممتعًا هو الفصل بين التأليف والتنفيذ. يمكنك تصميم نقاط النهاية وتجميع سيناريوهات الاختبار بصريًا في Apidog، وربط الطلبات، والتأكيد على رموز الحالة وحقول الاستجابة، وإعادة استخدام متغيرات البيئة. لا يلزم وجود كود لبناء المجموعة.
ثم تقوم CI بتشغيل نفس المجموعة بأمر CLI واحد داخل خطوة حاوية. عندما يقوم زميل في الفريق بتحديث اختبار في تطبيق Apidog، يلتقطه بناء Drone التالي تلقائيًا. لا توجد نسخة ثانية من الاختبارات للحفاظ على مزامنتها.
قم بتنزيل Apidog مجانًا لبناء أول سيناريو اختبار لك، ثم ضع ملف .drone.yml أعلاه في مستودعك لتشغيله في كل عملية دفع.
الأسئلة المتكررة
ما هو Drone CI؟
Drone هو نظام CI/CD مفتوح المصدر ومبني على الحاويات، وهو الآن جزء من Harness. يقوم بتشغيل كل خطوة في مسار العمل داخل حاوية Docker الخاصة بها، مع تعريف مسارات العمل في ملف .drone.yml. يحافظ هذا على عمليات البناء قابلة للتكرار ويتجنب انتشار الأدوات المثبتة مسبقًا في وكلاء البناء التقليديين.
هل Drone CI مجاني؟
مشروع Drone الأساسي مفتوح المصدر ومجاني للاستضافة الذاتية. بعد استحواذ Harness، أصبح Drone هو Harness CI Community Edition، مع توفر مستويات مؤسسية مدفوعة. بالنسبة لمعظم الفرق، يغطي الإصدار مفتوح المصدر المستضاف ذاتيًا تشغيل اختبارات API مثل تلك الموجودة في هذا الدليل.
هل Drone CI مفتوح المصدر؟
نعم. Drone هو أحد أدوات CI الأصلية المبنية على الحاويات ويظل مفتوح المصدر. عندما استحوذت عليه Harness في عام 2020، التزمت الشركة بالحفاظ على المشروع مفتوح المصدر، ولا يزال بإمكانك استضافته ذاتيًا.
كيف يتم استخدام Drone CI؟
تستخدم الفرق Drone لبناء واختبار وتسليم الكود تلقائيًا في كل عملية دفع أو طلب سحب. تقوم بتثبيت ملف .drone.yml في مستودعك، ويقرأه Drone، ويشغل كل خطوة في حاوية. تتضمن الخطوات الشائعة تجميع الكود، وتشغيل اختبارات الوحدات، وتشغيل اختبارات API، وتحميل التحف إلى تخزين خارجي.
كيف تقوم بتخزين الأسرار في Drone CI؟
يمكنك إضافة الأسرار من خلال شاشة إعدادات المستودع ثم الأسرار في واجهة مستخدم Drone، أو باستخدام drone secret add من CLI. ثم تشير إلى كل سر داخل كتلة environment في خطوة أو كتلة settings في مكون إضافي باستخدام from_secret، حيث تكون القيمة هي اسم السر. لا يظهر الرمز نفسه أبدًا في ملف YAML الخاص بك.
هل يمكنني تشغيل اختبارات Apidog في CI بدون كتابة سكريبتات؟
نعم. يمكنك بناء سيناريوهات الاختبار بصريًا في تطبيق Apidog، ثم تشغيلها في CI بأمر apidog run واحد. تحتاج خطوة Drone فقط إلى صورة Node، وسطر npm install -g apidog-cli، وأمر التشغيل الموجه إلى معرفات السيناريو والبيئة الخاصة بك.