DEV Community

Cover image for كيفية تشغيل اختبارات API بـ Apidog CLI في Drone CI
Yusuf Khalidd
Yusuf Khalidd

Posted on • Originally published at apidog.com

كيفية تشغيل اختبارات API بـ Apidog CLI في Drone CI

يمكنك تشغيل اختبارات Apidog CLI API داخل Drone CI بإضافة خطوة Docker تستخدم صورة Node، ثم تثبيت apidog-cli وتشغيل apidog run ضد بيئة محددة. خزّن رمز وصول Apidog كسرّ في Drone، ومرّره إلى الخطوة باستخدام from_secret. في هذا الدليل ستجهّز ملف .drone.yml قابلًا للنسخ، وتضبط الأسرار، وشروط التشغيل حسب الفرع، وخيارات عرض التقارير في Drone.

جرّب Apidog اليوم

ما هو Drone CI وكيف يعمل؟

Drone هو نظام CI/CD مفتوح المصدر ومبني على الحاويات، وهو الآن جزء من Harness. إذا كنت تريد مراجعة المفهوم العام للتكامل المستمر والتسليم المستمر، اقرأ ما هو CI/CD.

الفكرة الأساسية في Drone: كل خطوة في المسار تعمل داخل حاوية Docker مستقلة. بدل الاعتماد على وكيل بناء يحتوي أدوات مثبتة مسبقًا، تختار صورة Docker لكل خطوة، ثم تشغّل أوامرك داخلها. هذا يجعل المسارات قابلة للتكرار وأسهل في التصحيح.

يتم تعريف المسار في ملف .drone.yml داخل جذر المستودع:

kind: pipeline
type: docker
name: api-tests

steps:
  - name: greeting
    image: alpine
    commands:
      - echo hello
      - echo world
Enter fullscreen mode Exit fullscreen mode

يشغّل Drone أوامر commands كسكريبت shell مع set -e وset -x، لذلك يفشل البناء عند أول أمر يرجع رمز خروج غير صفري، ويطبع الأوامر قبل تنفيذها. دليل العمل الافتراضي هو جذر المستودع.

لماذا تشغّل اختبارات API داخل خطوة حاوية؟

اختبارات API تمنع تغييرات غير مقصودة في العقود: رمز حالة مختلف، حقل مفقود، أو شكل استجابة تغيّر بدون تنبيه. تشغيلها مع كل push أو pull_request يساعدك على اكتشاف الانحدارات قبل النشر.

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

أمر Apidog CLI المستخدم في Drone

ثبّت CLI عبر npm، ثم شغّل سيناريو الاختبار باستخدام معرف السيناريو ومعرف البيئة:

npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli
Enter fullscreen mode Exit fullscreen mode

شرح الأعلام الأساسية:

  • --access-token: يمرّر رمز وصول Apidog. خزّنه دائمًا كسرّ ولا تضعه في المستودع.
  • -t: معرف سيناريو الاختبار.
  • -e: معرف البيئة، ويحدد المتغيرات مثل base URL والقيم البيئية.
  • -r: نوع التقرير. القيم المدعومة تشمل 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

ضع الملف التالي في جذر المستودع:

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
Enter fullscreen mode Exit fullscreen mode

عدّل القيم التالية:

  • استبدل 1234567 بمعرف سيناريو الاختبار في Apidog.
  • استبدل 89012 بمعرف البيئة.
  • تأكد من إنشاء سر باسم apidog_access_token في Drone.

باستخدام reporter من نوع cli، ستظهر تفاصيل النجاح والفشل مباشرة داخل سجل بناء Drone.

تخزين الأسرار في Drone CI

لا تضع رمز Apidog داخل .drone.yml. استخدم أسرار Drone ثم اربطها بمتغير بيئة داخل الخطوة:

environment:
  APIDOG_ACCESS_TOKEN:
    from_secret: apidog_access_token
Enter fullscreen mode Exit fullscreen mode

إنشاء السر من واجهة Drone

  1. افتح المستودع في Drone.
  2. انتقل إلى Settings.
  3. افتح Secrets.
  4. أضف سرًا باسم: 
apidog_access_token
Enter fullscreen mode Exit fullscreen mode
  1. ضع رمز وصول Apidog كقيمة.

إنشاء السر باستخدام Drone CLI 

drone secret add \
  --repository your-org/your-repo \
  --name apidog_access_token \
  --data your-apidog-token
Enter fullscreen mode Exit fullscreen mode

قد تختلف أعلام Drone CLI حسب الإصدار، لذلك راجع وثائق إصدارك عند الحاجة.

يدعم Drone أيضًا الأسرار المشفرة داخل المستودع عبر drone encrypt وتعريف YAML من نوع kind: secret، لكن أسرار المستودع عبر الواجهة أو CLI هي الخيار الأبسط لمعظم الفرق.

لمزيد من التفاصيل حول المصادقة في CLI، راجع مصادقة Apidog CLI.

تحديد شروط التشغيل حسب الفرع والحدث

في Drone لديك مستويان للتحكم في وقت التشغيل:

  • trigger: يحدد هل يعمل المسار بالكامل أم لا.
  • when: يحدد هل تعمل خطوة معينة أم لا.

تشغيل المسار فقط على main 

trigger:
  branch:
    - main
  event:
    - push
    - pull_request
Enter fullscreen mode Exit fullscreen mode

في هذا المثال يعمل المسار فقط عند push أو pull_request على الفرع main.

