DEV Community

Cover image for اختبار انحدار الـ API: كيفية اكتشاف التغييرات الكاسرة مبكرًا
Yusuf Khalidd
Yusuf Khalidd

Posted on • Originally published at apidog.com

اختبار انحدار الـ API: كيفية اكتشاف التغييرات الكاسرة مبكرًا

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

جرّب Apidog اليوم

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

ما هو اختبار الانحدار لواجهة برمجة التطبيقات؟

اختبار الانحدار يعني إعادة تشغيل اختبارات كانت ناجحة سابقًا للتأكد من أن السلوك لم يتغير بعد تعديل جديد.

بالنسبة إلى API، السلوك المقصود هو العقد الذي يعتمد عليه المستهلكون:

  • المسارات
  • رموز الحالة
  • مخطط الاستجابة
  • أنواع الحقول
  • القيم التعاقدية المهمة

تتراجع واجهات API لأسباب شائعة:

  • إعادة تسمية حقل JSON
  • تغيير رمز 200 إلى 204
  • إضافة قاعدة تحقق ترفض مدخلات كانت مقبولة
  • تحديث ORM يغير تنسيق التاريخ
  • تحديث تبعية يغير رسالة خطأ يعتمد عليها عميل

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

اختبار الانحدار لواجهة API أضيق من اختبار الانحدار العام. أنت لا تعيد اختبار كل منطق التطبيق، بل تتحقق من واجهة HTTP التي ترتبط بها الأنظمة الأخرى. هذا التركيز يجعله مناسبًا للتشغيل مع كل commit.

ما الذي يجب تحديده كخط أساس؟

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

ابدأ بهذه الطبقات الأربع:

  1. رموز الحالة

    كل نقطة نهاية يجب أن تُرجع رمزًا متوقعًا لمدخلات معروفة. تغيّر 200 إلى 500 أو 201 إلى 200 قد يكون تراجعًا حتى لو بدا body صحيحًا.

  2. مخطط الاستجابة

    تحقق من أسماء الحقول، التداخل، وأنواع القيم: string، number، array، object. انحراف المخطط من أكثر الانحدارات الصامتة شيوعًا.

  3. قيم الحقول الرئيسية

    لا تؤكد على كل قيمة. ركّز على القيم ذات المعنى التعاقدي:

    • id موجود
    • status ضمن مجموعة معروفة
    • total رقم

  4. العقود

    قارن الاستجابة الحية مع مواصفات OpenAPI. إذا كانت المواصفات تقول إن email مطلوب وتوقفت API عن إرجاعه، فهذا انتهاك للعقد. راجع اختبار عقد API.

قاعدة عملية: أكّد على ما سيكسر العميل، وليس على كل ما يظهر في الحمولة اليوم. مثلًا، createdAt يتغير مع كل طلب، لذلك تحقق من النوع والتنسيق، لا من القيمة الحرفية.

مثال خط أساس بسيط:

GET /v1/users/42  ->  200
  body.id            is present, type number
  body.email         is present, type string, matches email format
  body.status        is one of ["active", "pending", "suspended"]
  body.roles         type array
  response time      < 800 ms
Enter fullscreen mode Exit fullscreen mode

هذه التأكيدات تصف العقد. إذا فشل أحدها بعد تغيير، فهناك تراجع يجب فحصه. لمزيد من التفاصيل حول فحص body، راجع تأكيدات API.

اختبار الانحدار اليدوي مقابل الآلي

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

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

الاختبار الآلي يزيل هذا القرار من العملية. تحفظ المجموعة مرة واحدة، ثم تعمل مع:

  • كل push
  • كل pull request
  • كل deploy
يدوي آلي
يعمل مع كل تغيير لا، يعتمد على الانضباط نعم، افتراضيًا
التغطية عدد قليل من نقاط النهاية المجموعة كاملة
التكلفة لكل تشغيل دقائق من وقت الإنسان ثوانٍ من الحوسبة
يكتشف الأعطال في الثانية صباحًا لا نعم
الجهد الأولي منخفض متوسط

لأي مشروع يتجاوز تجربة صغيرة، قم بأتمتة اختبارات الانحدار.

بناء مجموعة انحدار قابلة لإعادة الاستخدام

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

1. اجمع الاختبارات حسب المورد

لا تجمعها حسب الميزة. اجعل اختبارات /users في مجموعة، و/orders في مجموعة أخرى. عندما تتغير خدمة المستخدمين، تعرف مباشرة أي مجموعة تراقب.

2. استخدم متغيرات البيئة

لا تضع هذه القيم داخل كل طلب:

  • Base URL
  • رموز المصادقة
  • tenant IDs
  • مفاتيح الاختبار

