DEV Community

Cover image for كيفية تشغيل اختبارات API باستخدام Apidog CLI في CircleCI
Yusuf Khalidd
Yusuf Khalidd

Posted on • Originally published at apidog.com

كيفية تشغيل اختبارات API باستخدام Apidog CLI في CircleCI

لتشغيل اختبارات Apidog CLI API في CircleCI، أضف ملف .circleci/config.yml يستخدم صورة Docker مثل cimg/node، وثبّت apidog-cli عبر npm، ثم شغّل apidog run باستخدام رمز الوصول، ومعرف سيناريو الاختبار، ومعرف البيئة. خزّن هذه القيم كمتغيرات بيئة في CircleCI، وانشر تقارير JUnit وHTML باستخدام store_test_results وstore_artifacts.

جرّب Apidog اليوم

هذه المقالة تركز على التنفيذ: كيف تجعل اختبارات API تعمل تلقائيًا داخل CircleCI مع كل عملية دفع. إذا كنت لا تزال تقارن بين أدوات CI، فراجع مقارنة CircleCI بـ Jenkins. هنا نفترض أنك اخترت CircleCI وتريد تشغيل مجموعة اختبارات واجهاتك تلقائيًا.

ما هو CircleCI وكيف يعمل

CircleCI هي خدمة تكامل وتسليم مستمر قائمة على السحابة. تراقب مستودع Git، وعند كل commit أو push تشغل الخطوات التي عرّفتها في ملف YAML داخل المستودع.

الملف الأساسي هو:

.circleci/config.yml
Enter fullscreen mode Exit fullscreen mode

يقرأه CircleCI مع كل عملية دفع ويحوله إلى pipeline. تنسيق التكوين الحالي هو 2.1، ويتيح لك تعريف الوظائف، والمنفذين، ومسارات العمل.

المفاهيم الثلاثة التي تحتاجها هنا:

  • Jobs: وحدات العمل. كل وظيفة تحتوي على خطوات مثل checkout، تثبيت الحزم، وتشغيل الاختبارات.
  • Executors: بيئة التشغيل. في هذا الدليل سنستخدم Docker executor مع صورة cimg/node.
  • Workflows: تحدد أي jobs تعمل، وبأي ترتيب، وعلى أي فروع.

لاختبار API، ستنشئ job واحدة تثبّت Apidog CLI وتشغّل سيناريوهات الاختبار، ثم workflow يشغّل هذه job عند الدفع إلى المستودع.

لماذا تشغل اختبارات API في CircleCI

تشغيل اختبارات API داخل CI يساعدك على اكتشاف المشاكل قبل النشر:

  • تغيير غير مقصود في schema.
  • حقل response تمت إعادة تسميته.
  • كسر في تدفق المصادقة.
  • endpoint لم يعد يعيد status code المتوقع.

تم تصميم واجهة سطر الأوامر Apidog CLI لهذا النمط من العمل: تبني سيناريو الاختبار في Apidog، ثم تشغله headless داخل CI باستخدام أمر واحد.

إذا كنت تريد سياقًا أوسع حول وضع اختبارات API داخل pipeline، فراجع 12 من أفضل ممارسات CI/CD لاختبار واجهات برمجة التطبيقات.

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

قبل كتابة ملف CircleCI، جهّز القيم التالية من Apidog:

  1. رمز الوصول access token

    أنشئه من إعدادات حساب Apidog. سيستخدمه CLI للمصادقة داخل CircleCI. راجع دليل مصادقة Apidog CLI إذا أردت تفاصيل أكثر حول إنشاء الرمز والتعامل مع أسرار CI.

  2. معرف سيناريو الاختبار test scenario ID

    افتح سيناريو الاختبار في Apidog وانسخ المعرف من عنوان URL أو من إعدادات السيناريو.

  3. معرف البيئة environment ID

    يحدد أي base URL ومتغيرات بيئة سيستخدمها CLI، مثل staging أو production.

ستحتاج أيضًا إلى:

  • حساب CircleCI.
  • مشروع CircleCI متصل بمستودع Git.
  • مستودع يحتوي على مجلد .circleci.

تخزين الأسرار كمتغيرات بيئة