تشغيل خطوة الاختبار فقط في حالات محددة 

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
    when:
      branch:
        - main
      event:
        - push
Enter fullscreen mode Exit fullscreen mode

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

يدعم Drone أحداثًا مثل:

  • push
  • pull_request
  • tag
  • promote
  • rollback
  • cron
  • custom

كما يدعم أنماط glob ومفاتيح التضمين والاستبعاد.

عرض تقارير الاختبار بدون متجر تحف مدمج

Drone لا يوفر استضافة تحف مدمجة. أمامك خياران عمليان.

الخيار الأول: عرض النتائج في سجل البناء

استخدم reporter من نوع cli:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli
Enter fullscreen mode Exit fullscreen mode

هذا يكفي في معظم الحالات، لأن نتائج الاختبار والتأكيدات الفاشلة تظهر مباشرة في سجل Drone.

الخيار الثاني: إنشاء تقرير HTML ورفعه إلى S3

استخدم html مع --out-dir، ثم أضف خطوة رفع باستخدام plugins/s3:

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
Enter fullscreen mode Exit fullscreen mode

ما يحدث هنا:

  • reports/**/* يحدد الملفات التي سيتم رفعها.
  • target يحدد بادئة المسار داخل التخزين.
  • بيانات اعتماد AWS تُقرأ من أسرار Drone بنفس طريقة رمز Apidog.

للتعمق في محتوى التقارير وكيفية قراءتها، راجع تقارير اختبار Apidog 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
Enter fullscreen mode Exit fullscreen mode

مثال بسيط لملف data.csv:

userId,expectedStatus
1001,200
1002,200
9999,404
Enter fullscreen mode Exit fullscreen mode

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

للنمط الكامل، راجع اختبار Apidog CLI المدفوع بالبيانات.

مقارنة النمط مع أدوات CI الأخرى

نمط التشغيل نفسه يعمل تقريبًا في أي نظام CI:

  1. استخدم صورة تحتوي Node.
  2. ثبّت apidog-cli.
  3. مرّر رمز الوصول من secrets.
  4. شغّل apidog run.

الاختلاف يكون فقط في صياغة YAML الخاصة بالأداة. إذا كنت تستخدم أدوات أخرى بجانب Drone، راجع أدلة GitHub Actions وAzure Pipelines.

ملاحظة مهمة: Apidog CLI مخصص لاختبارات وظيفية واختبارات عقود API، وليس لاختبار تحميل واسع النطاق. إذا كنت تحتاج آلاف المستخدمين الافتراضيين المتزامنين، استخدم أداة متخصصة لاختبار التحميل.

بناء الاختبارات بصريًا وتشغيلها من CI

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

  1. صمّم نقاط النهاية داخل Apidog.
  2. أنشئ سيناريوهات اختبار.
  3. أضف التأكيدات على status code وحقول الاستجابة.
  4. اربط السيناريو ببيئة تحتوي base URL والمتغيرات.
  5. احصل على معرف السيناريو ومعرف البيئة.
  6. ضع أمر apidog run داخل .drone.yml.

عند تحديث اختبار داخل تطبيق Apidog، سيستخدم تشغيل Drone التالي النسخة المحدثة مباشرة. لا تحتاج إلى الحفاظ على نسخة ثانية من الاختبارات داخل المستودع.

قم بتنزيل Apidog مجانًا لبناء أول سيناريو اختبار، ثم أضف ملف .drone.yml أعلاه لتشغيله مع كل عملية دفع.

الأسئلة المتكررة

ما هو Drone CI؟

Drone هو نظام CI/CD مفتوح المصدر ومبني على الحاويات. يعرّف المسارات داخل ملف .drone.yml، ويشغّل كل خطوة داخل حاوية Docker مستقلة، مما يجعل البناء قابلًا للتكرار وأسهل في العزل.

هل Drone CI مجاني؟

مشروع Drone الأساسي مفتوح المصدر ومجاني للاستضافة الذاتية. بعد استحواذ Harness، أصبح Drone هو Harness CI Community Edition، مع توفر مستويات مؤسسية مدفوعة.

هل Drone CI مفتوح المصدر؟

نعم. Drone من أدوات CI المبنية على الحاويات، ولا يزال بإمكانك استضافته ذاتيًا واستخدامه كمشروع مفتوح المصدر.

كيف تستخدم Drone CI؟

تضع ملف .drone.yml في المستودع. عند حدوث push أو pull_request، يقرأ Drone الملف ويشغّل الخطوات المحددة داخل حاويات. يمكن أن تشمل الخطوات بناء التطبيق، تشغيل اختبارات الوحدة، تشغيل اختبارات API، أو رفع التقارير إلى تخزين خارجي.

كيف تخزّن الأسرار في Drone CI؟

أضف السر من واجهة Drone أو باستخدام drone secret add، ثم أشر إليه داخل environment أو settings باستخدام from_secret. بهذه الطريقة لا يظهر الرمز داخل ملف YAML.

environment:
  APIDOG_ACCESS_TOKEN:
    from_secret: apidog_access_token
Enter fullscreen mode Exit fullscreen mode

هل يمكن تشغيل اختبارات Apidog في CI بدون كتابة سكريبتات اختبار؟

نعم. تبني سيناريوهات الاختبار بصريًا داخل Apidog، ثم تشغّلها في Drone بأمر واحد:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli
Enter fullscreen mode Exit fullscreen mode

تحتاج فقط إلى صورة Node، وتثبيت apidog-cli، وتمرير رمز الوصول من أسرار Drone.

Top comments (0)