كيف تشغل اختبارات الـ API المؤتمتة في TeamCity؟

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

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

يرشدك هذا الدليل خلال تشغيل اختبارات واجهة برمجة التطبيقات (API) الآلية داخل TeamCity من البداية إلى النهاية. ستقوم بتصميم اختباراتك والتحقق منها في Apidog، ثم تشغيلها بدون واجهة رسومية عبر واجهة سطر الأوامر (CLI) الخاصة بـ Apidog كخطوة بناء في TeamCity. والنتيجة هي مسار عمل يفشل البناء في اللحظة التي تتوقف فيها واجهة برمجة التطبيقات (API) عن العمل بشكل صحيح، قبل أن يصل استجابة سيئة إلى المستخدم.

ما ستبنيه

بحلول النهاية ستحصل على:

• مشروع TeamCity متصل بمستودع Git الخاص بك
• إعداد بناء مع مشغل VCS يتم تشغيله عند كل عملية دفع
• خطوة بناء تشغل مجموعة اختبارات واجهة برمجة التطبيقات (API) الخاصة بك عبر واجهة سطر الأوامر (CLI) الخاصة بـ Apidog
• نتائج اختبارات محللة مرئية في علامة التبويب "الاختبارات" في TeamCity
• بناء يتحول إلى اللون الأحمر ويمنع الدمج عند تعطل نقطة نهاية

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

لماذا تنتمي اختبارات واجهة برمجة التطبيقات (API) إلى TeamCity، وليس فقط إلى جهازك

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

يعد TeamCity مناسبًا لذلك لعدة أسباب محددة:

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

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

الخطوة 1: تصميم اختبارات واجهة برمجة التطبيقات (API) والتحقق منها في Apidog

قبل أن يلمس أي شيء TeamCity، تحتاج إلى اختبارات تعمل بالفعل دون تدخل بشري. الاختبار الذي يتطلب منك تفحص استجابة JSON يدويًا لا قيمة له في التكامل المستمر (CI). يجب أن يكون كل فحص تأكيدًا يمكن للآلة تقييمه: رمز الحالة هو 200، حقل id هو رقم، الاستجابة عادت في أقل من 800 مللي ثانية.

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

قد يبدو سيناريو واقعي لواجهة برمجة تطبيقات للتجارة الإلكترونية كما يلي:

1. POST /auth/login ببيانات اعتماد الاختبار، تأكيد 200، استخراج رمز الموفّر (bearer token) إلى متغير.
2. GET /products?category=books باستخدام هذا الرمز، تأكيد 200، تأكيد أن الاستجابة مصفوفة، تأكيد أن كل عنصر لديه price أكبر من 0.
3. POST /cart/items بمعرف المنتج، تأكيد 201، تأكيد أن إجمالي سلة التسوق المعادة يطابق سعر العنصر.
4. GET /cart، تأكيد أن عدد العناصر هو 1.

تحتوي كل خطوة على تأكيدات تمر أو تفشل بمفردها. قم بتشغيل السيناريو داخل Apidog أولاً وتأكد من أنه يمر بنجاح (يتحول إلى اللون الأخضر) مقابل بيئة الاختبار الخاصة بك (staging environment). إذا لم يتمكن من المرور عند تشغيله يدويًا، فلن يمر أبدًا في التكامل المستمر (CI). اجمع السيناريوهات ذات الصلة في مجموعة اختبارات حتى تتمكن من تشغيل كل شيء بأمر واحد بدلاً من سيناريو تلو الآخر.

ميزة بناء الاختبارات بهذه الطريقة هي أن نفس السيناريوهات التي تستخدمها لتصحيح الأخطاء يدويًا تصبح مجموعة اختبارات التكامل المستمر (CI) الخاصة بك. لا تحتفظ بمجموعتين متوازيتين من الاختبارات؛ واحدة في واجهة المستخدم الرسومية للاستكشاف، وواحدة في الكود للأتمتة. إنه مصدر واحد للحقيقة. إذا كنت قادمًا من إطار عمل يعتمد على الكود أولاً مثل REST Assured، فهذا هو الجزء الذي يوفر معظم الوقت: تتوقف عن كتابة وإعادة كتابة كود الطلب/التأكيد المتكرر لكل نقطة نهاية.

قم بتنزيل Apidog إذا كنت ترغب في المتابعة. البدء مجاني، وواجهة سطر الأوامر (CLI) جزء من نفس مجموعة الأدوات.

