12 أفضل ممارسات CI/CD لاختبار الـ API الآلي

خط أنابيب أخضر يشحن واجهة برمجة تطبيقات معطلة أسوأ من عدم وجود خط أنابيب على الإطلاق. يخبر فريقك أن كل شيء على ما يرام حتى يقوم العميل بتقديم تذكرة. تبدأ معظم إعدادات اختبار واجهة برمجة التطبيقات في CI بقوة وتتدهور بصمت: يتم تغطية عدد قليل من نقاط النهاية، ثم تصبح المجموعة متقلبة، ويضيف شخص ما `continue-on-error` لإيقاف الضوضاء، وفي غضون ربع سنة تعمل الاختبارات ولكن لا يثق بها أحد. خط الأنابيب أخضر لأنه تعلم تجاهل الفشل.

الحل ليس المزيد من الاختبارات. إنها مجموعة من القرارات حول كيفية تصميم وتشغيل وحماية هذه الاختبارات التي تصمد تحت ضغط العالم الحقيقي، مثل الإصلاح العاجل بعد ظهر يوم الجمعة أو تغيير مخطط عميق في ثلاث خدمات. يرشدك هذا الدليل عبر اثني عشر من هذه القرارات، مع تكوين ملموس يمكنك نسخه إلى GitHub Actions أو GitLab CI أو أي مشغل تستخدمه بالفعل.

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

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

1. ضع اختبارات واجهة برمجة التطبيقات في خط الأنابيب، وليس في علامة تبويب نسيت فتحها.

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

اربط المجموعة بالمرحلة المهمة. بالنسبة لمعظم الفرق، يكون ذلك عند طلبات السحب، لذا فإن واجهة برمجة تطبيقات معطلة تمنع الدمج بدلاً من الوصول إلى `main`. هذا هو الشكل الأدنى في GitHub Actions:

name: API Tests
on:
  pull_request:
    branches: [main]
jobs:
  api-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Install Apidog CLI
        run: npm install -g apidog-cli
      - name: Run API test suite
        run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t "$SCENARIO_ID" \
            -e "$APIDOG_ENV_ID" \
            -r cli,junit \
            --out-dir ./test-results
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
          SCENARIO_ID: ${{ vars.SCENARIO_ID }}
          APIDOG_ENV_ID: ${{ vars.APIDOG_ENV_ID }}

هذا هو التكامل الكامل. يخرج CLI برمز `0` عندما تنجح جميع التأكيدات ورمز غير صفري عندما يفشل أي منها، لذلك يقوم GitHub بتحويل المهمة إلى اللون الأحمر عند فشل حقيقي دون أي توصيلات إضافية. نغطي الإعداد الكامل لـ GitHub في كيفية أتمتة اختبارات واجهة برمجة التطبيقات في GitHub Actions؛ وينطبق النمط على أي مشغل.

النقطة من الممارسة الأفضل الأولى هي أن قرار الاختبار يتخذه الجهاز، وليس المطور. البشر ينسون. خطوط الأنابيب لا تفعل.

2. حافظ على أمر التشغيل قابلاً للنقل عبر موفري التكامل المستمر (CI).

خطوط الأنابيب تهاجر. تنتقل الفرق من Jenkins إلى GitHub Actions، وتضيف GitLab لمستودع جديد، أو تشغل مشغلًا مستضافًا ذاتيًا للامتثال. إذا كانت اختبارات واجهة برمجة التطبيقات الخاصة بك ملحومة بنظام المكونات الإضافية لموفر واحد، فإن كل ترحيل يعني إعادة كتابتها.

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

apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t "$SCENARIO_ID" -e "$ENV_ID" -r cli,junit

يعمل نفس السطر في خطوة `run` في GitHub Actions، وكتلة `script` في GitLab، ومرحلة shell في Jenkins، أو قسم `script` في Travis. يتغير الغلاف المحيط به فقط. GitLab، على سبيل المثال:

api-tests:
  image: node:20
  script:
    - npm install -g apidog-cli
    - apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t "$SCENARIO_ID" -e "$ENV_ID" -r cli,junit
  artifacts:
    when: always
    reports:
      junit: ./test-results/*.xml

نظرًا لأن العمل الشاق (تنسيق الطلبات، التأكيدات، حل البيئة) يتم في CLI وتعريفات الاختبارات موجودة في Apidog، فإن ملف YAML لخط الأنابيب الخاص بك يظل رفيعًا. عندما تقوم بتبديل الموفرين، تنسخ ستة أسطر، وليس ستمائة. تم تفصيل إصدار Jenkins في كيفية دمج اختبارات Apidog المؤتمتة مع Jenkins لـ CI/CD إذا كانت تلك هي مجموعتك التقنية.

3. تأكد من السلوك، وليس فقط رموز الحالة.

اختبار يتحقق فقط من `200 OK` سينجح بينما تعيد واجهة برمجة التطبيقات الخاصة بك مصفوفة فارغة، أو عملة خاطئة، أو قيمة خالية حيث يتوقع العميل كائنًا. الاختبارات التي تعتمد على رمز الحالة فقط هي السبب الأكبر الوحيد وراء شحن خطوط الأنابيب الخضراء استجابات معطلة.

تتحقق التأكيدات الحقيقية من شكل ومحتوى الاستجابة: الحقول الموجودة، وأنواعها، والقيم المهمة للمستهلك. في Apidog، تقوم ببناء هذه التأكيدات بصريًا مقابل الاستجابة، لذلك أنت تتأكد من الحمولة الفعلية بدلاً من تخمين مسار JSON في ذهنك. يؤكد اختبار بحث الطلب القوي أن الحالة هي `200`، وأن `order.total` رقم، وأن `currency` تساوي القيمة التي أرسلتها، وأن مصفوفة `items` ليست فارغة. كل من هذه تأكيد منفصل يفشل بشكل مستقل، لذا فإن بناء أحمر يخبرك أي عقد انكسر.

ثلاث قواعد تجعل التأكيدات تصمد بمرور الوقت:

• تأكد من العقد، وليس البيانات. تحقق من أن `total` هو رقم، وليس أنه يساوي `49.99`. القيمة الدقيقة تتغير؛ النوع لا يتغير.
• اهتمام واحد لكل تأكيد. تجميع ستة فحوصات في تأكيد واحد يخفي أي منها فشل.
• غطِ المسار غير السعيد. رمز `400` للمدخلات السيئة و`401` للرمز المميز المفقود هما جزء من عقدك أيضًا. اختبر أنهما لا يزالان يعملان بشكل صحيح.

لمعالجة أعمق لكتابة التأكيدات التي تصمد أمام عمليات إعادة الهيكلة، راجع دليلنا حول تأكيدات واجهة برمجة التطبيقات. التأكيدات القوية هي ما يحول اختبار الدخان إلى اختبار عقد، واختبارات العقد هي ما يلتقط الانحدارات المهمة.

4. أدر البيئات والأسرار كتكوين، وليس كقيم مبرمجة ثابتة أبدًا.

تعمل اختباراتك على أهداف مختلفة: مكدس محلي، واجهة برمجة تطبيقات تجريبية، نقطة نهاية دخان إنتاجية. يتغير عنوان URL الأساسي، ورموز المصادقة، ومعرفات المستأجرين بينها جميعًا. ترميز أي من هذه القيم في اختبار هو كيف يصل اختبار تجريبي عن طريق الخطأ إلى الإنتاج، أو كيف ينتهي رمز مميز في سجل Git الخاص بك.

احتفظ بالبيئات كتكوينات مسماة واحقن الفروقات. في Apidog، تحتوي البيئة على عنوان URL الأساسي والمتغيرات لهدف واحد؛ تختار أي منها يستخدمه تشغيل CI باستخدام العلامة `-e`. يزود خط الأنابيب رمز الوصول من مخزن الأسرار الخاص به، وليس أبدًا من ملف في المستودع:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t "$SCENARIO_ID" \
  -e "$STAGING_ENV_ID" \
  -r cli,junit

نفس السيناريو، موجه إلى قيمة `-e` مختلفة، يصبح اختبار الدخان للإنتاج الخاص بك. لا يتغير شيء في الاختبار؛ فقط البيئة التي يتم حلها مقابلها تتغير. قم بتخزين `APIDOG_ACCESS_TOKEN` في GitHub Secrets، أو متغيرات GitLab CI/CD، أو مدير بيانات الاعتماد الخاص بالمشغل، وارجع إليه بالاسم. القاعدة بسيطة: أي شيء يختلف بين البيئات أو أي شيء سري هو تكوين، ويتم حقن التكوين في وقت التشغيل.

5. اجعل الاختبارات حتمية ليكون خط الأنابيب جديرًا بالثقة.

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

يأتي تقلب اختبارات واجهة برمجة التطبيقات من عدد قليل من المصادر المتوقعة:

• حالة متغيرة مشتركة. اختباران ينشئان مستخدمًا بنفس البريد الإلكتروني، أو اختبار يعتمد على بيانات حذفها اختبار آخر. يجب على كل اختبار إعداد وتفكيك بياناته الخاصة، أو استخدام مستأجرين معزولين.
• افتراضات التوقيت. التأكيد على نتيجة غير متزامنة قبل أن تكون جاهزة. إذا كانت العملية في النهاية، استقصِ عن الشرط بدلاً من الانتظار لعدد ثابت من الثواني.
• تبعيات حقيقية لا تتحكم فيها. بيئة دفع تجريبية خارجية تفرض عليك قيودًا على المعدل، أو خدمة عليا معطلة للصيانة. قم بمحاكاة هذه الحدود بحيث يقيس اختبارك واجهة برمجة التطبيقات الخاصة بك، وليس وقت تشغيل خدمة أخرى. يمكن لـ Apidog إنشاء محاكاة لتبعية غير مستقرة من مخططها، مما يبعد التقلبات الخارجية عن بناءك.
• الاعتماد على الترتيب. الاختبارات التي تنجح فقط عند تشغيلها بتسلسل معين. يجب أن تنجح المجموعة عند تشغيلها بأي ترتيب، لأن المشغلات تعمل بالتوازي.

الحتمية هي الفرق بين خط أنابيب يحترمه الناس وخط أنابيب يتجنبونه. استثمر في الهندسة مبكرًا؛ الاختبارات المتقلبة تتراكم الفائدة.

6. حافظ على سرعة مرحلة اختبار واجهة برمجة التطبيقات، وإلا سيتجنبها المطورون.

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

بضعة عوامل تمكنك من تحقيق ذلك:

• تشغيل سيناريوهات مستقلة بالتوازي. إذا كانت اختباراتك حتمية (الممارسة الخامسة الأفضل)، فلا شيء يمنعك من تقسيمها عبر مهام متوازية أو السماح للمشغل بتوزيعها. يمكن تشغيل المجموعات المستقلة جنبًا إلى جنب.
• صنف اختباراتك. قم بتشغيل مجموعة دخان سريعة على كل طلب سحب ومجموعة الانحدار الكاملة عند الدمج في `main` أو على جدول ليلي. ليس كل اختبار يحتاج إلى حماية كل تثبيت.
• تخزين التثبيت مؤقتًا. يؤدي تخزين تثبيت npm العالمي لـ `apidog-cli` مؤقتًا عبر التشغيلات إلى تقليل وقت الإعداد لكل مهمة.
• الفشل بسرعة حيث يساعد، وأكمل حيث لا يساعد. في طلب السحب، توقف عند أول فشل لتقديم ملاحظات سريعة. في التشغيل الليلي الكامل، استخدم `--on-error continue` الخاص بـ CLI حتى لا تخفي نقطة نهاية واحدة معطلة الأربعين نقطة الأخرى التي تعطلت أيضًا.

هذا هو النمط المتدرج في GitHub Actions، مع تشغيل دخان سريع على طلبات السحب والمجموعة الكاملة على جدول زمني:

on:
  pull_request:
    branches: [main]
  schedule:
    - cron: '0 2 * * *'   # nightly full regression

jobs:
  api-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g apidog-cli
      - name: Run suite
        run: |
          if [ "${{ github.event_name }}" = "pull_request" ]; then
            apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t "$SMOKE_ID" -e "$ENV_ID" -r cli,junit --out-dir ./test-results
          else
            apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t "$FULL_ID" -e "$ENV_ID" -r cli,junit --on-error continue --out-dir ./test-results
          fi
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

مرحلة سريعة تعمل أفضل من مرحلة شاملة يتم تعطيلها.

7. انشر نتائج قابلة للقراءة آليًا، وليس مجرد كومة من نصوص وحدة التحكم.

عندما يفشل البناء، فإن عبارة "اختبارات واجهة برمجة التطبيقات فشلت" ليست كافية. تحتاج إلى معرفة أي تأكيد تعطل، وفي أي سيناريو، وعلى أي طلب. بناء أحمر مع ألف سطر من مخرجات وحدة التحكم بالكاد أفضل من عدم وجود اختبار على الإطلاق؛ لا يزال يتعين على شخص ما قراءتها.

الحل هو إصدار النتائج بتنسيق يقوم خادم CI الخاص بك بتحليله بشكل طبيعي. JUnit XML هو التنسيق القياسي لنتائج اختبار CI، وتقريبًا كل منصة تقرأه. يكتب Apidog CLI واحدًا باستخدام مُبلغ `junit`:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t "$SCENARIO_ID" \
  -e "$ENV_ID" \
  -r cli,html,junit \
  --out-dir ./test-results

يصدر هذا الأمر ثلاث طرق عرض لنفس التشغيل: `cli` لمخرجات وحدة التحكم المباشرة، و`html` لتقرير يمكن تصفحه يمكن للإنسان فتحه، و`junit` للآلة. وجه خط الأنابيب الخاص بك إلى XML وستقوم المنصة بتحويله إلى نتائج منظمة لكل اختبار:

      - name: Publish test report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: api-test-results
          path: ./test-results

لاحظ `if: always()` . تريد أن يتم نشر التقرير حتى عندما يفشل التشغيل، لأن التشغيل الفاشل هو بالضبط عندما تحتاجه. الفائدة حقيقية: بدلاً من "بناء واجهة برمجة التطبيقات معطل"، تحصل على "بدأ تأكيد `cart-total` في سيناريو الدفع بالفشل"، مما يحول جلسة تصحيح الأخطاء إلى نظرة سريعة.

8. قم بتقييد عمليات الدمج على المجموعة بحماية الفرع.

مجموعة اختبار ناجحة لا تمنع أي شيء هي مجرد إشعار. الهدف من CI هو جعل الكود المعطل غير قابل للدمج، وهذا يتطلب خطوة إضافية أكثر مما تقوم به معظم الفرق: حماية الفرع.

رمز الخروج يقوم بالعمل المحلي. نظرًا لأن Apidog CLI يخرج برمز غير صفري عند أي تأكيد فاشل، فإن المهمة تتحول إلى اللون الأحمر عند فشل حقيقي. ولكن المهمة الحمراء على طلب السحب هي مجرد استشارية حتى تجعل الفحص مطلوبًا. في GitHub، عيّن فحص اختبارات واجهة برمجة التطبيقات كفحص حالة مطلوب على `main`؛ يظل زر الدمج معطلاً حتى يصبح أخضر. لدى GitLab و Bitbucket ما يعادله في إعدادات طلبات الدمج الخاصة بهما.

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

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

9. أنشئ تغطية الاختبار من مواصفات واجهة برمجة التطبيقات الخاصة بك بدلاً من كتابتها يدويًا.

أبطأ جزء في اختبار واجهة برمجة التطبيقات هو الحفاظ على تزامن الاختبارات مع واجهة برمجة التطبيقات. كل نقطة نهاية جديدة تحتاج إلى اختبار جديد؛ كل حقل متغير يحتاج إلى تأكيد محدث. عند القيام بذلك يدويًا، تتأخر الاختبارات دائمًا عن واجهة برمجة التطبيقات، والفجوة هي المكان الذي تعيش فيه الانحدارات.

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

هذا مهم في CI لأن الاختبارات المدفوعة بالمواصفات تلتقط خطأً شائعًا ومحددًا: الانجراف بين ما تعد به وثائقك وما تعيده واجهة برمجة التطبيقات الخاصة بك. عندما يتم إنشاء الاختبار من المواصفات وتشغيله مقابل واجهة برمجة التطبيقات الحية، يؤدي عدم التطابق إلى فشل البناء. يصبح العقد قابلاً للتنفيذ. لا تزال تكتب التأكيدات التي ترمز إلى المعنى التجاري يدويًا، لكنك لا تكتب يدويًا النص المتكرر لـ "هل توجد نقطة النهاية هذه وتعيد الشكل الموثق". دع المواصفات تتحمل هذا العبء.

10. استخدم الاختبارات الموجهة بالبيانات لتغطية الحالات الشاذة دون تكرار السيناريوهات.

تتصرف نقطة النهاية نفسها بشكل مختلف عبر المدخلات: طلب صالح، طلب يتجاوز حد الائتمان، طلب بمعرف SKU غير معروف، طلب بعملة غير مدعومة. كتابة سيناريو منفصل لكل منها هو كيف تتضخم المجموعات لتصبح مئات الاختبارات المتطابقة تقريبًا التي لا يحافظ عليها أحد.

يشغل الاختبار الموجه بالبيانات سيناريو واحدًا مقابل العديد من صفوف الإدخال. تحدد الطلب والتأكيدات مرة واحدة، ثم تغذي جدولًا من الحالات. يقبل Apidog CLI ملف بيانات باستخدام العلامة `-d`:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t "$SCENARIO_ID" \
  -e "$ENV_ID" \
  -d ./test-data/orders.csv \
  -r cli,junit \
  --out-dir ./test-results

يصبح كل صف في `orders.csv` تكرارًا واحدًا بنجاحه أو فشله الخاص. سيناريو واحد، استدعاء CLI واحد، تغطية كاملة للحالات الشاذة، وتقرير JUnit يوضح أي صفوف إدخال فشلت. هذا يحافظ على مجموعتك صغيرة وتغطيتك واسعة، وهذا بالضبط ما تريده في CI. يتعمق دليلنا حول اختبار واجهة برمجة التطبيقات الموجه بالبيانات باستخدام CSV أو JSON في هيكلة ملف البيانات.

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

11. قم بتشغيل اختبار دخان بعد النشر على البيئة الحقيقية.

الاختبارات التي تنجح مقابل بيئة التطوير تخبرك أن البناء جيد. لا تخبرك أن النشر قد نجح. انحراف التكوين، متغير بيئة مفقود، موازن تحميل موجه بشكل خاطئ، شهادة منتهية الصلاحية: كل هذه الأمور تتجاوز جميع اختبارات ما قبل الدمج وتفشل فقط في البيئة التي تم الشحن إليها فعليًا.

الحارس هو اختبار دخان يتم تشغيله بعد النشر، على الهدف الحي. إنها مجموعة صغيرة وسريعة، تغطي فقط المسارات الحيوية، تدفق المصادقة الخاص بك، أهم نقاط نهاية القراءة والكتابة الخاصة بك، موجهة نحو الإنتاج أو البيئة المنشورة حديثًا. نظرًا لأن أمر التشغيل قابل للنقل (الممارسة الثانية الأفضل) والبيئات مجرد تكوين (الممارسة الرابعة الأفضل)، فهذه هي نفس المجموعة بعلامة `-e` مختلفة:

  smoke-after-deploy:
    needs: deploy
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g apidog-cli
      - name: Smoke test production
        run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t "$SMOKE_SCENARIO_ID" \
            -e "$PROD_ENV_ID" \
            -r cli,junit \
            --out-dir ./smoke-results
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

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

12. تعامل مع مجموعة الاختبار ككود تقوم بصيانته، وليس كإعداد تنتهي منه.

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

بضعة عادات تحافظ على صحة المجموعة على المدى الطويل:

• أضف الاختبار مع الميزة. يتم شحن نقطة نهاية جديدة مع سيناريوها في نفس طلب السحب، وليس في متابعة لا تصل أبدًا.
• أصلح التقلبات في نفس اليوم الذي تظهر فيه. الاختبار المتقلب المعزول هو فجوة تغطية بضوء أخضر عليه. لا تدع `continue-on-error` يصبح دائمًا.
• راجع ما لا تغطيه المجموعة. تحقق بشكل دوري من نقاط النهاية التي لا تحتوي على تأكيدات. النقاط غير المختبرة هي حيث تبدأ الانقطاعات التالية.
• احتفظ بتكوين خط الأنابيب في التحكم في الإصدارات. تعيش ملفات YAML وتعريفات البيئة وبيانات الاختبار كلها في المستودع، وتتم مراجعتها مثل أي تغيير آخر.

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

تجميع كل ذلك

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

الأساس المشترك هو الحفاظ على اختباراتك قريبة من عقدك وقابلة للتشغيل من أمر واحد. هذا هو سير عمل Apidog في جملة واحدة: صمم واجهة برمجة التطبيقات واختباراتها في مكان واحد، ثم قم بتشغيل تلك المجموعة بالضبط في أي خط أنابيب باستخدام `apidog run`. يخرج CLI برمز غير صفري عند الفشل، ويصدر JUnit ليقوم CI الخاص بك بتحليله، ويتصرف بنفس الطريقة سواء استدعاه GitHub Actions أو GitLab أو Jenkins أو مشغل مستضاف ذاتيًا.

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

الأسئلة الشائعة

ما الفرق بين اختبار واجهة برمجة التطبيقات في CI و CI/CD؟ يقوم CI (التكامل المستمر) بتشغيل اختبارات واجهة برمجة التطبيقات الخاصة بك تلقائيًا على كل تثبيت أو طلب سحب للكشف عن الانحدارات مبكرًا. يقوم CD (التسليم المستمر) بترقية بناء إلى هدف نشر بمجرد اجتيازه لتلك الفحوصات. اختبارات واجهة برمجة التطبيقات توجد في كليهما: مجموعة ما قبل الدمج تحمي التكامل، ومجموعة الدخان بعد النشر تتحقق من التسليم. نفس أمر Apidog CLI يخدم كلا المرحلتين.

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

كيف أوقف تقلب اختبارات واجهة برمجة التطبيقات الخاصة بي في CI؟ الأسباب الثلاثة الكبرى هي بيانات الاختبار المتغيرة المشتركة، وافتراضات التوقيت على العمليات غير المتزامنة، والتبعيات الخارجية غير المتحكم فيها. امنح كل اختبار بياناته الخاصة، استقصِ عن الظروف غير المتزامنة بدلاً من الانتظار لوقت ثابت، وقم بمحاكاة الحدود الخارجية التي لا تتحكم فيها. الهدف هو مجموعة اختبار تنجح بأي ترتيب وفي أي تشغيل.

كيف أجعل اختبار واجهة برمجة التطبيقات الفاشل يمنع الدمج؟ جزأين. أولاً، يجب أن يخرج مشغل الاختبار برمز غير صفري عند الفشل؛ يقوم Apidog CLI بذلك عند أي تأكيد فاشل، لذلك تتحول المهمة إلى اللون الأحمر تلقائيًا. ثانيًا، ضع علامة على تلك المهمة كفحص حالة مطلوب في قواعد حماية الفرع لمضيف Git الخاص بك. يظل زر الدمج معطلاً حتى ينجح الفحص.

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

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