كيفية تشغيل اختبارات Apidog CLI API في Harness CI/CD

يمكنك تشغيل اختبارات Apidog CLI داخل Harness بإضافة مرحلة CI تحتوي على خطوة Run واحدة: تثبيت apidog-cli، تنفيذ apidog run، ثم نشر نتائج JUnit في Harness. خزّن رمز وصول Apidog كـ Harness Secret، واستدعِه عبر <+secrets.getValue("...")>، واجعل Harness يقرأ ملفات XML التي ينتجها CLI. في هذا الدليل ستجد إعدادات YAML جاهزة لكل من Harness Cloud والوكيل المستضاف ذاتيًا.

جرّب Apidog اليوم

ما هو Harness CI/CD؟

Harness CI هي وحدة التكامل المستمر في منصة Harness. تستخدمها لبناء الكود، تشغيل الاختبارات، والتحقق من صحة التغييرات على بنية بناء مُدارة أو مستضافة ذاتيًا، ثم تمرير المخرجات إلى Harness CD للنشر.

في Harness، تُعرّف خط الأنابيب كملف YAML:

• pipeline: يحتوي على بيانات الخط ومراحله.
• stages: قائمة المراحل.
• كل stage يمكن أن تكون من النوع CI.
• داخل مرحلة CI توجد بنية البناء وكتلة execution.
• داخل execution تضيف خطوات مثل Run.

هذا النموذج مناسب لاختبارات API: أضف مرحلة CI، شغّل أمر الاختبار، واترك Harness يفشل الخط عند فشل الاختبارات.

يدعم Harness قراءة تقارير JUnit XML. وبما أن Apidog CLI يستطيع إخراج JUnit، يمكنك عرض نتائج الاختبار مباشرة في تبويب Tests داخل Harness بدون كود وسيط.

كيف يعمل Harness CI

الهيكل الأساسي لمرحلة CI يبدو كالتالي:

pipeline:
  stages:
    - stage:
        type: CI
        spec:
          execution:
            steps:
              - step:
                  type: Run
                  spec:
                    shell: Sh
                    command: |-
                      echo "run tests here"

لتشغيل أوامر shell، استخدم خطوة من النوع Run. داخلها تحتاج غالبًا إلى:

• shell: مثل Sh أو Bash.
• command: الأوامر التي تريد تنفيذها.
• reports: اختياري، لكنه مطلوب إذا أردت نشر نتائج JUnit.

خطوة Run واحدة كافية لتثبيت وتشغيل Apidog CLI.

Apidog CLI بسرعة

Apidog CLI هو مشغّل سطر أوامر لسيناريوهات الاختبار التي تبنيها بصريًا في Apidog. تصمم الاختبارات داخل Apidog، ثم تشغلها headless داخل CI/CD، بطريقة مشابهة لتشغيل Newman لمجموعات Postman. للمقارنة، راجع Apidog CLI vs Newman.

التثبيت والتشغيل الأساسي:

npm install -g apidog-cli

apidog run \
  --access-token <ACCESS_TOKEN> \
  -t <TEST_SCENARIO_ID> \
  -e <ENVIRONMENT_ID> \
  -r cli,junit \
  --out-dir ./apidog-reports

أهم الخيارات في CI:

الخيار	الاستخدام
--access-token	مصادقة تشغيل Apidog CLI
-t	معرف سيناريو الاختبار
-e	معرف البيئة، وهو مطلوب
-r cli,junit	إخراج النتائج في الطرفية وJUnit XML
--out-dir	مسار حفظ التقارير، افتراضيًا ./apidog-reports

اختيار junit مهم لأن Harness يقرأ ملفات XML الناتجة لعرض النتائج. لمزيد من التفاصيل، راجع دليل تقارير اختبار Apidog CLI.

تخزين رمز وصول Apidog كـ Harness Secret

لا تضع رمز الوصول مباشرة في YAML. اتبع الخطوات التالية:

1. افتح مشروعك في Harness.
2. انتقل إلى Project Settings أو نطاق المؤسسة/الحساب.
3. افتح Secrets.
4. أنشئ Text Secret جديدًا.
5. اجعل المعرّف مثلًا:

apidog_token

ثم استدعِ السر في YAML:

<+secrets.getValue("apidog_token")>

للسر على مستوى المؤسسة:

<+secrets.getValue("org.apidog_token")>

وللسر على مستوى الحساب:

<+secrets.getValue("account.apidog_token")>

داخل أمر shell، ضع التعبير بين علامات اقتباس فردية لتجنب تفسير أحرف مثل $:

--access-token '<+secrets.getValue("apidog_token")>'

يمكنك الرجوع إلى ملاحظات مصادقة Apidog CLI إذا كنت تجهز الرمز لأول مرة.

خط أنابيب Harness Cloud

استخدم Harness Cloud إذا كانت واجهات API التي تختبرها متاحة عبر الإنترنت ولا تحتاج إلى شبكة داخلية. في هذا النمط، لا تحتاج إلى إدارة بنية تحتية أو تحديد صورة Docker في خطوة التشغيل.

