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

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

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

ما هو اختبار الانحدار لواجهة برمجة التطبيقات (ولماذا تتراجع واجهات برمجة التطبيقات)

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

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

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

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

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

حدد هذه الطبقات الأربع كخط أساس:

1. رموز الحالة. يجب أن تُرجع كل نقطة نهاية حالة معروفة للمدخلات المعروفة. رمز 200 الذي يصبح 500، أو 201 الذي يصبح 200، هو تراجع حتى لو بدا النص الأساسي سليمًا.
2. مخطط الاستجابة. هيكل وأنواع الاستجابة. أسماء الحقول، التداخل، وما إذا كانت القيمة سلسلة نصية أو رقمًا أو مصفوفة أو كائنًا. انحراف المخطط هو الأكثر شيوعًا كخطأ صامت.
3. قيم الحقول الرئيسية. ليست كل قيمة، بل تلك التي لها معنى تعاقدي: id يجب أن يكون موجودًا، تعداد status يجب أن يبقى ضمن مجموعة معروفة، total يجب أن يكون رقمًا.
4. العقود. العلاقة بين مواصفات OpenAPI الخاصة بك والاستجابة الحية. إذا كانت المواصفات تقول إن email مطلوب وتوقفت واجهة برمجة التطبيقات عن إعادته، فهذا انتهاك للعقد. انظر اختبار عقد 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

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

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

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

يزيل اختبار الانحدار الآلي العنصر البشري من العملية. تقوم بتسجيل المجموعة مرة واحدة، ثم تعيد الآلة تشغيلها مع كل دفع (push)، وكل طلب سحب (pull request)، وكل نشر (deploy). القيمة ليست السرعة في تشغيل واحد. بل هي أن المجموعة تعمل في كل مرة، دون أن يقرر أحد أنها تستحق الجهد.

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

لأي شيء يتجاوز مشروعًا صغيرًا، قم بأتمتته.

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

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

هيكل المجموعة بحيث تنجو من التغيير:

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

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

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

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

إليك كيف قد يبدو جدول البيانات لاختبار تحقق واحد بتنسيق CSV:

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

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

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

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

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

النمط هو نفسه عبر أنظمة التكامل المستمر. قم بتثبيت مشغل بدون واجهة مستخدم رسومية (headless runner)، وجهه إلى مجموعتك المحفوظة، وافشل البناء إذا فشل أي تأكيد. يوفر Apidog مشغل سطر أوامر لهذا الغرض بالضبط. قم بتثبيته باستخدام Node:

npm install -g apidog-cli

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

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

لنحلل ذلك:

• --access-token يقوم بمصادقة التشغيل. قم بتخزين الرمز كسر CI، وليس أبدًا في المستودع.
• -t هو معرف السيناريو، المجلد، أو المجموعة المراد تشغيلها.
• -e هو معرف البيئة، بحيث يمكن لنفس المجموعة استهداف بيئة التجريب أو الإنتاج عن طريق تغيير قيمة واحدة.
• -r يسرد تنسيقات التقارير. cli يطبع إلى وحدة التحكم، html ينتج تقريرًا قابلاً للقراءة، و junit يصدر XML يمكن لنظام التكامل المستمر الخاص بك تحليله لإظهار النجاح/الفشل لكل اختبار.

المشغل بدون واجهة مستخدم رسومية. يتناسب مع أي خطوة CI يمكنها تشغيل Node، لذا يعمل نفس الأمر في GitHub Actions، GitLab CI، Jenkins، أو CircleCI. إليك مهمة GitHub Actions التي تشغل المجموعة مع كل طلب سحب:

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 }}

عندما يفشل سيناريو، يخرج المشغل بقيمة غير صفرية ويتحول لون المهمة إلى الأحمر. يتم حظر طلب السحب حتى يقوم شخص ما بالنظر فيه. للحصول على مسار عمل كامل قابل للنسخ واللصق والمزيد من أنماط CI، انظر 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

هل تختبر فرع ميزة له إصدار API خاص به؟ أضف --branch للتشغيل مقابل مجموعة الفرع المحفوظة بدلاً من الافتراضية. للاحتفاظ بسجل للتشغيلات في السحابة، ألحق العلامة --upload-report المجردة.

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

تكتشف التأكيدات الانحدارات في السلوك. وتكتشف مقارنة المخطط (Schema diffing) الانحدارات في التعريف، غالبًا قبل النشر.

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

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

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

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

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

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

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

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

سير عمل للمبتدئين

فيما يلي تسلسل يمكنك اعتماده هذا الأسبوع دون إعادة بناء استراتيجية الاختبار الخاصة بك:

1. اختر نقاط النهاية الخمسة الأكثر استدعاءً لديك. يتركز خطر الانحدار حيث يتركز حركة المرور. ابدأ من هناك.
2. احفظ طلبًا لكل نقطة نهاية مع تأكيدات. رمز الحالة، مخطط الاستجابة، وحقلين أو ثلاثة حقول رئيسية لكل منها. هذا هو خط الأساس الخاص بك.
3. أضف تدفقًا متسلسلاً واحدًا. إنشاء، قراءة، تحديث، حذف على موردك الأساسي. هذا يكتشف انحدارات عبر الطلبات التي تفوتها الاختبارات المعزولة.
4. أضف جدول بيانات إلى نقطة نهاية واحدة ثقيلة التحقق. عدد قليل من المدخلات الصالحة والفارغة والسيئة.
5. اربطه بنظام التكامل المستمر (CI) عند طلبات السحب. قم بتثبيت apidog-cli، وشغل المجموعة باستخدام -r junit، وقم بحظر عمليات الدمج عند الفشل.
6. قم بتوسيع المجموعة عندما يفلت خطأ. كل انحدار إنتاجي يفلت يصبح حالة اختبار جديدة. تصبح المجموعة أقوى من أخطائها الخاصة.

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

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

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

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

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

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

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