DEV Community

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

Posted on • Originally published at apidog.com

كيفية تشغيل اختبارات API المؤتمتة في بيلدكايت

يمكنك تشغيل اختبارات API المؤتمتة في Buildkite عبر خطوة أوامر داخل .buildkite/pipeline.yml: تثبيت Apidog CLI، تشغيل apidog run على بيئة محددة، ثم رفع تقرير HTML كـ artifact. يوضح هذا الدليل الإعداد العملي الكامل، بما في ذلك تمرير رمز وصول Apidog كسرّ حتى لا يظهر في السجلات.

جرّب Apidog اليوم

ملاحظة سريعة: Buildkite هي منصة CI/CD، وليست Docker BuildKit المستخدم لبناء صور Docker. تشابه الأسماء فقط؛ هذه المقالة عن Buildkite كمنصة CI/CD.

ما هي Buildkite

Buildkite منصة CI/CD بتصميم هجين:

  • Hosted Control Plane: لوحة التحكم وتنسيق عمليات البناء.
  • Agents: العملاء الذين يشغّلون المهام فعليًا.

Buildkite

هذا التقسيم مهم لأن Buildkite ينسّق العمل، بينما يتم التنفيذ على العملاء. يمكنك تشغيل العملاء على بنيتك التحتية، أو استخدام عملاء Buildkite المستضافين.

بالنسبة لاختبارات API، هذا يعني أن الاختبارات يمكن أن تعمل داخل نفس الشبكة التي توجد فيها خدماتك، مع وصول آمن إلى البيئات الداخلية والأسرار.

عميل Buildkite مفتوح المصدر، مكتوب بلغة Go ومرخّص بـ MIT، بينما منصة Buildkite ولوحة التحكم منتج SaaS تجاري.

فيما تستخدم Buildkite

تستخدم الفرق Buildkite لأتمتة المهام المرتبطة بتغييرات الكود، مثل:

  • بناء artifacts
  • تشغيل اختبارات الوحدة والتكامل
  • تشغيل اختبارات End-to-End
  • نشر الخدمات
  • تشغيل مهام تحتاج إلى عتاد أو شبكة محددة، مثل GPUs أو بيئات داخلية

Buildkite use cases

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

إذا كنت تقارن Buildkite مع أدوات أخرى، راجع قائمة أفضل أدوات التكامل المستمر لفرق API.

كيف يتم تعريف مسارات Buildkite

يُعرَّف مسار Buildkite عادة داخل:

.buildkite/pipeline.yml
Enter fullscreen mode Exit fullscreen mode

عند بدء البناء، يبحث Buildkite عن مجلد .buildkite يحتوي على pipeline.yml. يمكن أيضًا استخدام مجلد buildkite/ غير مخفي في جذر المستودع.

البنية الأساسية:

steps:
  - label: ":test_tube: تشغيل الاختبارات"
    command: "npm test"
Enter fullscreen mode Exit fullscreen mode

أهم أنواع الخطوات لاختبار API:

  • Command steps: تشغيل أوامر shell على agent.
  • Wait steps: إيقاف المسار حتى تنتهي الخطوات السابقة.
  • Block steps: بوابة موافقة يدوية قبل المتابعة، مثل النشر للإنتاج.

مثال مختصر:

steps:
  - label: ":test_tube: اختبارات API"
    command: "echo run tests"

  - wait

  - block: ":rocket: الموافقة على النشر؟"

  - label: ":rocket: نشر"
    command: "scripts/deploy.sh"
Enter fullscreen mode Exit fullscreen mode

في خطوات الأوامر ستستخدم غالبًا المفاتيح التالية:

  • label: اسم الخطوة في واجهة Buildkite.
  • key: معرف داخلي للخطوة.
  • command أو commands: الأوامر المراد تشغيلها.
  • env: متغيرات بيئة غير حساسة.
  • agents: اختيار agent أو queue محددة.
  • secrets: حقن أسرار Buildkite.
  • artifact_paths: حفظ ملفات من خطوة البناء.
  • parallelism: تشغيل نسخ متوازية من نفس الخطوة.
  • matrix: تشغيل نفس الخطوة عبر قيم متعددة.

مثال لتوجيه خطوة إلى queue محددة:

agents:
  queue: "tests"
Enter fullscreen mode Exit fullscreen mode