لا تضع رمز الوصول مباشرة داخل config.yml. هذا الملف يتم رفعه إلى Git، وأي secret داخله يمكن أن يتسرب.

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

الخيار 1: متغيرات بيئة المشروع

من واجهة CircleCI:

  1. افتح المشروع.
  2. اذهب إلى Project Settings.
  3. افتح Environment Variables.
  4. أضف المتغيرات التالية: 
APIDOG_ACCESS_TOKEN
APIDOG_TEST_SCENARIO_ID
APIDOG_ENVIRONMENT_ID
Enter fullscreen mode Exit fullscreen mode

الخيار 2: Contexts

استخدم Context إذا كانت عدة مستودعات تشترك في نفس أسرار Apidog.

من CircleCI:

  1. افتح Organization Settings.
  2. اختر Contexts.
  3. أنشئ context باسم مثل apidog-secrets.
  4. أضف نفس المتغيرات الثلاثة.

سنبدأ بمتغيرات المشروع، ثم نعرض مثال context لاحقًا.

ملف config.yml الكامل

أنشئ الملف التالي داخل المستودع:

.circleci/config.yml
Enter fullscreen mode Exit fullscreen mode

ثم أضف التكوين التالي:

version: 2.1

jobs:
  api-tests:
    docker:
      - image: cimg/node:20.11
    steps:
      - checkout

      - run:
          name: Install Apidog CLI
          command: npm install -g apidog-cli

      - run:
          name: Run Apidog API tests
          command: |
            apidog run \
              --access-token $APIDOG_ACCESS_TOKEN \
              -t $APIDOG_TEST_SCENARIO_ID \
              -e $APIDOG_ENVIRONMENT_ID \
              -r cli,junit,html \
              --out-dir ./reports

      - store_test_results:
          path: ./reports

      - store_artifacts:
          path: ./reports

workflows:
  test-api:
    jobs:
      - api-tests
Enter fullscreen mode Exit fullscreen mode

بعد ذلك:

git add .circleci/config.yml
git commit -m "Run Apidog API tests in CircleCI"
git push
Enter fullscreen mode Exit fullscreen mode

سيقرأ CircleCI الملف ويشغّل job الاختبار.

شرح التكوين خطوة بخطوة

1. اختيار المنفذ 

docker:
  - image: cimg/node:20.11
Enter fullscreen mode Exit fullscreen mode

نستخدم صورة cimg/node لأن Apidog CLI يتم تثبيته عبر npm. الصورة تحتوي على Node.js وnpm وأدوات أساسية جاهزة.

يمكنك تغيير الإصدار حسب نسخة Node المعتمدة في فريقك:

docker:
  - image: cimg/node:18.19
Enter fullscreen mode Exit fullscreen mode

أو:

docker:
  - image: cimg/node:20.11
Enter fullscreen mode Exit fullscreen mode

2. سحب الكود 

- checkout
Enter fullscreen mode Exit fullscreen mode

هذه الخطوة تسحب المستودع إلى بيئة job. حتى لو كان الاختبار يعتمد أساسًا على Apidog، يظل checkout مفيدًا إذا كنت تستخدم ملفات بيانات مثل CSV أو JSON من المستودع.

3. تثبيت Apidog CLI 

- run:
    name: Install Apidog CLI
    command: npm install -g apidog-cli
Enter fullscreen mode Exit fullscreen mode

هذا يثبّت CLI عالميًا داخل حاوية CircleCI. بعد هذه الخطوة يصبح الأمر apidog متاحًا في الخطوات التالية.

4. تشغيل اختبارات API 

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t $APIDOG_TEST_SCENARIO_ID \
  -e $APIDOG_ENVIRONMENT_ID \
  -r cli,junit,html \
  --out-dir ./reports
Enter fullscreen mode Exit fullscreen mode

معنى كل خيار:

  • --access-token

    يستخدم رمز الوصول للمصادقة مع Apidog.

  • -t

    يحدد سيناريو الاختبار المطلوب تشغيله.

  • -e

    يحدد البيئة التي سيعمل عليها السيناريو.

  • -r cli,junit,html

    يطلب ثلاثة أنواع من التقارير:

    • cli: عرض النتيجة داخل سجل CircleCI.
    • junit: ملف XML يمكن لـ CircleCI قراءته كاختبارات.
    • html: تقرير HTML قابل للتصفح.

  • --out-dir ./reports

    يحدد مكان حفظ التقارير.

