يقوم وكيل Cascade من Windsurf بتشغيل حلقة: فهو يعدل الملفات، ويشغل أوامر الطرفية، ويقرأ المخرجات، ويقرر ما يجب فعله بعد ذلك. فلماذا لا توجد اختبارات API الخاصة بك في تلك الحلقة؟ إنها موجودة في Apidog خلف واجهة رسومية وتعمل عندما يتذكر أحدهم النقر عليها. لا يلمسها Cascade أبدًا.
الحل هو كتلة تكوين واحدة. واجهة سطر الأوامر (CLI) الخاصة بـ Apidog هي حزمة npm، apidog-cli، تقوم بتشغيل سيناريوهات الاختبار التي أنشأتها في Apidog مباشرة من الطرفية. بمجرد تثبيت CLI ومعرفة Cascade بوجودها، يقوم Windsurf بتشغيل سيناريو Apidog بنفس الطريقة التي يشغل بها اختبارات الوحدة الخاصة بك: قم بتشغيل الأمر، واقرأ رمز الخروج، وقم بإصلاح الكود إذا عاد أحمر.
زر
إذا لم تقم بتثبيت CLI بعد، فافعل ذلك أولاً. كيفية تثبيت Apidog CLI باستخدام وكيل ترميز بالذكاء الاصطناعي يشرح خطوات تثبيت npm، والمصادقة، والتشغيل الأول، مع قيام وكيل بعملية الكتابة. تفترض هذه المقالة أن apidog --version يطبع رقمًا وأن حسابك على Apidog مصادق عليه.
عن أي Windsurf نتحدث
Windsurf هو بيئة تطوير متكاملة (IDE) قائمة على الوكلاء من Codeium، ويُسمى وكيلها المدمج Cascade. يعمل Cascade محليًا، ويقرأ مستودعك، ويعدل الملفات، وينفذ أوامر shell في محطتك الطرفية المتكاملة، ويطلب الموافقة بناءً على إعداد التشغيل التلقائي لديك. هذا هو المحرر ووكيله، وليس امتدادًا للمتصفح أو مكونًا إضافيًا للإكمال التلقائي.
إذا لم تقم بإعداده بعد، فابدأ بـ كيفية تنزيل وتثبيت Windsurf. بمجرد فتح Cascade في مشروعك، يمكنك تعليمه حول Apidog CLI من خلال آلية القواعد الخاصة به، والتي تحول أمر “تشغيل اختباراتي” لمرة واحدة إلى شيء يصل إليه Cascade من تلقاء نفسه.
الخطوة 1: أضف قاعدة Apidog إلى .windsurf/rules
يقرأ Cascade قواعد المشروع من ملفات Markdown قبل أن يبدأ العمل. ضعها في دليل .windsurf/rules/ في جذر مستودعك، قاعدة واحدة لكل ملف. لا يزال Windsurf يقرأ ملفًا واحدًا قديمًا .windsurfrules في جذر مساحة العمل، وملفًا عالميًا ~/.codeium/windsurf/memories/global_rules.md ينطبق على كل مشروع، ولكن لتعليمات خاصة بالمشروع، فإن دليل .windsurf/rules/ هو المكان الصحيح. هذا موثق في مرجع قواعد وذاكرات Windsurf.
أنشئ ملف .windsurf/rules/apidog.md بكتلة مثل هذه:
# Apidog API tests
يحتوي هذا المشروع على سيناريوهات اختبار Apidog. قم بتشغيلها باستخدام Apidog CLI:
apidog run -t <scenario_id> -e <env_id> -r cli
القواعد:
- استخدم الأمر أعلاه بالضبط؛ لا تخترع علامات. قم بتشغيل `apidog run --help` إذا لم تكن متأكدًا.
- `apidog run` يخرج برمز 0 عندما تمر جميع التأكيدات، وبرمز غير صفري عندما يفشل أي منها.
اعتبر رمز الخروج 0 نجاحًا وغير الصفري فشلاً. أبلغ عن رمز الخروج الفعلي.
- الجهاز مصادق عليه بالفعل عبر `apidog login`. لا تقم أبدًا بإضافة
رمز وصول إلى الأمر أو إلزام (commit) واحد لهذا الملف.
- بعد تغيير الكود الذي يمس الـ API، قم بتشغيل السيناريو وتصرف بناءً على النتيجة.
لماذا ملف قاعدة بدلاً من رسالة دردشة؟ معرف السيناريو الذي يتم كتابته في الدردشة يختفي عند انتهاء الجلسة. أما الذي في ملف .windsurf/rules/apidog.md فهو موجود لكل زميل في الفريق ولكل جلسة Cascade من الآن فصاعدًا. إنه مستمر، ويتم إصدار نسخته في Git، ويقوم Cascade بتحميله في السياق تلقائيًا عند بدء التشغيل.
الخطوة 2: احصل على الأمر من Apidog
معرفا <scenario_id> و <env_id> في تلك الكتلة ليسا علامات نائبة تخمنها. Apidog ينشئ الأمر الدقيق لك.
افتح سيناريو الاختبار في Apidog، انتقل إلى علامة تبويب CI/CD الخاصة به، وانسخ أمر apidog run الجاهز. يحتوي بالفعل على معرف السيناريو الصحيح، ومعرف البيئة، وعلامات المبلّغ مملوءة. الصق هذا الأمر في ملف .windsurf/rules/apidog.md الخاص بك بدلاً من السطر المثالي. الآن تحتوي القاعدة على أمر يعمل بالفعل ضد مشروعك، وليس مجرد قالب.
للاطلاع على التشريح الكامل لهذا الأمر وكل علامة يقبلها، راجع مرجع أمر apidog run.
الخطوة 3: اجعل Cascade يُشغل الاختبار
مع وجود القاعدة في مكانها، افتح Cascade في مستودعك. يقوم بتحميل .windsurf/rules/apidog.md عند بدء التشغيل، لذلك فهو يعرف بالفعل أن CLI موجود. قم بإجراء تغيير يمس واجهة برمجة التطبيقات (API) الخاصة بك، أو اطلب منه ببساطة تشغيل الفحص:
Run the Apidog scenario and tell me the exit code.
يصدر Cascade أمر apidog run من قاعدتك. يعتمد ما إذا كان يعمل بدون مطالبة على إعداد التشغيل التلقائي لديك. يوفر Windsurf أربعة مستويات: معطل (كل أمر يحتاج إلى موافقة)، قائمة السماح فقط (تلقائيًا للأوامر المطابقة لقائمتك المسموحة فقط)، تلقائي (تقدير نموذج متميز)، وتوربو (كل شيء يعمل تلقائيًا باستثناء الأوامر الموجودة في القائمة المحظورة). في وضع توربو، يتم تنفيذ أمر apidog run العادي تلقائيًا؛ في الأوضاع الأكثر صرامة، يتوقف Cascade ويطلب الإذن أولاً.
إذا كنت تريد أن يقوم apidog run بالتشغيل التلقائي دون تخفيف كل شيء، فأضفه إلى قائمة السماح الخاصة بك. الإعداد هو windsurf.cascadeCommandsAllowList، ويمكن الوصول إليه من لوحة الأوامر ضمن فتح الإعدادات؛ أضف apidog وسيُشغل Cascade الأمر دون سؤال. إعداد قائمة الرفض المطابق هو windsurf.cascadeCommandsDenyList، وتفوز قائمة الرفض عندما يتطابق أمر مع كليهما. كلاهما مغطى في توثيق الطرفية الخاص بـ Windsurf. إن سيناريو القراءة فقط مقابل بيئة الاختبار (staging) هو بالضبط نوع الأمر الآمن داخل مساحة العمل الذي تم تصميم إدخال قائمة السماح لأجله.
الخطوة 4: اقرأ التقرير داخل Windsurf
عندما يفشل تشغيل ما (يصبح أحمر)، يحتوي التقرير على الإجابة. يقوم مبلّغ -r cli بطباعة نتيجة وملخص خطوة بخطوة مباشرة في طرفية Cascade: كل طلب، كل تأكيد، وأي منها فشل مع القيمة المتوقعة مقابل القيمة الفعلية. يحدد التأكيد الفاشل الحقل الدقيق أو رمز الحالة، وهو ما يكفي عادةً لـ Cascade للعثور على الإصلاح في مروره التالي.
للحصول على تقرير يمكنك فتحه في المتصفح أو تسليمه لزميل في الفريق، أضف مبلّغ HTML:
apidog run -t <scenario_id> -e <env_id> -r cli,html
يكتب مبلّغ html ملفًا ذاتيًا إلى ./apidog-reports. احتفظ بـ cli في القائمة لكي يحصل Cascade على المخرجات المباشرة التي يقرأها لتحديد خطوته التالية. لكل مبلّغ، بما في ذلك لوحات معلومات CI التي تحلل تنسيق JUnit، راجع الدليل الكامل لـ Apidog CLI و كيفية قراءة تقارير اختبار Apidog CLI.
اختبار Windsurf ضمن حلقته الخاصة
المغزى هو ما يحدث عندما تتوقف عن السؤال ويقوم Cascade بتشغيل السيناريو من تلقاء نفسه لأن القاعدة طلبت منه ذلك.
تخيل أن Cascade يقوم بتحرير معالج ينشئ استجابة سحب. تتغير حلقته. يقوم بتعديل الكود، ثم بدلاً من إعلان النصر، يشغل سيناريو Apidog الخاص بك مقابل بيئة الاختبار (staging)، ويقرأ رمز الخروج، ويتصرف بناءً عليه. إذا كان أخضر، ينتقل. إذا كان أحمر، يفتح التقرير، ويقرأ أي تأكيد فشل (رمز الحالة، الحقل المفقود، القيمة الخاطئة)، ويحاول إصلاحًا، ويعيد التشغيل. يصبح اختبار API جزءًا من نفس حلقة التعديل والاختبار والإصلاح التي يشغل Cascade اختبارات وحدتك من خلالها بالفعل. لقد كتبت قاعدة واحدة وقام Cascade بدمج الأمر في طريقة عمله الحالية.
هذا هو نموذج التفويض ثم التحقق الذي يجعل أي سير عمل للوكيل آمنًا. يقوم Cascade بتشغيل الأمر وقراءة النتيجة؛ بينما تستمر في تأليف السيناريوهات بصريًا في Apidog وتتحقق من أن الوكيل يقرأ رموز الخروج بصدق. للحصول على النمط الأوسع، راجع كيفية استخدام وكلاء الذكاء الاصطناعي لاختبار API و أداة اختبار Apidog AI.
تحقق من أن Cascade يشغل CLI بالفعل
يُبلغ الوكلاء عن نجاح لم يكسبوه، وCascade ليس استثناءً. ثلاثة فحوصات، بترتيب تكرار اكتشافها للمشاكل.
أولاً، تأكد من أن الأمر قد تم تشغيله على الإطلاق. يعرض Cascade الأوامر التي ينفذها ومخرجاتها مباشرة في الطرفية. ابحث عن السطر الحرفي apidog run ... ونتيجة تحته. إذا قال Cascade إنه أجرى الاختبارات ولكنك لا ترى الأمر، فقد لخص شيئًا لم يفعله أبدًا. اطلب منه التشغيل مرة أخرى وإظهار المخرجات الخام.
ثانياً، تأكد من رمز الخروج، وهو الرمز المهم. اسأله مباشرة:
What was the exit code of that apidog run command?
يخرج apidog run برمز 0 عندما تمر جميع التأكيدات وبقيمة غير صفرية عندما يفشل أي شيء. يتيح هذا السلوك الفردي لـ Cascade، أو لخط أنابيب (pipeline)، معاملة التشغيل كبوابة نظيفة. عندما يقول نص Cascade أن “الاختبارات مرت” ولكن رمز الخروج غير صفري، فإن رمز الخروج هو الصحيح.
ثالثًا، تأكد من أنه استخدم السيناريو الحقيقي. إذا فشل التشغيل بـ “لم يتم العثور على السيناريو”، فربما يكون Cascade قد اخترع أو تذكر معرفًا خاطئًا. أعد التحقق من قيم -t و -e مقابل ملف القاعدة الخاص بك والأمر الذي أنشأه Apidog في علامة تبويب CI/CD. المعرفات الموجودة في .windsurf/rules/apidog.md هي الحقيقة.
اختياري: ربط خادم Apidog MCP
تشغيل apidog run من قاعدة يغطي معظم ما تحتاجه. للمضي خطوة إلى الأمام، قم بربط خادم MCP.
يدعم Cascade بروتوكول سياق النموذج (Model Context Protocol). يقرأ Windsurf قائمة خوادمه من ~/.codeium/windsurf/mcp_config.json، والذي يمكنك تعديله مباشرة أو إدارته عبر لوحة Cascade MCP؛ التنسيق موثق في مرجع MCP الخاص بـ Windsurf، و كيفية إعداد خوادم MCP في Windsurf يشرح اللوحة. يقوم خادم Apidog MCP بكشف مواصفات واجهة برمجة التطبيقات (API) الخاصة بك عبر MCP، حتى يتمكن Cascade من قراءة المخطط الخاص بك أثناء كتابته للكود، وليس فقط بعد الانتهاء. تقسيم العمل واضح: يقوم CLI بتشغيل الاختبارات، ويقوم MCP بتغذية الوكيل بالمواصفات.
عندما يخطئ Windsurf
تظهر بعض الإخفاقات غالبًا أثناء الإعداد.
يتجاهل القاعدة. إذا قام Cascade بتشغيل أمر عام أو لم يشغل أي شيء على الإطلاق، فقد لا يتم تحميل القاعدة. تأكد من أن الملف موجود في .windsurf/rules/ في جذر مستودعك ولديه امتداد .md. يبلغ الحد الأقصى لكل ملف قاعدة 12,000 حرف، لذا حافظ على كتلة Apidog قصيرة. إعادة تشغيل Cascade تجبره على قراءة جديدة.
يمرر رمز وصول على أي حال. إذا حاول Cascade إضافة رمز وصول إلى الأمر، فهو يخمن من الأمثلة العامة. تخبره قاعدتك بالفعل ألا يفعل ذلك، نظرًا لأن الجهاز مصادق عليه عبر apidog login. عزز السطر، ولا تضع أبدًا رمزًا حقيقيًا في ملف قواعد يتم إلزامه (committed). لمعرفة كيفية عمل المصادقة بالفعل، راجع دليل مصادقة Apidog CLI.
يخترع علامة (flag). خطأ “خيار غير معروف” يعني أن Cascade خمن علامة لا تملكها نسختك. اطلب منه تشغيل apidog run --help وانسخ العلامة الدقيقة من هناك، وهي دائمًا صحيحة لنسختك المثبتة.
يُبلغ عن نجاح في تشغيل فاشل. هذا هو الأكثر تكلفة، وهو السبب في أن قاعدة رمز الخروج موجودة في كل من ملف القواعد الخاص بك وخطوة التحقق الخاصة بك. عندما يتعارض الملخص ورمز الخروج، فإن رمز الخروج هو الذي يفوز.
من وكيل يومي إلى حلقة مختبرة
هذا هو الإعداد. قم بتثبيت apidog-cli مرة واحدة باتباع دليل التثبيت، أضف قاعدة Apidog قصيرة إلى دليل .windsurf/rules/ في مستودعك، ويعرف Cascade كيفية تشغيل اختبارات API الخاصة بك وقراءة النتيجة ضمن نفس الحلقة التي يستخدمها بالفعل لتحرير الكود. يتم اكتشاف نقطة نهاية معطلة بينما لا يزال Cascade يعمل على التغيير، وليس بعد إطلاقه.
يتم تشغيل الاختبار خلف واجهة رسومية (GUI) عندما ينقر إنسان؛ ويتم تشغيل أمر من سطر واحد كلما قرر Cascade ذلك. تستمر في بناء السيناريوهات بصريًا في Apidog، ويقوم وكيلك بتشغيلها حيث لا تشاهد. لتشغيل نفس الأمر في خط أنابيب (pipeline) بمجرد أن يعمل محليًا، يغطي Apidog CLI في GitHub Actions الأسرار والمبلّغين وبوابات رمز الخروج. قم بتنزيل Apidog، أنشئ سيناريو واحدًا، أسقط أمر apidog run الخاص به في قاعدة Windsurf، وشاهد Cascade يلتقطه في التغيير التالي.