استخدم ذلك عندما تحتاج الاختبارات إلى عميل لديه وصول للشبكة أو أدوات محددة.

مسار جاهز لتشغيل اختبارات API باستخدام Apidog CLI

أنشئ الملف التالي:

.buildkite/pipeline.yml
Enter fullscreen mode Exit fullscreen mode

ثم أضف:

steps:
  - label: ":test_tube: اختبارات API (Apidog)"
    key: "api-tests"
    command: |
      npm install -g apidog-cli
      apidog run \
        --access-token "$APIDOG_ACCESS_TOKEN" \
        -t 637132 \
        -e 358171 \
        -r html,cli
      buildkite-agent artifact upload "apidog-reports/**/*"
    agents:
      queue: "default"
    secrets:
      - APIDOG_ACCESS_TOKEN
Enter fullscreen mode Exit fullscreen mode

ما الذي يحدث هنا؟

  1. تثبيت Apidog CLI: 
npm install -g apidog-cli
Enter fullscreen mode Exit fullscreen mode
  1. تشغيل سيناريو اختبار Apidog: 
apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t 637132 \
  -e 358171 \
  -r html,cli
Enter fullscreen mode Exit fullscreen mode
  1. رفع تقرير HTML كـ artifact: 
buildkite-agent artifact upload "apidog-reports/**/*"
Enter fullscreen mode Exit fullscreen mode

معاني أهم الخيارات:

  • -t: معرف سيناريو الاختبار أو مجلد السيناريو.
  • -e: معرف بيئة التشغيل في Apidog.
  • -r html,cli: إنشاء تقرير HTML وإظهار ملخص في الطرفية.
  • --access-token: رمز وصول Apidog، ويجب تمريره كسرّ.

الثنائي buildkite-agent يكون متاحًا داخل بيئة agent لأن Buildkite يستخدمه لتشغيل المهمة. أنت فقط تحتاج إلى تثبيت apidog-cli.

لمزيد من تفاصيل الخيارات، راجع الدليل الشامل لواجهة سطر الأوامر Apidog CLI.

وإذا أردت تجربة تشغيل API من الطرفية أولًا، راجع برنامج Apidog CLI التعليمي لاختبار REST API عبر سطر الأوامر.

تمرير رمز وصول Apidog باستخدام أسرار Buildkite

رمز وصول Apidog هو credential. لا تضعه داخل pipeline.yml ولا تطبعه في السجلات.

استخدم أسرار Buildkite بدلًا من ذلك.

الطريقة 1: استخدام secrets

إذا كان اسم السر في Buildkite هو نفسه اسم متغير البيئة:

steps:
  - label: ":test_tube: اختبارات API"
    command: |
      apidog run \
        --access-token "$APIDOG_ACCESS_TOKEN" \
        -t 637132 \
        -e 358171 \
        -r html,cli
    secrets:
      - APIDOG_ACCESS_TOKEN
Enter fullscreen mode Exit fullscreen mode

إذا كان اسم السر المخزن مختلفًا:

steps:
  - label: ":test_tube: اختبارات API"
    command: |
      apidog run \
        --access-token "$APIDOG_ACCESS_TOKEN" \
        -t 637132 \
        -e 358171 \
        -r html,cli
    secrets:
      APIDOG_ACCESS_TOKEN: apidog_token
Enter fullscreen mode Exit fullscreen mode

هنا:

APIDOG_ACCESS_TOKEN: apidog_token
Enter fullscreen mode Exit fullscreen mode

تعني:

اسم متغير البيئة داخل الخطوة: اسم السر في Buildkite
Enter fullscreen mode Exit fullscreen mode

الطريقة 2: جلب السر داخل السكربت

يمكنك أيضًا قراءة السر صراحةً باستخدام Buildkite agent CLI:

APIDOG_ACCESS_TOKEN="$(buildkite-agent secret get apidog_token)"

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t 637132 \
  -e 358171 \
  -r html,cli
Enter fullscreen mode Exit fullscreen mode

هذه الطريقة مفيدة إذا أردت التحكم في وقت قراءة السر.

بدائل للأسرار

على agents مستضافة ذاتيًا، يمكنك استخدام hook باسم environment لتصدير الأسرار قبل تشغيل المهام. ويمكنك تقييده حسب متغيرات مثل:

$BUILDKITE_PIPELINE_SLUG
$BUILDKITE_STEP_KEY
Enter fullscreen mode Exit fullscreen mode

كما يمكنك السحب من مخازن خارجية مثل:

  • AWS Secrets Manager
  • HashiCorp Vault
  • GCP Secret Manager

لا تستخدم env: للرموز الحساسة. استخدمها فقط للقيم غير السرية.

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

رفع تقرير HTML كـ artifact

عند استخدام:

-r html
Enter fullscreen mode Exit fullscreen mode

ينشئ Apidog CLI تقرير HTML محليًا داخل مساحة عمل agent. إذا لم ترفعه، سيختفي عند انتهاء المهمة.

ارفعه باستخدام:

buildkite-agent artifact upload "apidog-reports/**/*"
Enter fullscreen mode Exit fullscreen mode

ضع نمط glob بين علامتي اقتباس:

"apidog-reports/**/*"
Enter fullscreen mode Exit fullscreen mode

حتى لا يقوم shell بتوسيعه قبل أن يراه buildkite-agent.

بعد انتهاء البناء، ستجد التقرير في تبويب Artifacts داخل Buildkite.

إذا أردت فهم تنسيقات التقارير، راجع دليل تقارير اختبار Apidog CLI.

تشغيل الاختبارات بالتوازي عبر عدة بيئات

إذا أردت تشغيل نفس سيناريو الاختبار على أكثر من بيئة، استخدم matrix.

مثال:

steps:
  - label: ":test_tube: اختبارات API {{matrix.env}}"
    command: |
      npm install -g apidog-cli
      apidog run \
        --access-token "$APIDOG_ACCESS_TOKEN" \
        -t 637132 \
        -e "{{matrix.env}}" \
        -r html,cli
      buildkite-agent artifact upload "apidog-reports/**/*"
    secrets:
      - APIDOG_ACCESS_TOKEN
    matrix:
      setup:
        env:
          - "358171"   # staging
          - "358172"   # production
Enter fullscreen mode Exit fullscreen mode

سيقوم Buildkite بإنشاء مهمة لكل قيمة في matrix.env وتشغيلها بالتوازي.

يتم استبدال:

{{matrix.env}}
Enter fullscreen mode Exit fullscreen mode

داخل label وداخل أمر apidog run.

إذا أردت فقط تشغيل عدة نسخ متطابقة من نفس المهمة، استخدم:

parallelism: 5
Enter fullscreen mode Exit fullscreen mode

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

تقييد النشر خلف اختبارات API

النمط العملي الشائع:

  1. تشغيل اختبارات API.
  2. انتظار انتهاء الاختبارات.
  3. طلب موافقة يدوية.
  4. النشر.

مثال:

steps:
  - label: ":test_tube: اختبارات API"
    command: |
      npm install -g apidog-cli
      apidog run \
        --access-token "$APIDOG_ACCESS_TOKEN" \
        -t 637132 \
        -e 358171 \
        -r html,cli
    secrets:
      - APIDOG_ACCESS_TOKEN

  - wait

  - block: ":rocket: نشر؟"
    branches: "main"

  - label: ":rocket: نشر"
    command: "scripts/deploy.sh"
Enter fullscreen mode Exit fullscreen mode

ما الذي يضمنه هذا المسار؟

  • wait: لا ينتقل للنشر حتى تنتهي الاختبارات.
  • block: يطلب موافقة بشرية.
  • branches: "main": يجعل الموافقة مطلوبة فقط على فرع main.
  • إذا فشلت اختبارات API، لن يصل المسار إلى النشر.

لأنماط أوسع، راجع أفضل ممارسات CI/CD لاختبار API.

إضافة تعليق توضيحي لنتائج الاختبار

سجلات البناء قد تكون طويلة. استخدم buildkite-agent annotate لإظهار ملخص أعلى صفحة البناء.

مثال:

cat << 'EOF' | buildkite-agent annotate --style "success" --context "apidog"
### نتائج اختبار API

اجتازت جميع سيناريوهات Apidog.