نشر تقارير الاختبار في CircleCI

نشر نتائج JUnit 

- store_test_results:
    path: ./reports
Enter fullscreen mode Exit fullscreen mode

هذه الخطوة تجعل CircleCI يقرأ ملفات JUnit XML من مجلد ./reports ويعرضها في تبويب الاختبارات داخل واجهة البناء.

هذا مفيد لأنك سترى:

  • أسماء الاختبارات الفاشلة.
  • مدة التنفيذ.
  • عدد الاختبارات الناجحة والفاشلة.
  • تفاصيل الفشل بدل البحث داخل logs طويلة.

نشر تقرير HTML كـ artifact 

- store_artifacts:
    path: ./reports
Enter fullscreen mode Exit fullscreen mode

هذه الخطوة ترفع مجلد التقارير كـ artifacts. بعد انتهاء البناء يمكنك فتح تبويب Artifacts وتنزيل تقرير HTML أو عرضه.

للمزيد حول أنواع التقارير، راجع دليل تقارير اختبار Apidog CLI.

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

إذا كنت لا تريد تشغيل اختبارات API الكاملة على كل feature branch، أضف filters إلى workflow:

workflows:
  test-api:
    jobs:
      - api-tests:
          filters:
            branches:
              only:
                - main
                - develop
Enter fullscreen mode Exit fullscreen mode

الآن ستعمل job فقط عند الدفع إلى:

  • main
  • develop

وتُتخطى على بقية الفروع.

استخدام Context بدل متغيرات المشروع

إذا كان لديك أكثر من مستودع يستخدم نفس Apidog token، استخدم CircleCI Context.

مثال:

workflows:
  test-api:
    jobs:
      - api-tests:
          context:
            - apidog-secrets
Enter fullscreen mode Exit fullscreen mode

في هذا المثال، تقرأ job المتغيرات التالية من context باسم apidog-secrets:

APIDOG_ACCESS_TOKEN
APIDOG_TEST_SCENARIO_ID
APIDOG_ENVIRONMENT_ID
Enter fullscreen mode Exit fullscreen mode

ميزة هذا الأسلوب أنك تغيّر الرمز في مكان واحد، وتستفيد كل المشاريع من القيمة الجديدة.

تشغيل اختبارات معتمدة على البيانات

إذا كان سيناريو الاختبار يحتاج إلى بيانات متعددة، يمكنك استخدام ملف CSV أو JSON مع الخيار -d.

مثال:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t $APIDOG_TEST_SCENARIO_ID \
  -e $APIDOG_ENVIRONMENT_ID \
  -d ./data/users.csv \
  -r cli,junit \
  --out-dir ./reports
Enter fullscreen mode Exit fullscreen mode

هنا سيستخدم Apidog CLI ملف:

./data/users.csv
Enter fullscreen mode Exit fullscreen mode

ويشغل السيناريو بناءً على صفوف البيانات.

يمكن أن يكون الملف داخل المستودع مثلًا:

data/users.csv
Enter fullscreen mode Exit fullscreen mode

مثال مبسط:

email,password
user1@example.com,secret123
user2@example.com,secret456
Enter fullscreen mode Exit fullscreen mode

لمزيد من التفاصيل حول تنظيم ملفات البيانات، راجع دليل الاختبار المعتمد على البيانات.

التحكم في سلوك الفشل

يمكنك تحديد ماذا يحدث عند فشل خطوة داخل السيناريو باستخدام:

--on-error
Enter fullscreen mode Exit fullscreen mode

القيم المدعومة:

  • continue: تابع التنفيذ بعد الفشل.
  • end: أوقف التشغيل عند الفشل.
  • ignore: تجاهل الفشل.

مثال:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t $APIDOG_TEST_SCENARIO_ID \
  -e $APIDOG_ENVIRONMENT_ID \
  --on-error end \
  -r cli,junit,html \
  --out-dir ./reports
