كيفية تشغيل اختبارات 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. يشرح هذا الدليل كل جزء لتتمكن من النسخ واللصق والنشر.

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

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

CircleCI هي خدمة تكامل وتسليم مستمر قائمة على السحابة. تراقب مستودع Git الخاص بك، وعندما تدفع التزامًا (commit)، فإنها تشغل خطوات البناء والاختبار والنشر التي حددتها. تصف هذه الخطوات في ملف YAML واحد، بحيث يعيش مسار العمل الخاص بك في التحكم في الإصدار جنبًا إلى جنب مع التعليمات البرمجية الخاصة بك.

يبدأ كل شيء بملف .circleci/config.yml في جذر مستودعك. يقرأ CircleCI هذا الملف مع كل عملية دفع ويحوله إلى مسار عمل (pipeline). تنسيق التكوين الحالي هو الإصدار 2.1، والذي يضيف كتل بناء قابلة لإعادة الاستخدام مثل الأوربس والأوامر والمعاملات فوق محرك 2.0 الأساسي.

تكوين CircleCI لديه ثلاثة مفاهيم أساسية:

• **الوظائف (Jobs)** هي وحدات عمل. تشغل كل وظيفة سلسلة من **الخطوات (steps)**، مثل سحب الكود (checking out code)، أو تثبيت التبعيات (installing dependencies)، أو تشغيل أمر اختبار (running a test command).
• **المنفذون (Executors)** يحددون مكان تشغيل الوظيفة. يشغل منفذ Docker خطواتك داخل صورة حاوية تختارها، مثل cimg/node لمشاريع Node.js.
• **مسارات العمل (Workflows)** تنظم الوظائف. يقرر مسار العمل أي الوظائف تُشغّل، وبأي ترتيب، وما إذا كانت تُشغّل بالتوازي أو بالتسلسل.

هذا الفصل مهم لاختبار واجهات برمجة التطبيقات (API). تحدد وظيفة واحدة تُثبت Apidog CLI وتُشغّل سيناريوهاتك، ثم مسار عمل يُفعّلها على الفروع التي تهتم بها.

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

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

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

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

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

قبل كتابة التكوين، جهز هذه الأشياء في تطبيق Apidog:

• **رمز وصول (access token)**. أنشئه ضمن إعدادات حساب Apidog الخاص بك. هذا يقوم بمصادقة CLI في البيئات التي لا تحتوي على واجهة رسومية. يغطي دليل مصادقة Apidog CLI إنشاء الرمز والتعامل مع أسرار CI بالتفصيل.
• **معرف سيناريو اختبار (test scenario ID)**. افتح سيناريو الاختبار الذي تريد تشغيله وانسخ معرفه من عنوان URL أو إعدادات السيناريو.
• **معرف بيئة (environment ID)**. هذا يخبر CLI بأي عنوان URL أساسي ومتغيرات يجب استخدامها، مثل بيئة الاختبار المرحلي (staging) أو الإنتاج (production).

ستحتاج أيضًا إلى حساب CircleCI متصل بموفر Git الخاص بك، مع تمكين المشروع في لوحة تحكم CircleCI.

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

لا تقم أبدًا بتضمين رمز الوصول الخاص بك مباشرة في config.yml. يتم الالتزام بالملف (committed) في Git، لذا فإن وجود رمز فيه يعني تسرب الرمز.

يوفر لك CircleCI خيارين آمنين:

• **متغيرات بيئة المشروع (Project environment variables)**. في واجهة مستخدم CircleCI، افتح إعدادات المشروع (Project Settings)، ثم متغيرات البيئة (Environment Variables)، وأضف كل قيمة. يتم تشفيرها وتُعرض للوظائف كـ $VARS.
• **السياقات (Contexts)**. السياق هو مجموعة مسماة من متغيرات البيئة المشتركة عبر المشاريع. تقوم بإنشائه ضمن إعدادات المنظمة (Organization Settings)، ثم السياقات (Contexts)، وتشير إليه من مسار عمل. السياقات مفيدة عندما تشترك عدة مستودعات في نفس رمز Apidog.

لهذا الدليل، أضف ثلاثة متغيرات: APIDOG_ACCESS_TOKEN، APIDOG_TEST_SCENARIO_ID، وAPIDOG_ENVIRONMENT_ID. يقرأ CLI هذه المتغيرات وقت التشغيل، ولا يوجد شيء حساس يعيش في مستودعك.

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

إليك تكوين كامل قابل للنسخ واللصق. ضعه في .circleci/config.yml، واضبط متغيرات البيئة الثلاثة الخاصة بك، ثم قم بالدفع (push).

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

دعني أشرح ما يفعله كل جزء.

المنفذ

docker:
  - image: cimg/node:20.11

cimg/node هي صورة CircleCI الملائمة لـ Node.js. تأتي مع Node و npm وأدوات البناء الشائعة مثبتة مسبقًا، لذا يعمل npm install -g apidog-cli بدون إعداد إضافي. يشير الوسم :20.11 إلى إصدار Node؛ قم بتحديد الإصدار الذي يعتمده فريقك.

الخطوات

يقوم checkout بسحب مستودعك إلى دليل عمل الوظيفة. الخطوة الأولى run تُثبت CLI عالميًا. الخطوة الثانية run تُشغّل اختباراتك.

انظر إلى أمر الاختبار عن كثب:

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

كل علامة (flag) تقوم بمهمة واحدة:

• --access-token يُصادق عملية التشغيل. ليس له شكل مختصر.
• -t يختار سيناريو الاختبار بواسطة المعرف.
• -e يختار البيئة. هذه العلامة مطلوبة؛ يحتاج CLI لمعرفة أي عنوان URL أساسي ومتغيرات يجب استخدامها.
• -r يحدد أدوات إعداد التقارير. هنا تطلب ثلاثة: cli يطبع النتائج المباشرة إلى سجل البناء، وjunit يكتب XML قابل للقراءة آليًا، وhtml يكتب تقريرًا قابلاً للتصفح.
• --out-dir يخبر CLI أين يكتب ملفات التقرير.

نشر التقارير

- store_test_results:
    path: ./reports
- store_artifacts:
    path: ./reports

يشير store_test_results إلى CircleCI لملف JUnit XML في ./reports. يقوم CircleCI بتحليله ويعرض علامة تبويب "الاختبارات" في البناء، بحيث يتم سرد الإخفاقات بالاسم مع بيانات التوقيت. هذا هو ما يحول كمية كبيرة من نص السجل إلى عرض منظم لنتائج النجاح/الفشل.

يقوم store_artifacts بتحميل نفس الدليل كملفات قابلة للتنزيل، بما في ذلك تقرير HTML. بعد البناء، تفتح علامة التبويب "التحف" (Artifacts) وتعرض التقرير المقدم في متصفحك. يشرح دليل تقارير اختبار Apidog CLI تنسيقات CLI و HTML و JSON بمزيد من التفصيل.

مسار العمل

workflows:
  test-api:
    jobs:
      - api-tests

يشغل مسار العمل هذا وظيفة api-tests مع كل عملية دفع. يمكنك إضافة فلاتر لتقييده على فروع معينة، أو إضافة وظائف أخرى تعمل قبله أو بعده. لوظيفة اختبار واحدة، هذا الجزء الأدنى هو كل ما تحتاجه.

تشغيل الاختبارات على الفرع الرئيسي فقط

قد لا ترغب في تشغيل كامل لـ API على كل فرع ميزة. أضف فلتر فرع إلى مسار العمل:

workflows:
  test-api:
    jobs:
      - api-tests:
          filters:
            branches:
              only:
                - main
                - develop

الآن تُشغّل الوظيفة فقط عند الدفع إلى فرعي main وdevelop. تتخطاها الفروع الأخرى، مما يحافظ على دقائق البناء الخاصة بك مركزة على الفروع التي يتم نشرها.

استخدام السياق بدلاً من متغيرات المشروع

إذا كانت عدة مستودعات تشترك في رمز Apidog واحد، فإن السياق (Context) يحافظ عليه في مكان واحد. قم بإنشاء السياق في إعدادات المنظمة (Organization Settings)، وأضف متغيراتك هناك، ثم أشر إليه:

workflows:
  test-api:
    jobs:
      - api-tests:
          context:
            - apidog-secrets

تقرأ الوظيفة الآن APIDOG_ACCESS_TOKEN والباقي من سياق apidog-secrets. قم بتدوير الرمز مرة واحدة، وستلتقط كل مشروع القيمة الجديدة.

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

يحتوي CLI على المزيد من العلامات (flags) مما يستخدمه هذا الدليل. اثنان منها يستحقان المعرفة للتكامل المستمر (CI).

يمكنك تكرار سيناريو عبر صفوف من بيانات الاختبار باستخدام -d و -n:

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

تأخذ العلامة -d مسار ملف CSV أو JSON، أو معرف مجموعة بيانات مخزنة رقمي، وتشغل السيناريو مرة واحدة لكل صف. يوضح دليل الاختبار المعتمد على البيانات كيفية تنظيم تلك الملفات.

يمكنك أيضًا التحكم في كيفية تعامل التشغيل مع حالات الفشل باستخدام --on-error، والذي يقبل القيم continue (متابعة)، أو end (إنهاء)، أو ignore (تجاهل). وبالنسبة للمشاريع التي تستخدم فروع Apidog، يستهدف --project <id> --branch <name> فرعًا محددًا. لدفع نظرة عامة على التقرير إلى سحابة Apidog، أضف --upload-report كعلامة مجردة.

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

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

نظرًا لأن السيناريو يعيش في مشروع Apidog الخاص بك، يقوم فريقك بتحرير الاختبارات في مكان واحد. لا يتغير تكوين CI نادرًا؛ بل يستدعي apidog run فقط. عندما يضيف شخص ما تأكيدًا في التطبيق، فإن البناء التالي لـ CircleCI يكتشفه بدون تعديل في YAML.

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

هل أنت مستعد لوضع مجموعة واجهات برمجة التطبيقات (API suite) الخاصة بك على كل عملية دفع؟ حمل Apidog، وقم ببناء سيناريو اختبار، وضع التكوين أعلاه في مستودعك.

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

ما هو CircleCI؟

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

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

تستخدم الفرق CircleCI لأتمتة الاختبار والنشر. تشمل الوظائف الشائعة تجميع الكود، وتشغيل اختبارات الوحدات والتكامل، والتحقق من عقود API، وبناء صور Docker، وشحن الإصدارات إلى بيئة الاختبار المرحلي أو الإنتاج. في هذا الدليل، تشغل الوظيفة اختبارات Apidog CLI API مع كل عملية دفع.

هل CircleCI مجاني؟

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

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

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

كيف يعمل CircleCI؟

عندما تدفع التزامًا (commit)، يكتشف CircleCI التغيير، ويقرأ ملف .circleci/config.yml، ويشغل المنفذ الذي حددته، مثل حاوية Docker cimg/node. يشغل كل خطوة في وظائفك بالترتيب، ثم يبلغ عن النتائج إلى موفر Git الخاص بك. تسمح لك مسارات العمل (Workflows) بربط الوظائف وتشغيلها بالتوازي. للحصول على الصورة الأكبر لكيفية تناسب هذا مع مسار التسليم (delivery pipeline)، راجع دليل ما هو CI/CD.