الخطوة 2: تشغيل واجهة سطر الأوامر (CLI) الخاصة بـ Apidog محليًا أولاً

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

npm install -g apidog-cli

تأكد من وجوده:

apidog --version

الآن قم بتشغيل سيناريو الاختبار الخاص بك. يمكن لواجهة سطر الأوامر (CLI) تشغيل سيناريو أو مجموعة مباشرة من مشروع Apidog الخاص بك عن طريق الإشارة إلى معرّفه (ID)، والمصادقة باستخدام رمز وصول (access token)، أو من ملف محلي تم تصديره. يحافظ النهج عبر الإنترنت على اختباراتك كمصدر وحيد للحقيقة؛ فما يعدله فريقك في Apidog هو ما يتم تشغيله في CI، بدون خطوة تصدير يمكن نسيانها.

قم بإنشاء رمز وصول (access token) من إعدادات حساب Apidog الخاص بك، ثم قم بالتشغيل:

apidog run \
 --access-token "$APIDOG_ACCESS_TOKEN" \
 -e "$APIDOG_ENV_ID" \
 -r cli,html,junit

بضع ملاحظات هنا:

• --access-token يقوم بمصادقة التشغيل. مرره بشكل مباشر هكذا، أو قم بتسجيل الدخول مرة واحدة باستخدام apidog login --with-token.
• يحدد -e البيئة التي سيتم التشغيل عليها؛ بيئة الاختبار (staging)، أو بيئة الإنتاج للقراءة فقط (production-readonly)، أو أي شيء قمت بتعريفه في Apidog. يمكنك توجيه نفس الاختبارات إلى عناوين URL أساسية مختلفة عن طريق تبديل هذا المعرّف.
• يختار -r أدوات الإبلاغ. يطبع cli مخرجات قابلة للقراءة البشرية إلى وحدة التحكم، وينتج html تقريرًا يمكنك تصفحه، وتقرير بتنسيق JUnit هو ما يسمح لـ TeamCity بتحليل وعرض نتائج الاختبارات الفردية.

عند انتهاء التشغيل، تخرج واجهة سطر الأوامر (CLI) بالرمز 0 إذا مر كل شيء، وبقيمة غير صفرية إذا فشل أي تأكيد. رمز الخروج هذا هو اللعبة بأكملها في CI: الخروج بقيمة غير صفرية هو ما يخبر TeamCity بوضع علامة "فشل" على عملية البناء.

بالنسبة للاختبارات التي تحتاج إلى التشغيل عبر العديد من المدخلات، تدعم واجهة سطر الأوامر (CLI) عمليات التشغيل المعتمدة على البيانات. وجهها إلى ملف CSV أو JSON وتكرر السيناريو مرة واحدة لكل صف:

apidog run \
 --access-token "$APIDOG_ACCESS_TOKEN" \
 -d test-data/checkout-cases.csv \
 -r cli,junit

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

بمجرد رؤيتك لمخرجات خضراء محليًا، يكون لديك أمر تثق به. انسخه. هذا الأمر بالضبط هو ما سيتم وضعه في TeamCity.

الخطوة 3: ربط TeamCity بمستودعك

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

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

docker run -d --name teamcity-server \
 -v ~/teamcity/datadir:/data/teamcity_server/datadir \
 -v ~/teamcity/logs:/opt/teamcity/logs \
 -p 8111:8111 \
 jetbrains/teamcity-server

افتح http://localhost:8111، أكمل إعداد التشغيل الأول (اختيار قاعدة البيانات، حساب المسؤول)، وستهبط على لوحة التحكم. تستخدم إعدادات الإنتاج قاعدة بيانات خارجية مناسبة ووكلاء بناء مخصصين، ولكن لاتباع هذا الدليل يكفي الوكيل المضمّن.

إنشاء المشروع:

1. اذهب إلى "الإدارة" (Administration) واختر "إنشاء مشروع" (Create project).
2. اختر "من عنوان URL لمستودع" (From a repository URL) والصق رابط Git البعيد الخاص بك (HTTPS أو SSH).
3. أضف بيانات الاعتماد إذا كان المستودع خاصًا؛ مفتاح نشر (deploy key) أو رمز وصول شخصي (personal access token).
4. يقوم TeamCity بمسح المستودع ويجب أن يكتشف خطوات البناء تلقائيًا. يمكنك تركه يفعل ذلك، ولكن لاختبارات واجهة برمجة التطبيقات (API) من الأفضل تكوين الخطوة بنفسك في القسم التالي.

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

