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

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

ما هو Harness CI/CD؟

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

تحدد كل شيء كملف YAML. يحتوي خط الأنابيب على مرحلة واحدة أو أكثر. كل مرحلة لها نوع، وتعمل مرحلة CI على بنية أساسية للبناء. داخل المرحلة، تحتوي كتلة التنفيذ على قائمة مرتبة من الخطوات التي تقوم بتشغيل أوامرك.

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

يقرأ Harness JUnit XML لإعداد تقارير الاختبار. نظرًا لأن Apidog CLI يمكنه إصدار JUnit، فإنك تحصل على علامة تبويب "الاختبارات" أصلية مع عدد حالات النجاح والفشل في كل عملية بناء. لا توجد حاجة إلى أي كود وسيط.

كيف يعمل Harness CI

التسلسل الهرمي لـ YAML صارم، لذا من المفيد رؤية التداخل قبل كتابة أي شيء. يبدو خط أنابيب CI بهذا الشكل من الأعلى للأسفل:

`pipeline` يحتوي على بيانات وصفية وقائمة `stages`.
كل `stage` له `type: CI` و`spec`.
يصرح `spec` الخاص بالمرحلة بالبنية التحتية للبناء وكتلة `execution`.
`execution` يحتوي على قائمة `steps`.
كل `step` له `type`، `name`، `identifier`، و`spec` خاص به.

لتشغيل أمر شل، يكون نوع الخطوة هو `Run`. يحمل `spec` الخاص بخطوة Run حقل `shell` (Bash، Sh، PowerShell، Pwsh، أو Python) وحقل `command` الذي يحتوي على النص البرمجي الخاص بك. تكتب الأوامر متعددة الأسطر باستخدام YAML block scalar `|-`.

خطوة التشغيل الواحدة هذه هي كل ما تحتاجه لتثبيت وتنفيذ Apidog CLI. كل شيء آخر في هذا الدليل هو تهيئة حول تلك الخطوة الواحدة.

Apidog CLI في دقيقة واحدة

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

