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

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

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

ما هي Buildkite

Buildkite هي منصة CI/CD مبنية على نموذج هجين. تحتوي على مستوى تحكم مستضاف (Hosted Control Plane)، وهو لوحة التحكم وتنسيق البناء التي تراها في متصفحك، وعملاء (Agents) يقومون بالفعل بتشغيل مهامك.

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

هذا هو الشيء الرئيسي الذي يميز Buildkite عن أنظمة CI المستضافة بالكامل. يمكن أن يبقى الكود والأسرار الخاصة بك على أجهزتك الخاصة بينما يقوم Buildkite بتنسيق عمليات البناء. بالنسبة لاختبار API، هذا يعني أن اختباراتك تعمل حيث توجد خدماتك والوصول إلى الشبكة بالفعل.

عميل Buildkite نفسه مفتوح المصدر. تمت كتابته بلغة Go وتم إصداره بموجب ترخيص MIT، مع الكود المصدري على GitHub. المنصة ومستوى التحكم المحيط بها هو منتج SaaS تجاري.

فيما تستخدم Buildkite

تستخدم الفرق Buildkite لتشغيل أي نوع من المهام المؤتمتة التي يتم تشغيلها بواسطة تغييرات الكود: بناء القطع الأثرية، وتشغيل اختبارات الوحدات والتكامل، ونشر الخدمات، وتشغيل الفحوصات الشاملة (End-to-End). نظرًا لأن العملاء يمكن أن يعملوا على أجهزتك الخاصة، فإنه شائع في الفرق التي تحتاج إلى التحكم في الحوسبة، أو حدود الشبكة، أو الأجهزة مثل وحدات معالجة الرسومات (GPUs).

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

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

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

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

المفتاح الرئيسي هو steps:، ويحتوي على قائمة. أنواع الخطوات التي ستستخدمها غالبًا لاختبار API هي هذه:

• خطوات الأوامر (Command steps): تقوم بتشغيل أوامر shell على عميل (agent). هذا هو المكان الذي تعمل فيه اختباراتك.
• خطوات الانتظار (Wait steps): توقف المسار حتى تنتهي كل خطوة سابقة. تكتبها كعنصر قائمة - wait بسيط.
• خطوات الحظر (Block steps): تنشئ بوابة موافقة يدوية، تكتب كـ - block: "Label". ينقر الإنسان للمتابعة، وهذا مفيد قبل النشر في الإنتاج.

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

مفتاح agents هو جدول تجزئة لأزواج العلامات. تستخدمه لتوجيه خطوة إلى العميل الصحيح، على سبيل المثال queue: "tests". تسمح لك العلامات بالاحتفاظ بمهام الاختبار على العملاء الذين لديهم حق الوصول إلى الشبكة أو الأدوات المناسبة.

مسار عمل جاهز للنسخ واللصق لتشغيل اختبارات API

إليك ملف .buildkite/pipeline.yml بسيط يقوم بتثبيت واجهة سطر الأوامر الخاصة بـ Apidog، ويشغل سيناريو اختبار على بيئة، ويحمّل تقرير HTML. Apidog CLI هي أداة Node.js تقوم بتشغيل سيناريوهات اختبار Apidog الخاصة بك من سطر الأوامر.

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

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

يحتوي مضيف عميل Buildkite بالفعل على الثنائي buildkite-agent متاحًا، حيث أن هذا هو ما يشغل المهمة. أنت فقط تقوم بتثبيت apidog-cli بنفسك. للحصول على جولة أعمق لكل علامة، راجع الدليل الشامل لواجهة سطر الأوامر Apidog CLI.

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

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

رمز الوصول الخاص بـ Apidog هو بيانات اعتماد. يجب ألا يتواجد أبدًا في ملف pipeline.yml الخاص بك أو يطبع في سجل البناء. يوفر لك Buildkite ميزة أصلية لهذا الغرض تسمى أسرار Buildkite.

أسرار Buildkite هي مخزن قيم-مفاتيح مشفر. تُشفّر القيم عند السكون وأثناء النقل عبر TLS، وتُفك تشفيرها على خوادم Buildkite، وتُحدد نطاقها لكل مجموعة (Cluster)، حيث لكل مجموعة مفتاح تشفير خاص بها. يعمل مع كل من عملاء Buildkite المستضافين والعملاء المستضافين ذاتيًا. أي قيمة سرية تظهر في سجلاتك يتم إخفاؤها تلقائيًا.

هناك طريقتان لاستخدام سر مخزن. الأولى هي مفتاح secrets: في خطوة الأمر. في أبسط أشكاله كقائمة، يطابق اسم المتغير البيئي مفتاح السر:

steps:
  - command: |
      apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e 358171 -r html,cli
    secrets:
      - APIDOG_ACCESS_TOKEN

إذا كان للسر المخزن اسم مختلف عن اسم المتغير البيئي الذي تريده، فاستخدم صيغة الـ Hash. المفتاح هو اسم المتغير البيئي والقيمة هي مفتاح السر:

steps:
  - command: |
      apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e 358171 -r html,cli
    secrets:
      APIDOG_ACCESS_TOKEN: apidog_token   # اسم متغير البيئة : مفتاح سر 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

أسرار Buildkite ليست خيارك الوحيد. على العملاء المستضافين ذاتيًا، يمكنك استخدام خطاف عميل environment، وهو نص برمجي يعمل في بداية كل مهمة ويقوم بتصدير القيم إلى البيئة. يمكنك تقييده بمتغيرات مثل $BUILDKITE_PIPELINE_SLUG أو $BUILDKITE_STEP_KEY بحيث يتم تحميل السر فقط للمهام الصحيحة. يمكنك أيضًا السحب من مخازن خارجية مثل AWS Secrets Manager، HashiCorp Vault، أو GCP من خلال مكونات Buildkite الإضافية، وفي هذه الحالة لا يتم تخزين السر أو إرساله إلى Buildkite أبدًا.

قيم env: العادية جيدة للتكوينات غير الحساسة، ولكن لا تضع الرموز (Tokens) هناك. لمزيد من التفاصيل حول كيفية تدفق الرمز من مخزن الأسرار الخاص بك إلى واجهة سطر الأوامر، راجع الدليل الخاص بـ مصادقة Apidog CLI.

رفع تقرير HTML كقطعة أثرية

يكتب المبلِّغ -r html تقرير HTML إلى مسار محلي في مساحة عمل العميل. يختفي هذا الملف عند انتهاء المهمة ما لم تقم بحفظه. يحافظ أمر buildkite-agent artifact upload عليه.

buildkite-agent artifact upload "apidog-reports/**/*"

تعتبر علامات الاقتباس حول نمط glob مهمة. فهي تمنع shell الخاص بك من توسيع النمط قبل أن يراه العميل، لذا يقوم العميل بالمطابقة بنفسه. تنتقل القطع الأثرية المحملة إلى التخزين الذي تديره Buildkite افتراضيًا، مع نافذة احتفاظ لمدة 6 أشهر وحد أقصى 5 جيجابايت لكل قطعة أثرية. يمكنك تمرير وجهة كحجة ثانية إذا كنت تريد إرسالها إلى مكان آخر.

بعد تشغيل عملية بناء، يظهر التقرير تحت علامة التبويب "Artifacts" الخاصة بالبناء. يمكن لأي شخص يراجع البناء تنزيله ومعرفة أي من التأكيدات (assertions) نجحت أو فشلت. إذا كنت ترغب في فهم تنسيقات التقرير أولاً، فإن دليل تقارير اختبار Apidog CLI يغطي مخرجات CLI و HTML و JSON.

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

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

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)

هنا يتم استبدال {{matrix.env}} في كل من التسمية وعلامة -e، بحيث تستهدف كل مهمة بيئة Apidog مختلفة. إذا كنت تريد فقط توزيع نسخ متطابقة من مهمة واحدة، قم بتعيين parallelism: 5 على الخطوة بدلاً من مصفوفة.

لعمليات التشغيل المعتمدة على البيانات، حيث يقوم سيناريو واحد بالتكرار على صفوف ملف CSV أو JSON، تتعامل Apidog CLI مع ذلك باستخدام علامة -d الخاصة بها بدلاً من مصفوفة Buildkite. يوضح دليل اختبار Apidog CLI المعتمد على البيانات كيفية تغذية ملف بيانات إلى سيناريو.

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

الشكل الشائع هو: تشغيل الاختبارات، والانتظار حتى تنتهي، وطلب الموافقة من إنسان، ثم النشر. Buildkite تصمم هذا باستخدام خطوات wait و block.

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"

توقف خطوة wait المسار حتى تكتمل الاختبارات. تتوقف خطوة block بانتظار نقرة يدوية وتكون مقصورة على فرع main باستخدام branches:. لا يتم تشغيل خطوة النشر إلا بعد موافقة شخص ما. هذا يمنع مجموعة اختبارات فاشلة من الوصول إلى الإنتاج. للحصول على أنماط أوسع حول هذا، راجع أفضل ممارسات CI/CD لاختبار API.

إضافة تعليق توضيحي ملخص

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