1. افتح إعداد البناء الخاص بك وانتقل إلى "المشغلات" (Triggers).
2. أضف "مشغل VCS" (VCS Trigger).
3. اترك القاعدة الافتراضية بحيث تؤدي كل تغيير في الفرع المراقب إلى قائمة انتظار بناء.

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

الخطوة 4: إضافة واجهة سطر الأوامر (CLI) الخاصة بـ Apidog كخطوة بناء

هذا هو جوهر الإعداد. أنت تضيف خطوة بناء تقوم بتثبيت واجهة سطر الأوامر (CLI) على الوكيل وتشغيل مجموعتك.

في إعداد البناء الخاص بك، افتح "خطوات البناء" (Build Steps) وأضف خطوة جديدة من نوع "سطر الأوامر" (Command Line). اختر "برنامج نصي مخصص" (Custom script) والصق:

#!/bin/bash
set -e

# تثبيت واجهة سطر الأوامر (CLI) لـ Apidog على وكيل البناء
npm install -g apidog-cli

# تشغيل مجموعة اختبارات واجهة برمجة التطبيقات (API) وإصدار تقرير JUnit لـ TeamCity
apidog run \
 --access-token "%env.APIDOG_ACCESS_TOKEN%" \
 -e "%env.APIDOG_ENV_ID%" \
 -r cli,junit \
 --out-dir reports

هذا هو نفس الأمر الذي أثبت صحته محليًا، مع تغييرين للتكامل المستمر (CI). أولاً، يجعل set -e السكريبت يتوقف عند أي خطأ. ثانيًا، يتم الإشارة إلى الأسرار كمعاملات TeamCity (%env.APIDOG_ACCESS_TOKEN%) بدلاً من أن تكون مكتوبة يدويًا؛ ستقوم بتعريفها لاحقًا.

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

تفصيل واحد يستحق الاهتمام: يجب أن تعمل واجهة سطر الأوامر (CLI) بعد نشر واجهة برمجة التطبيقات (API) الخاصة بك وإتاحتها. إذا كان TeamCity يختبر خدمة تم نشرها للتو في بيئة الاختبار (staging)، فاجعل بناء الاختبار يعتمد على بناء النشر باستخدام تبعية لقطة (Snapshot Dependency) أو سلسلة بناء (Build Chain). يضمن ذلك أن الاختبارات تستهدف دائمًا إصدار واجهة برمجة التطبيقات (API) الذي أنتجه هذا الالتزام (commit)، وليس الإصدار السابق أبدًا.

الخطوة 5: تخزين الأسرار كمعاملات TeamCity

رمز الوصول الخاص بك هو بيانات اعتماد. لا ينتمي إلى سكريبت البناء، أو إلى مستودعك، أو إلى سجل البناء. لدى TeamCity مكان مخصص لهذا الغرض.

1. في إعداد البناء الخاص بك (أو المشروع الأصلي، للمشاركة عبر الإعدادات)، افتح "المعاملات" (Parameters).
2. أضف معلمة جديدة باسم env.APIDOG_ACCESS_TOKEN.
3. عيّن مواصفاتها (Spec) إلى "كلمة مرور" (Password). هذا يخفي القيمة في واجهة المستخدم ويزيلها من سجلات البناء.
4. الصق رمز الوصول الخاص بـ Apidog كقيمة.
5. أضف env.APIDOG_ENV_ID بنفس الطريقة مع معرف بيئتك (هذا ليس سرًا، ولكن الاحتفاظ به كمعلمة يتيح لك تغيير البيئات دون تعديل السكريبت).

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

معامل كلمة المرور هو الفرق بين رمز مميز يعيش بأمان في TeamCity ورمز يتسرب إلى ملف سجل يمكن للفريق بأكمله قراءته. تعامل معه بنفس الطريقة التي ستتعامل بها مع كلمة مرور قاعدة بيانات.

الخطوة 6: عرض نتائج الاختبار في علامة التبويب "الاختبارات" في TeamCity

البناء الذي يتحول إلى اللون الأحمر فقط يخبرك أن شيئًا ما تعطل. البناء الذي يظهر أي اختبار تعطل يخبرك أين تبحث. هذا ما يوفره لك تقرير JUnit.