تقوم بتثبيته من npm وتشغيل أمر واحد:

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` تصادق على التنفيذ السحابي وليس لها شكل مختصر. العلامة `-e` تحدد البيئة وهي مطلوبة. العلامة `-t` تختار سيناريو اختبار حسب المعرف. العلامة `-r` تختار التقارير، و`junit` هي إحدى القيم المدعومة (`cli`، `html`، `json`، `junit`). العلامة `--out-dir` تتحكم في مكان هبوط التقارير، وتكون القيمة الافتراضية `./apidog-reports`.

اختيار `-r cli,junit` هو الجسر إلى Harness. يكتب CLI JUnit XML في دليل الإخراج، ويقرأه Harness مباشرة. لمزيد من المعلومات حول ما ينتجه CLI، راجع دليل تقارير اختبار Apidog CLI.

تخزين رمز وصول Apidog الخاص بك كسر Harness

لا تقم أبدًا بتضمين الرمز بشكل ثابت في YAML. أضفه إلى مدير أسرار Harness أولاً، ثم ارجع إليه.

في واجهة مستخدم Harness، انتقل إلى إعدادات مشروعك (أو المؤسسة/الحساب)، وافتح Secrets، وأنشئ سر نصي جديد. امنحه المعرّف `apidog_token`. المعرّف هو ما تشير إليه في YAML، ويختلف عن اسم العرض.

يمكنك الإشارة إلى السر بهذا التعبير:

<+secrets.getValue("apidog_token")>

استخدم المعرّف داخل علامات الاقتباس، وليس اسم العرض. بالنسبة للسر ذي النطاق التنظيمي، أضف البادئة `org.` مثل `<+secrets.getValue("org.apidog_token")>`. بالنسبة للسر ذي النطاق على مستوى الحساب، استخدم `account.` بدلاً من ذلك.

قم بتضمين التعبير بعلامات اقتباس فردية داخل أمر shell. قد يحتوي الرمز المميز على حرف `$`، وتمنع علامات الاقتباس الفردية shell من توسيعه. يمكنك قراءة المزيد حول إعداد الرمز المميز في ملاحظات مصادقة Apidog CLI.

خط أنابيب Harness Cloud (نقطة بداية موصى بها)

توفر لك Harness Cloud آلات بناء مُدارة من Harness مع Node.js و npm مثبتة مسبقًا. لا توجد بنية تحتية للصيانة، ويعمل Linux مباشرة. هذه هي أسرع طريقة للحصول على خط أنابيب يعمل.

على Harness Cloud، تستخدم `spec` المرحلة كتلة `platform` وكتلة `runtime` من `type: Cloud`. لا تحدد `image` في خطوة التشغيل هنا، لأن الجهاز المُدار لديه الأدوات بالفعل.

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

استبدل `605067` بمعرف سيناريو الاختبار الخاص بك و`1629989` بمعرف بيئتك. العلامة `-n 1` تشغل تكرارًا واحدًا. قم بتعيين `cloneCodebase: false` لأن الاختبارات موجودة في سحابة Apidog، لذا لا يحتاج خط الأنابيب إلى مستودعك.

نشر نتائج الاختبار

كتلة `reports` في خطوة Run هي التي تعرض النتائج في Harness. تأخذ `type` من نوع `JUnit` و`spec` مع قائمة `paths` تشير إلى ملفات XML الخاصة بك.

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

يقوم Harness بتحليل JUnit XML فقط للإبلاغ الأصلي. بعد البناء، سترى علامة تبويب "الاختبارات" مع كل سيناريو، وحالته، وتوقيته. يتطابق النمط الشامل `apidog-reports/*.xml` مع الملفات التي كتبها CLI باستخدام `-r cli,junit` في دليل الإخراج الافتراضي.

يوفر Harness أيضًا Test Intelligence، الذي يستخدم نوع خطوة `Test` منفصلًا لتشغيل الاختبارات المتأثرة بتغيير التعليمات البرمجية فقط. يستهدف هذا التحسين اختبارات الوحدة على مستوى اللغة، وليس سيناريوهات API بدون واجهة رسومية. لاستيعاب إخراج Apidog CLI، فإن خطوة Run العادية مع كتلة `reports` من نوع JUnit هي المسار الصحيح.

إذا قمت بتغيير أداة إعداد التقارير (reporter) في أي وقت، احتفظ على الأقل بـ `junit` في قائمة `-r`. بدونها، لن يكتب CLI أي ملفات XML، وستبقى علامة تبويب "الاختبارات" فارغة حتى لو نجحت الخطوة نفسها.

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

استخدم بناءً مدعومًا بوكيل عندما تحتاج إلى الوصول إلى شبكة خاصة، أو وقت تشغيل مخصص أو قديم، أو ترغب في تجنب أرصدة بناء Harness Cloud. يقوم وكيل Kubernetes بتشغيل كل مرحلة كجراب (pod).

تتغير البنية بطريقتين. تستخدم `spec` المرحلة كتلة `infrastructure` بدلاً من `platform` و`runtime`. وعلى بنية Kubernetes التحتية، يجب أن تعلن كل خطوة Run عن `connectorRef` و`image`، لأن الخطوة تعمل داخل حاوية تحددها.

        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

يمنحك السطر `image: node:20` Node.js و npm داخل الـ pod. تشير قيم `connectorRef` إلى موصلات Kubernetes و Docker المسجلة لديك. لا تخلط بين أسلوبي البنية التحتية في مرحلة واحدة. تكون المرحلة إما Harness Cloud (`platform` بالإضافة إلى `runtime`) أو مدعومة بوكيل (`infrastructure`)، ولا تكون كليهما أبدًا.

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

اختر بناءً على مكان وجود واجهات برمجة التطبيقات الخاصة بك ومن يمتلك آلات البناء.

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

ابدأ مع Harness Cloud إذا كانت بيئة Apidog الخاصة بك تصل إلى نقاط نهاية عامة. انتقل إلى وكيل عندما تكون بيئة الاختبار الخاصة بك خلف شبكة افتراضية خاصة (VPN) أو تحتاج إلى وقت تشغيل تتحكم فيه. تظل خطوة Run وأمر Apidog متطابقين تقريبًا بين الاثنين.

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

يمكنك تغذية ملف CSV أو JSON في عملية التشغيل لاختبارات معلمة. تأخذ العلامة `-d` (الاسم الطويل `iteration-data--`) مسار ملف البيانات، وتحدد `-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، ستقوم بـ `git clone` أو تجهيز ملف البيانات أولاً، ثم توجيه `-d` إلى مساره. للحصول على النمط الكامل، راجع اختبار Apidog CLI المدفوع بالبيانات والدليل الأوسع اختبار API الآلي.

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

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

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

نظرًا لأن Apidog يدعم OpenAPI أصلاً مع دعم الفروع ومساحات عمل الفريق، فإن مهندسي ضمان الجودة ومطوري الواجهة الخلفية يشاركون مصدرًا واحدًا للحقيقة. يصبح السيناريو الموافق عليه في فرع هو نفس السيناريو الذي ينفذه أمر `apidog run` الخاص بك. لأنماط خطوط الأنابيب الأوسع، يغطي التمهيد ما هو CI/CD ودليل سير عمل GitHub Actions نفس CLI في أنظمة أخرى. تستخدم التعليمات الإرشادية لـ Jenkins في دمج اختبارات Apidog مع Jenkins نفس شكل الأمر تمامًا.

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

button

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

ما هو Harness CI/CD؟

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

كيف يعمل Harness CI؟

يحتوي خط الأنابيب على قائمة مراحل. كل مرحلة CI لها مواصفات تعلن عن بنية البناء وكتلة تنفيذ. تقوم كتلة التنفيذ بتشغيل قائمة مرتبة من الخطوات. خطوة التشغيل تنفذ أمر شل، وهو المكان الذي تقوم فيه بتثبيت وتشغيل Apidog CLI.

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

قم بإنشاء سر نصي في مدير أسرار Harness ودوّن معرفه. ارجع إليه في YAML باستخدام `<+secrets.getValue("identifier")>`، باستخدام المعرف بدلاً من اسم العرض. أضف بادئة `org.` أو `account.` لتلك النطاقات، وقم بتضمين التعبير بعلامات اقتباس فردية داخل أوامر shell.

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

أضف كتلة `reports` إلى خطوة Run الخاصة بك مع `type: JUnit` وقائمة `paths` تشير إلى ملفات XML الخاصة بك. يقوم Harness بتحليل JUnit XML ويعرض النتائج في علامة تبويب "الاختبارات" في البناء. يصدر Apidog CLI هذا XML عند تمرير `-r junit` أو `-r cli,junit`.

هل Harness CI مجاني؟

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

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

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