[تنزيل التقرير الكامل بصيغة HTML](artifact://apidog-reports/index.html)
EOF
Enter fullscreen mode Exit fullscreen mode

خيارات مفيدة:

  • --style: يحدد نمط التعليق. القيم المتاحة تشمل:
    • info
    • warning
    • error
    • success
  • --context: معرف ثابت للتعليق. إذا استخدمت نفس السياق لاحقًا، يتم تحديث التعليق بدل إنشاء تعليق جديد.

رابط artifact:// يوجّه المراجعين مباشرة إلى التقرير الذي تم رفعه.

أين تتلاءم Apidog في هذا المسار

المسار في Buildkite يجب أن يبقى بسيطًا. كتابة الاختبارات وصيانتها تتم داخل Apidog، وليس داخل YAML.

Apidog منصة API متكاملة لتصميم واجهات API، تصحيحها، اختبارها، إنشاء mocks لها، وتوثيقها. يمكنك بناء سيناريوهات الاختبار بصريًا عبر:

  • ربط عدة requests
  • تمرير البيانات بين الخطوات
  • إضافة assertions
  • استخدام بيئات مختلفة
  • تشغيل نفس السيناريو من CI

Apidog

تعمل واجهة سطر الأوامر Apidog CLI كجسر بين Apidog وCI.

الخطوات العملية:

  1. أنشئ سيناريو الاختبار داخل Apidog.
  2. احصل على معرف السيناريو.
  3. احصل على معرف البيئة.
  4. أضف أمر apidog run في Buildkite.

مثال محلي قبل ربطه بـ CI:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t 637132 \
  -e 358171 \
  -r cli,html
Enter fullscreen mode Exit fullscreen mode

عند تعديل الاختبار داخل Apidog، ستلتقط عملية Buildkite التالية التغيير دون تعديل YAML.

نفس نمط التشغيل يعمل أيضًا مع منصات CI أخرى. راجع دليل Apidog CLI CI/CD pipeline وشرح Apidog CLI مع GitHub Actions.

قم ببناء سيناريو اختبار في Apidog، ثم أضف أمر apidog run كسطر واحد داخل مسار Buildkite الخاص بك.

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

ما هي Buildkite؟

Buildkite منصة CI/CD بتصميم هجين. لوحة تحكم مستضافة تنسّق عمليات البناء، بينما agents تشغّل المهام فعليًا. يمكن تشغيل agents على بنيتك التحتية أو على حوسبة مستضافة من Buildkite. وهي غير مرتبطة بـ Docker BuildKit.

فيما تستخدم Buildkite؟

تُستخدم Buildkite لأتمتة مهام مثل بناء artifacts، تشغيل الاختبارات، والنشر. بالنسبة لفرق API، يمكنها تشغيل الاختبارات على بيئات staging وproduction وإيقاف النشر عند فشل الاختبارات.

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

عميل Buildkite مفتوح المصدر ومكتوب بلغة Go ومرخّص بـ MIT. أما منصة Buildkite ولوحة التحكم فهي منتج SaaS تجاري.

هل Buildkite مجانية؟

نعم، لدى Buildkite خطة مجانية باسم Personal. تتضمن وظائف متزامنة محدودة، مستخدمًا واحدًا، احتفاظًا بالبيانات لمدة محددة، ودقائق شهرية للعملاء المستضافين على Linux، إضافة إلى تجربة وصول كامل لمدة 30 يومًا لتقييم الميزات المدفوعة.

كيف ترفع artifacts في Buildkite؟

استخدم الأمر التالي داخل خطوة Buildkite:

buildkite-agent artifact upload "<pattern>"
Enter fullscreen mode Exit fullscreen mode

مثال لتقارير Apidog:

buildkite-agent artifact upload "apidog-reports/**/*"
Enter fullscreen mode Exit fullscreen mode

بعد البناء، تظهر الملفات في تبويب Artifacts.

كيف تشغل اختبارات API في Buildkite؟

أضف خطوة إلى .buildkite/pipeline.yml تقوم بـ:

  1. تثبيت Apidog CLI: 
npm install -g apidog-cli
Enter fullscreen mode Exit fullscreen mode
  1. تشغيل الاختبارات: 
apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t 637132 \
  -e 358171 \
  -r html,cli
Enter fullscreen mode Exit fullscreen mode
  1. رفع التقرير: 
buildkite-agent artifact upload "apidog-reports/**/*"
Enter fullscreen mode Exit fullscreen mode

مرّر APIDOG_ACCESS_TOKEN باستخدام أسرار Buildkite، وليس عبر env: أو داخل ملف YAML.

Top comments (0)