يقوم أداة الإبلاغ -r junit بكتابة ملف XML بتنسيق JUnit، وهو تنسيق نتائج اختبارات CI القياسي الذي يقرأه TeamCity بشكل أصلي. يمكنك توجيه TeamCity إلى هذا الملف باستخدام ميزة بناء "معالجة تقارير XML" (XML Report Processing).

1. افتح "ميزات البناء" (Build Features) في إعداد البناء الخاص بك.
2. أضف "معالجة تقارير XML" (XML report processing).
3. عيّن نوع التقرير إلى "Ant JUnit".
4. عيّن مسار المراقبة (monitoring path) ليتطابق مع مخرجاتك، على سبيل المثال reports/*.xml.

قم بتشغيل بناء. افتحه وانقر على علامة التبويب "الاختبارات" (Tests). سترى كل سيناريو وتأكيد كاختبار فردي مع حالة نجاح/فشل وتوقيت. عندما يفشل اختبار، يعرض TeamCity رسالة الفشل مباشرة، ويربطها بالالتزام (commit) الذي أدخلها، ويتتبعها عبر عمليات البناء المستقبلية. إذا فشل نفس الاختبار مرتين متتاليتين، يمكن لـ TeamCity وضع علامة عليه كفشل جديد بدلاً من فشل متقلب.

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

الخطوة 7: إفشال البناء وحظر الدمج

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

أولاً، رمز الخروج. نظرًا لأن واجهة سطر الأوامر (CLI) الخاصة بـ Apidog تخرج بقيمة غير صفرية عند أي تأكيد فاشل ويستخدم السكريبت الخاص بك set -e، فإن الاختبار الفاشل يفشل خطوة البناء، مما يفشل البناء. ليس عليك تكوين أي شيء إضافي؛ اختبار واجهة برمجة تطبيقات (API) أحمر يعني بناءً أحمر بشكل افتراضي.

ثانيًا، بوابة الدمج. إذا كان فريقك يعمل بطلبات السحب (pull requests) أو طلبات الدمج (merge requests)، فقم بتكوين مضيف Git الخاص بك (GitHub، GitLab، Bitbucket) لطلب اجتياز فحص TeamCity قبل الدمج. يقوم TeamCity بالإبلاغ عن حالة البناء الخاصة به مرة أخرى إلى الالتزام (commit) عبر ميزة بناء "ناشر حالة الالتزام" (Commit Status Publisher):

1. أضف ميزة البناء "ناشر حالة الالتزام" (Commit Status Publisher).
2. اختر مزود استضافة VCS الخاص بك.
3. أضف رمز وصول (access token) حتى يتمكن TeamCity من نشر الحالات.

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

مسار عمل كامل وواقعي

بجمع الأجزاء معًا، يبدو إعداد البناء العامل لمسار عمل اختبار واجهة برمجة التطبيقات (API) كما يلي:

• جذر VCS يشير إلى مستودعك، مع مشغل VCS على الفرع الرئيسي وفروع طلبات السحب (PR branches).
• خطوة البناء 1: نشر الخدمة إلى بيئة اختبار (staging environment) (أو تشغيلها في حاوية Docker على الوكيل).
• خطوة البناء 2: أمر واجهة سطر الأوامر (CLI) الخاصة بـ Apidog من الخطوة 4، وتشغيل مجموعتك مقابل بيئة الاختبار هذه.
• ميزات البناء: معالجة تقارير XML تقرأ reports/*.xml.
• ميزات البناء: ناشر حالة الالتزام (Commit Status Publisher) يبلغ مضيف Git الخاص بك.
• المعاملات: env.APIDOG_ACCESS_TOKEN (كلمة مرور) و env.APIDOG_ENV_ID.

بالنسبة للفرق التي تحتفظ بتكوين CI الكامل الخاص بها في نظام التحكم بالإصدار (version control)، يدعم TeamCity تعريف كل هذا في لغة Kotlin DSL (.teamcity/settings.kts) الملتزم بها في المستودع، بدلاً من النقر عبر واجهة المستخدم. خطوة البناء هي نفس الأمر apidog run في كلتا الحالتين؛ تصف DSL التكوين ككود بحيث تتم مراجعته ووضع إصدار له جنبًا إلى جنب مع كل شيء آخر.

يمكنك تشغيل المجموعة ليس فقط عند كل عملية دفع. أضف "مشغل جدول زمني" (Schedule Trigger) لتشغيل مجموعة اختبارات الانحدار (regression suite) الكاملة كل ليلة مقابل بيئة الاختبار (staging)، بحيث تكتشف الانحراف الذي يحدث بين الالتزامات (commits)؛ مثل تبعية طرف ثالث تغيرت، أو قاعدة بيانات دخلت في حالة غريبة. تشغيل اختبارات واجهة برمجة التطبيقات (API) الليلية هو تأمين رخيص ويمنع أول التزام في الصباح من وراثة بيئة الأمس المعطلة.

كيف يقارن هذا بمنصات CI الأخرى

النمط هنا قابل للنقل. الأمر الذي يشغل اختباراتك (apidog run مع رمز وصول ومُبلِّغ JUnit) متطابق بغض النظر عن خادم CI الذي يستدعيه. يتغير الغلاف فقط:

• في GitHub Actions، ستضع نفس الأمر في خطوة YAML لسير العمل. نغطي ذلك في كيفية أتمتة اختبارات API في GitHub Actions.
• في Jenkins، يذهب في مرحلة Jenkinsfile. انظر كيفية دمج اختبارات Apidog المؤتمتة مع Jenkins للتكامل المستمر/النشر المستمر (CI/CD).
• توجد الاستراتيجية الأوسع عبر أي منصة في كيفية أتمتة اختبارات API في التكامل المستمر/النشر المستمر (CI/CD).

إذا كنت لا تزال تختار خادم CI، فإن مقارنتنا لأفضل أدوات CI/CD توضح موقع TeamCity مقابل البدائل. نقاط قوة TeamCity هي سلاسل البناء، وسجل الاختبارات المفصل، ولغة Kotlin DSL؛ إنه اختيار قوي للفرق الموجودة بالفعل في نظام JetBrains البيئي أو التي تدير مسارات عمل معقدة متعددة المراحل.

المشكلات الشائعة وكيفية إصلاحها

• لا يمكن للبناء العثور على الأمر apidog. Node.js غير مثبت على الوكيل، أو دليل npm bin العام ليس في PATH الخاص بالوكيل. أضف خطوة تثبيت Node في وقت سابق من السلسلة، أو قم بتشغيل الخطوة داخل صورة Docker مثل node:20.
• الاختبارات تمر محليًا ولكن تفشل في CI بأخطاء اتصال. لا يمكن لوكيل البناء الوصول إلى واجهة برمجة التطبيقات (API) الخاصة بك. قد لا يمكن الوصول إلى عنوان URL لبيئة الاختبار (staging URL) الذي يعمل على شبكة VPN الخاصة بجهاز الكمبيوتر المحمول الخاص بك من وكيل سحابي. تأكد من أن البيئة التي تختارها باستخدام -e تشير إلى مضيف يمكن للوكيل الوصول إليه بالفعل، وأن أي قواعد وصول للشبكة أو جدران الحماية المطلوبة تغطي الوكيل.
• تفشل المصادقة فقط في CI. تحقق من أن معامل كلمة المرور مكتوب بالضبط كما يشير إليه السكريبت وأن الرمز المميز لم ينتهِ. خطأ شائع هو تعريف APIDOG_ACCESS_TOKEN بينما يقرأ السكريبت %env.APIDOG_ACCESS_TOKEN%؛ بادئة env. مهمة.
• الاختبارات متقلبة؛ تنجح وتفشل على نفس الكود. عادة ما تكون مشكلة توقيت أو ترتيب بيانات. استخدم تأكيدات وقت الاستجابة في Apidog لإظهار نقاط النهاية البطيئة، واجعل كل سيناريو يقوم بإعداد وتفكيك بياناته الخاصة حتى لا تعتمد عمليات التشغيل على بقايا بعضها البعض. تتيح لك ميزة كتم الصوت والتحقيق في TeamCity عزل اختبار متقلب حتى يتوقف عن حظر الجميع بينما تقوم بإصلاح السبب الجذري.
• علامة التبويب "الاختبارات" فارغة على الرغم من تشغيل البناء. مسار معالجة تقارير XML لا يتطابق مع المكان الذي كتبت فيه واجهة سطر الأوامر (CLI) التقرير. تأكد من أن --out-dir في الأمر ومسار المراقبة في ميزة البناء يشيران إلى نفس المكان.

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

• هل أحتاج إلى كتابة كود لتشغيل اختبارات API في TeamCity؟ لا. تقوم بتصميم الاختبارات بصريًا في Apidog باستخدام التأكيدات، و"الكود" الوحيد في TeamCity هو أمر apidog run ذو السطر الواحد في خطوة بناء سطر الأوامر. هذا هو الفرق الرئيسي عن النهج الذي يعتمد على الكود أولاً مثل REST Assured، حيث تحتاج كل نقطة نهاية إلى كود طلب وتأكيد مكتوب يدويًا.
• هل يمكنني تشغيل الاختبارات مقابل بيئات مختلفة؟ نعم. قم بتعريف كل بيئة (staging، pre-prod، production-readonly) في Apidog، ثم قم بتبديل البيئة التي تعمل في CI عن طريق تغيير معلمة معرف البيئة -e. تعمل نفس الاختبارات مقابل أي بيئة عن طريق الإشارة إلى عنوان URL أساسي مختلف.
• كيف أحافظ على أمان رمز الوصول الخاص بي في TeamCity؟ قم بتخزينه كمعلمة TeamCity ذات مواصفات "كلمة مرور" (Password). هذا يخفيه في واجهة المستخدم ويزيله من سجلات البناء. لا تقم أبدًا بتضمينه مباشرة في سكريبت البناء أو الالتزام به في مستودعك. قم بتعريفه على مستوى المشروع حتى تتمكن من تدويره مرة واحدة لجميع مسارات العمل.
• هل سيؤدي اختبار API الفاشل بالفعل إلى حظر الدمج؟ نعم، بوجود قطعتين في مكانهما. يخرج واجهة سطر الأوامر (CLI) الخاصة بـ Apidog بقيمة غير صفرية عند أي تأكيد فاشل، مما يؤدي إلى فشل بناء TeamCity. أضف ميزة بناء "ناشر حالة الالتزام" (Commit Status Publisher) واطلب الفحص في قواعد حماية الفرع الخاصة بمضيف Git الخاص بك، وسيظل زر الدمج معطلاً حتى تمر المجموعة.
• ما الفرق بين تشغيل الاختبارات عبر الإنترنت مقابل ملف تم تصديره؟ تشغيل الاختبارات عبر الإنترنت باستخدام معرف المشروع ورمز الوصول يعني أن اختباراتك في Apidog هي مصدر الحقيقة الوحيد؛ فما يعدله الفريق هو ما يتم تشغيله في CI. تشغيلها من ملف تم تصديره يربط الاختبارات بإصدار ملتزم به في مستودعك. التشغيل عبر الإنترنت أبسط للحفاظ على التزامن؛ بينما يوفر لك الملف المصدر اختبارات تنتقل مع الكود. تبدأ معظم الفرق بالتشغيل عبر الإنترنت.
• هل يمكنني تشغيل مجموعة اختبارات الانحدار الكاملة (full regression suite) على جدول زمني بدلاً من كل عملية دفع؟ نعم. أضف "مشغل جدول زمني" (Schedule Trigger) إلى إعداد البناء للتشغيل ليلاً (أو كل ساعة) مقابل بيئة الاختبار (staging). تشغل العديد من الفرق مجموعة اختبارات سريعة (smoke suite) عند كل عملية دفع ومجموعة اختبارات الانحدار الكاملة على جدول زمني ليلي، بحيث لا يتنافس التغذية الراجعة السريعة والتغطية العميقة على نفس الدقائق.

خلاصة

مسار عمل TeamCity الذي يقوم بتشغيل اختبارات واجهة برمجة التطبيقات (API) الخاصة بك في كل التزام (commit) يغير اقتصاديات نقطة نهاية معطلة. بدلاً من أن يجد العميل الخطأ، يجده البناء؛ على الفرع، قبل الدمج، مع التأكيد الفاشل بالضبط والالتزام الذي تسبب فيه، كل ذلك معروض في علامة التبويب "الاختبارات".

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

قم بتنزيل Apidog لتصميم أول مجموعة اختبارات لك، وأثبت صحة أمر واجهة سطر الأوامر (CLI) محليًا، ثم ضعه في TeamCity. من تلك النقطة فصاعدًا، يتم اختبار واجهة برمجة التطبيقات (API) الخاصة بك بنفس الطريقة في كل التزام، سواء تذكر أحد تشغيلها أم لا.