انسخ هذا المثال وعدّل القيم:

pipeline:
  name: Apidog API Tests
  identifier: apidog_api_tests
  projectIdentifier: YOUR_PROJECT
  orgIdentifier: YOUR_ORG
  stages:
    - stage:
        name: API Tests
        identifier: api_tests
        type: CI
        spec:
          cloneCodebase: false
          platform:
            os: Linux
            arch: Amd64
          runtime:
            type: Cloud
            spec: {}
          execution:
            steps:
              - step:
                  type: Run
                  name: Run Apidog CLI Tests
                  identifier: run_apidog_cli_tests
                  spec:
                    shell: Sh
                    command: |-
                      npm install -g apidog-cli
                      apidog run \
                        --access-token '<+secrets.getValue("apidog_token")>' \
                        -t 605067 \
                        -e 1629989 \
                        -n 1 \
                        -r cli,junit \
                        --out-dir ./apidog-reports
                    reports:
                      type: JUnit
                      spec:
                        paths:
                          - apidog-reports/*.xml

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

• YOUR_PROJECT: معرف مشروع Harness.
• YOUR_ORG: معرف المؤسسة.
• 605067: معرف سيناريو الاختبار في Apidog.
• 1629989: معرف البيئة في Apidog.
• apidog_token: معرف السر في Harness.

استخدم cloneCodebase: false عندما تكون الاختبارات مخزنة في Apidog ولا يحتاج خط الأنابيب إلى استنساخ المستودع.

نشر نتائج الاختبار في Harness

كتلة reports هي الجزء الذي يربط JUnit XML بتبويب الاختبارات في Harness:

reports:
  type: JUnit
  spec:
    paths:
      - apidog-reports/*.xml

عند تشغيل الأمر التالي:

apidog run \
  --access-token '<TOKEN>' \
  -t <TEST_SCENARIO_ID> \
  -e <ENVIRONMENT_ID> \
  -r cli,junit \
  --out-dir ./apidog-reports

سيكتب Apidog CLI ملفات XML داخل apidog-reports. بعد ذلك يقرأها Harness ويعرض:

• أسماء السيناريوهات.
• حالات النجاح والفشل.
• توقيت التنفيذ.
• تفاصيل النتائج داخل تبويب Tests.

إذا غيّرت قيمة -r لاحقًا، أبقِ junit ضمن القائمة. بدونها لن ينتج CLI ملفات XML، وستبقى نتائج Harness فارغة حتى لو نجح أمر الاختبار.

بديل الوكيل المستضاف ذاتيًا

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

في Kubernetes self-hosted runner، تختلف البنية عن Harness Cloud:

• تستخدم infrastructure بدل platform وruntime.
• تحدد connectorRef للـ Kubernetes connector.
• تحدد image لخطوة Run، مثل node:20.

مثال مرحلة CI باستخدام Kubernetes:

pipeline:
  name: Apidog API Tests Self Hosted
  identifier: apidog_api_tests_self_hosted
  projectIdentifier: YOUR_PROJECT
  orgIdentifier: YOUR_ORG
  stages:
    - stage:
        name: API Tests
        identifier: api_tests
        type: CI
        spec:
          cloneCodebase: false
          infrastructure:
            type: KubernetesDirect
            spec:
              connectorRef: YOUR_K8S_CONNECTOR
              namespace: harness-ci
          execution:
            steps:
              - step:
                  type: Run
                  name: Run Apidog CLI Tests
                  identifier: run_apidog_cli_tests
                  spec:
                    connectorRef: YOUR_DOCKER_CONNECTOR
                    image: node:20
                    shell: Sh
                    command: |-
                      npm install -g apidog-cli
                      apidog run \
                        --access-token '<+secrets.getValue("apidog_token")>' \
                        -t 605067 \
                        -e 1629989 \
                        -r cli,junit \
                        --out-dir ./apidog-reports
                    reports:
                      type: JUnit
                      spec:
                        paths:
                          - apidog-reports/*.xml

استخدم:

• YOUR_K8S_CONNECTOR: موصل Kubernetes في Harness.
• YOUR_DOCKER_CONNECTOR: موصل Docker registry.
• image: node:20: لتوفير Node.js وnpm داخل الـ pod.

لا تخلط بين نمطي البنية في المرحلة نفسها. المرحلة تكون إما Harness Cloud عبر platform وruntime، أو وكيلًا عبر infrastructure.

الاختيار بين Harness Cloud والوكيل

اختر حسب مكان وجود واجهات API ومن يدير بيئة البناء.

العامل	Harness Cloud	الوكيل المستضاف ذاتيًا
الإعداد	بدون بنية تحتية، npm مثبت مسبقًا	تدير أنت الـ cluster أو الأجهزة الافتراضية
الوصول الشبكي	نقاط نهاية عامة	نقاط نهاية خاصة أو داخلية
صورة Docker في خطوة Run	غير مطلوبة	مطلوبة على Kubernetes
نموذج التكلفة	يستهلك أرصدة بناء Harness	يستخدم حوسبتك الخاصة
الأفضل لـ	واجهات API السحابية والبدء السريع	واجهات API الداخلية وأوقات التشغيل المخصصة

ابدأ بـ Harness Cloud إذا كانت بيئة Apidog تصل إلى نقاط نهاية عامة. استخدم الوكيل عندما تكون واجهات API خلف VPN أو شبكة داخلية. أمر apidog run يبقى تقريبًا نفسه في الحالتين.

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

يمكنك تمرير ملف CSV أو JSON إلى Apidog CLI لتشغيل السيناريو بعدة مدخلات. استخدم:

• -d: مسار ملف البيانات.
• -n: عدد التكرارات.

مثال:

apidog run \
  --access-token <ACCESS_TOKEN> \
  -t <TEST_SCENARIO_ID> \
  -e <ENVIRONMENT_ID> \
  -d ./data.csv \
  -n 5 \
  -r cli,junit \
  --out-dir ./apidog-reports

داخل Harness، إذا كان ملف البيانات داخل المستودع، فعّل استنساخ الكود أو اجلب الملف قبل تشغيل Apidog CLI:

command: |-
  npm install -g apidog-cli
  apidog run \
    --access-token '<+secrets.getValue("apidog_token")>' \
    -t 605067 \
    -e 1629989 \
    -d ./data.csv \
    -n 5 \
    -r cli,junit \
    --out-dir ./apidog-reports

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

لماذا تصمم الاختبارات في Apidog أولًا؟

Apidog CLI لا ينشئ الاختبارات من الصفر؛ بل يشغّل السيناريوهات الموجودة في مشروعك. لذلك تصمم الاختبارات داخل Apidog، ثم تنفذها في Harness.

داخل Apidog يمكنك:

• بناء سيناريوهات API بصريًا.
• ربط الطلبات ببعضها.
• استخراج قيم من استجابة واستخدامها في الطلب التالي.
• إضافة تأكيدات عبر الواجهة.
• إعادة استخدام السيناريو نفسه في CI/CD عبر apidog run.

وبما أن Apidog يدعم OpenAPI ومساحات عمل الفريق والفروع، يمكن للمطورين وفرق QA العمل على مصدر واحد للحقيقة. السيناريو الذي توافق عليه في Apidog هو نفسه الذي يشغله Harness.

لأنماط CI/CD أخرى، راجع:

• ما هو CI/CD
• سير عمل GitHub Actions مع Apidog CLI
• دمج اختبارات Apidog مع Jenkins

قم بتنزيل Apidog مجانًا، أنشئ أول سيناريو اختبار، ثم وصّله بـ Harness باستخدام YAML أعلاه.

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

ما هو Harness CI/CD؟

Harness CI/CD هي منصة خطوط أنابيب لبناء البرمجيات واختبارها ونشرها. تكتب خطوط الأنابيب كـ YAML مكوّن من مراحل وخطوات. مرحلة CI تشغل البناء والاختبارات، ومرحلة CD تتولى النشر.

كيف يعمل Harness CI؟

يحتوي خط الأنابيب على مراحل. كل مرحلة CI تحدد بنية البناء وكتلة تنفيذ. داخل كتلة التنفيذ تضيف خطوات مرتبة. لتشغيل Apidog CLI، استخدم خطوة Run تنفذ أوامر shell.

كيف أخزن وأستخدم الأسرار في Harness؟

أنشئ Text Secret في Harness واحفظ معرفه. استخدمه في YAML بهذا الشكل:

<+secrets.getValue("identifier")>

استخدم org. أو account. إذا كان السر على مستوى المؤسسة أو الحساب، وضع التعبير داخل علامات اقتباس فردية في أوامر shell.

كيف أنشر نتائج الاختبار في Harness؟

أضف كتلة reports إلى خطوة Run:

reports:
  type: JUnit
  spec:
    paths:
      - apidog-reports/*.xml

ثم شغّل Apidog CLI مع -r junit أو -r cli,junit. سيقرأ Harness ملفات XML ويعرض النتائج في تبويب Tests.

هل Harness CI مجاني؟

توفر Harness طبقة مجانية لـ CI، وتستهلك عمليات Harness Cloud أرصدة بناء مضمنة في الخطة. راجع صفحة تسعير Harness الحالية لأن الحدود والأسعار قد تتغير.

هل يمكنني تشغيل اختبارات Apidog CLI دون استنساخ المستودع؟

نعم. إذا كانت الاختبارات موجودة في Apidog، استخدم:

cloneCodebase: false

يقوم Apidog CLI بالمصادقة باستخدام رمز الوصول، ثم يسحب سيناريو الاختبار والبيئة حسب المعرف. لا يحتاج خط الأنابيب إلى الكود المصدري لتشغيل اختبارات API.