cat << 'EOF' | buildkite-agent annotate --style "success" --context "apidog"
### نتائج اختبار API
اجتازت جميع سيناريوهات Apidog. [تنزيل التقرير الكامل بصيغة HTML](artifact://apidog-reports/index.html)
EOF

تتحكم علامة --style في اللون والأيقونة، مع القيم info، warning، error، و success. تمنح علامة --context التعليق التوضيحي معرفًا فريدًا، بحيث تقوم خطوة لاحقة بنفس السياق بتحديث نفس التعليق التوضيحي بدلاً من إضافة تعليق جديد. يشير الرابط artifact:// المراجعين مباشرة إلى تقرير HTML الذي تم تحميله.

أين تتلاءم Apidog

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

Apidog هي منصة API متكاملة لتصميم واجهات برمجة التطبيقات وتصحيح الأخطاء واختبارها وإنشاء نماذج وهمية لها وتوثيقها. يمكنك بناء سيناريوهات الاختبار في محرر مرئي: ربط الطلبات، تمرير البيانات بين الخطوات، وإضافة تأكيدات دون كتابة نصوص برمجية. نظرًا لأن السيناريوهات تعيش في مشروع Apidog الخاص بك، يقوم فريقك بتحريرها في مكان واحد والتحكم في الإصدارات مع دعم الفروع.

واجهة سطر الأوامر (CLI) هي الجسر إلى التكامل المستمر (CI). تقوم ببناء سيناريو مرة واحدة، وتلتقط معرف السيناريو والبيئة، ويكون تكامل CI بأكمله عبارة عن أمر apidog run واحد. عندما تقوم بتحديث اختبار في Apidog، فإن عملية بناء Buildkite التالية تلتقط التغيير دون أي تعديلات على YAML. هذه الخاصية ذات الأمر الواحد هي ما يجعل Apidog تندمج بسلاسة في Buildkite أو GitHub Actions أو أي نظام آخر. نغطي نفس الأمر على منصات أخرى في دليل Apidog CLI CI/CD pipeline و شرح Apidog CLI مع GitHub Actions.

لتجربتها من جهازك الخاص أولاً، قبل ربط أي شيء بالتكامل المستمر، قم بتشغيل نفس الأمر محليًا باستخدام الرمز الخاص بك:

apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e 358171 -r cli,html

قم بتنزيل Apidog مجانًا، وابنِ سيناريو اختبار، وأسقط أمر apidog run في سطر واحد في مسار Buildkite الخاص بك.

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

ما هي Buildkite؟

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

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

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

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

عميل Buildkite مفتوح المصدر. تمت كتابته بلغة Go وتم إصداره بموجب ترخيص MIT، مع الكود المصدري على GitHub. المنصة ولوحة التحكم المحيطة بالعميل هي منتج SaaS تجاري، لذلك العميل نفسه فقط هو مفتوح المصدر.

هل Buildkite مجانية؟

نعم، لدى Buildkite خطة مجانية تسمى Personal. تكلفتها 0 دولار أمريكي، لا تتطلب بطاقة ائتمان ولا تنتهي صلاحيتها. تتضمن 3 وظائف متزامنة، مستخدم واحد، احتفاظ بالبيانات لمدة 90 يومًا، 500 دقيقة شهريًا من العملاء المستضافين على Linux، و 50,000 عملية تنفيذ اختبار شهريًا. يوجد أيضًا تجربة وصول كامل لمدة 30 يومًا لتقييم الميزات المدفوعة.

كيف تقوم برفع القطع الأثرية في Buildkite؟

تقوم بتشغيل buildkite-agent artifact upload "<pattern>" داخل خطوة أمر. قم بوضع نمط glob بين علامتي اقتباس حتى يطابقه العميل بدلاً من الـ shell. تنتقل الملفات إلى التخزين الذي تديره Buildkite افتراضيًا، مع احتفاظ لمدة 6 أشهر وحد أقصى 5 جيجابايت لكل قطعة أثرية. بالنسبة لاختبارات API، تقوم بتحميل تقرير HTML حتى يتمكن المراجعون من فتحه من علامة تبويب Artifacts الخاصة بالبناء.

كيف تقوم بتشغيل اختبارات API في مسار Buildkite؟

أضف خطوة أمر إلى .buildkite/pipeline.yml تقوم بتثبيت Apidog CLI باستخدام npm install -g apidog-cli، ثم تشغل apidog run بمعرف سيناريو اختبار، ومعرف بيئة عبر -e، و -r html,cli للتقارير. قم بتمرير رمز الوصول الخاص بك عبر سر Buildkite، وقم بتحميل تقرير HTML باستخدام buildkite-agent artifact upload بحيث تستمر النتائج بعد عملية البناء.