ضعها في بيئات منفصلة:

local
staging
production
Enter fullscreen mode Exit fullscreen mode

بهذا تعمل المجموعة نفسها على أكثر من بيئة بتغيير إعداد واحد.

3. سلسل الطلبات المعتمدة على بعضها

التدفق الواقعي غالبًا يكون:

Create -> Read -> Update -> Delete
Enter fullscreen mode Exit fullscreen mode

استخرج id من استجابة الإنشاء ومرره إلى الطلب التالي. هذا يكشف انحدارات لا تظهر في اختبار كل طلب بشكل منفصل. هنا يتقاطع اختبار الانحدار مع اختبار التكامل API.

4. استخدم بيانات لاختبار حالات الحافة

بدلًا من تكرار عشرة طلبات متشابهة، اكتب طلبًا واحدًا ومرر له جدول بيانات.

مثال CSV لاختبار تحقق البريد الإلكتروني:

email,expectedStatus
alice@example.com,201
bob@test.co,201
not-an-email,422
,422
a@b,422
Enter fullscreen mode Exit fullscreen mode

طلب واحد، خمس حالات، وخمس تأكيدات على رمز الحالة. عندما تكتشف حالة حافة جديدة، أضف صفًا بدل كتابة اختبار جديد.

5. اجعل المجموعة سريعة

إذا استغرقت المجموعة 20 دقيقة، سيبدأ الفريق في تجاوزها. لتقليل الزمن:

  • شغّل الطلبات المستقلة بالتوازي إذا كانت الأداة تدعم ذلك
  • استخدم mocks للتبعيات الخارجية البطيئة
  • احتفظ بالتدفقات الشاملة الطويلة لتشغيل ليلي
  • اجعل مجموعة pull request صغيرة وسريعة

تشغيل المجموعة مع كل تغيير في CI

مجموعة الانحدار على جهازك تحمي جهازك فقط. القيمة الحقيقية تظهر عندما تعمل في CI مع كل pull request وكل merge إلى الفرع الرئيسي.

النمط العام:

  1. ثبّت runner بدون واجهة رسومية.
  2. وجّهه إلى المجموعة المحفوظة.
  3. شغّله ضد بيئة محددة.
  4. أفشل البناء إذا فشل أي تأكيد.

يوفر Apidog أداة CLI لهذا الغرض. ثبّتها عبر Node:

npm install -g apidog-cli
Enter fullscreen mode Exit fullscreen mode

ثم شغّل سيناريو أو مجموعة محفوظة:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t 123456 \
  -e 789012 \
  -r cli,html,junit
Enter fullscreen mode Exit fullscreen mode

شرح الخيارات:

  • --access-token: يصادق التشغيل. خزّنه كـ CI secret ولا تضعه في المستودع.
  • -t: معرف السيناريو أو المجلد أو المجموعة المراد تشغيلها.
  • -e: معرف البيئة، مثل staging أو production.
  • -r: تنسيقات التقارير:
    • cli للطباعة في الطرفية
    • html لتقرير قابل للقراءة
    • junit لتقرير XML يمكن لـ CI قراءته

مثال GitHub Actions لتشغيل المجموعة مع كل pull request:

name: API Regression

on: [pull_request]

jobs:
  regression:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v6

      - uses: actions/setup-node@v6
        with:
          node-version: '22'

      - run: npm install -g apidog-cli

      - run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t 123456 \
            -e 789012 \
            -r cli,junit
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
Enter fullscreen mode Exit fullscreen mode

عند فشل سيناريو، يخرج runner بقيمة غير صفرية وتفشل المهمة. هكذا يتم حظر pull request حتى يراجع الفريق المشكلة.

لأمثلة أوسع، راجع Apidog CLI لـ CI/CD وكيفية أتمتة اختبارات API في GitHub Actions.

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

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t 123456 \
  -e 789012 \
  -d ./test-data/emails.csv \
  -r cli,junit
Enter fullscreen mode Exit fullscreen mode

إذا كنت تختبر فرع ميزة له إصدار API خاص، استخدم:

--branch
Enter fullscreen mode Exit fullscreen mode

ولرفع سجل التشغيل إلى السحابة، أضف:

--upload-report
Enter fullscreen mode Exit fullscreen mode

مقارنة المخطط والعقد

التأكيدات تلتقط الانحدارات في السلوك. مقارنة المخطط تلتقط الانحدارات في التعريف قبل النشر أحيانًا.

الفكرة:

  • مواصفات OpenAPI موجودة في المستودع.
  • عند تعديلها، تتم مقارنة النسخة الجديدة بالسابقة.
  • يتم تصنيف التغييرات إلى آمنة أو كاسرة.