Enter fullscreen mode Exit fullscreen mode

استخدم end عندما تريد fail fast داخل CI، خاصة في الفروع الحرجة مثل main.

استهداف فرع محدد داخل Apidog

إذا كان مشروعك يستخدم فروع Apidog، يمكنك تحديد المشروع والفرع:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  --project <id> \
  --branch <name> \
  -t $APIDOG_TEST_SCENARIO_ID \
  -e $APIDOG_ENVIRONMENT_ID \
  -r cli,junit,html \
  --out-dir ./reports
Enter fullscreen mode Exit fullscreen mode

استبدل:

<id>
<name>
Enter fullscreen mode Exit fullscreen mode

بمعرف المشروع واسم الفرع المطلوب.

رفع ملخص التقرير إلى Apidog

إذا أردت رفع ملخص التقرير إلى سحابة Apidog، أضف:

--upload-report
Enter fullscreen mode Exit fullscreen mode

مثال:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t $APIDOG_TEST_SCENARIO_ID \
  -e $APIDOG_ENVIRONMENT_ID \
  -r cli,junit,html \
  --out-dir ./reports \
  --upload-report
Enter fullscreen mode Exit fullscreen mode

كيف يتناسب هذا مع سير عمل Apidog

الفكرة الأساسية أن Apidog يمتلك تعريف الاختبار، وCircleCI يمتلك وقت ومكان التشغيل.

داخل Apidog:

  1. تبني سيناريو الاختبار.
  2. تضيف assertions على status codes وresponse body.
  3. تحدد البيئة والمتغيرات.
  4. تحفظ السيناريو.

داخل CircleCI:

  1. تثبّت Apidog CLI.
  2. تشغّل نفس السيناريو باستخدام apidog run.
  3. تنشر تقارير JUnit وHTML.

يمكنك أيضًا إنشاء أو تشغيل سيناريو اختبار من سطر الأوامر حسب طريقة عمل فريقك.

هذا التقسيم يقلل تكرار كود الاختبار. عندما يضيف أحد أعضاء الفريق assertion جديدًا داخل Apidog، سيبدأ CircleCI بتشغيله في البناء التالي بدون تعديل YAML.

إذا أردت مقارنة CircleCI بأدوات CI أخرى مناسبة لفرق API، راجع أدوات التكامل المستمر لفرق واجهات برمجة التطبيقات.

هل تريد تشغيل API suite مع كل push؟ حمّل Apidog، أنشئ سيناريو اختبار، ثم أضف ملف config.yml أعلاه إلى مستودعك.

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

ما هو CircleCI؟

CircleCI هي منصة تكامل وتسليم مستمر قائمة على السحابة. تتصل بمستودع Git، وتقرأ ملف .circleci/config.yml، ثم تشغل خطوات البناء والاختبار والنشر تلقائيًا عند دفع الكود.

ما هو استخدام CircleCI؟

تستخدم الفرق CircleCI لأتمتة الاختبار والنشر. من الاستخدامات الشائعة:

  • تشغيل unit tests.
  • تشغيل integration tests.
  • اختبار عقود API.
  • بناء صور Docker.
  • نشر الإصدارات إلى staging أو production.

في هذا الدليل، استخدمناه لتشغيل اختبارات Apidog CLI API مع كل push.

هل CircleCI مجاني؟

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

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

لا. CircleCI منتج تجاري مستضاف، وليس مفتوح المصدر. يمكنك تكوينه بملف YAML وتشغيله على بنية CircleCI التحتية أو عبر مشغّل مستضاف ذاتيًا. إذا كنت تحتاج إلى خادم CI مفتوح المصدر بالكامل، فغالبًا ستقارن مع Jenkins.

كيف يعمل CircleCI؟

عند دفع commit، يكتشف CircleCI التغيير، يقرأ .circleci/config.yml، يشغّل المنفذ المحدد مثل حاوية Docker cimg/node، ثم ينفذ خطوات كل job بالترتيب. بعد الانتهاء، يعرض النتائج داخل CircleCI ويرسل الحالة إلى موفر Git.

للحصول على الصورة الأوسع حول CI/CD، راجع دليل ما هو CI/CD.

Top comments (0)