أمثلة على تغييرات غالبًا آمنة:

  • إضافة حقل اختياري
  • توسيع enum بطريقة متوافقة
  • إضافة endpoint جديد

أمثلة على تغييرات كاسرة:

  • حذف حقل
  • إعادة تسمية حقل
  • جعل حقل اختياري إلزاميًا
  • تضييق نوع من string إلى enum محدود
  • تغيير شكل object إلى array

هذا يجعل المراجع يرى رسالة مثل:

Breaking change: removed user.phone
Enter fullscreen mode Exit fullscreen mode

بدل البحث في ملف YAML طويل.

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

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

كيف يشغّل Apidog مجموعات الانحدار؟

يجمع Apidog الأجزاء الأساسية في مكان واحد:

  • تصميم API
  • السيناريوهات
  • التأكيدات
  • البيئات
  • مجموعات البيانات
  • تشغيل CI عبر CLI

يمكنك بناء سيناريوهات الاختبار بصريًا:

  1. أضف الطلبات.
  2. رتّبها كتسلسل.
  3. استخرج قيمة من استجابة لاستخدامها في طلب لاحق.
  4. أضف تأكيدات على:
    • رمز الحالة
    • مخطط الاستجابة
    • قيم الحقول
    • زمن الاستجابة

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

للحالات المعتمدة على البيانات، أرفق ملف CSV أو JSON بسيناريو، ويشغّل Apidog حالة لكل صف. بعد ذلك، احفظ السيناريوهات في مجموعة اختبار لتشغيل مورد أو تدفق كامل بأمر واحد.

apidog-cli ينقل هذه المجموعات إلى CI بدون واجهة رسومية. وظيفته محددة: إعادة تشغيل مجموعة الانحدار والإبلاغ عن النتائج. ليس مولد تحميل ولا عميل طلبات تفاعلي. لهذا يمكن إدخاله بسهولة في أي CI قادر على تشغيل Node.

للمزيد، راجع دليل مسار عمل Apidog CLI CI/CD.

سير عمل عملي للبدء

يمكنك تطبيق هذا خلال أسبوع دون إعادة بناء استراتيجية الاختبار بالكامل.

  1. اختر أكثر خمس نقاط نهاية استخدامًا

    ابدأ حيث تتركز حركة المرور والمخاطر.

  2. احفظ طلبًا لكل نقطة نهاية

    أضف تأكيدات على:

    • رمز الحالة
    • مخطط الاستجابة
    • حقلين أو ثلاثة حقول رئيسية

  3. أضف تدفقًا متسلسلًا واحدًا

    مثل:

   Create -> Read -> Update -> Delete
Enter fullscreen mode Exit fullscreen mode

  1. أضف جدول بيانات لنقطة نهاية كثيرة التحقق

    استخدم حالات صالحة، فارغة، وحدّية، وخاطئة.

  2. اربط المجموعة بـ CI

    ثبّت apidog-cli، شغّل المجموعة مع -r junit، وافشل pull request عند فشل الاختبارات.

  3. وسّع المجموعة عند هروب خطأ

    كل انحدار يصل للإنتاج يجب أن يتحول إلى حالة اختبار جديدة.

النتيجة: إعادة تسمية حقل كانت ستصبح حادثًا إنتاجيًا تتحول إلى فشل واضح في pull request.

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

كيف يختلف اختبار الانحدار لواجهة API عن اختبار الانحدار العام؟

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

كم مرة يجب تشغيل مجموعة الانحدار؟

شغّلها مع كل تغيير يمكن أن يؤثر على API. عمليًا: كل pull request وكل merge إلى الفرع الرئيسي. استخدم مجموعة أساسية سريعة لطلبات السحب، ومجموعة أوسع للتشغيل الليلي.

ما الذي يجب التأكيد عليه لتجنب الاختبارات الهشة؟

أكّد على ما سيكسر المستهلك: رموز الحالة، بنية الاستجابة، أنواع الحقول، والقيم التعاقدية مثل المعرفات وتعدادات الحالة. بالنسبة للقيم المتغيرة مثل الطوابع الزمنية، تحقق من النوع والتنسيق بدل القيمة.

هل يمكن تشغيل اختبارات الانحدار بدون كتابة كود؟

نعم. يمكن بناء السيناريوهات والتأكيدات بصريًا في أدوات مثل Apidog، ثم تشغيلها في CI باستخدام apidog-cli. تحفظ المجموعة مرة واحدة ويعيد runner تشغيلها تلقائيًا.

كيف أتعامل مع تغييرات كاسرة مقصودة؟

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

Top comments (0)