تراي (Trae) هي حلقة تكرارية. يقوم وكيلها البنّاء (Builder agent) بقراءة مستودعك، وتعديل الملفات، وتشغيل الأوامر في الطرفية، وقراءة المخرجات ليقرر ما يجب فعله لاحقًا. فلماذا لا تكون اختبارات واجهة برمجة التطبيقات (API) الخاصة بك ضمن هذه الحلقة؟ إنها موجودة في Apidog خلف واجهة مستخدم رسومية (GUI) وتُشغل عندما يتذكر شخص ما النقر عليها. وكيلك لا يلمسها أبدًا.
الحل هو كتلة إعدادات واحدة. إن Apidog CLI عبارة عن حزمة npm، apidog-cli، تقوم بتشغيل سيناريوهات الاختبار التي أنشأتها في Apidog مباشرة من الطرفية. بمجرد تثبيت CLI ومعرفة Trae بوجودها، يقوم البنّاء بتشغيل سيناريو Apidog بنفس الطريقة التي يشغل بها اختبارات الوحدات الخاصة بك: تشغيل الأمر، قراءة رمز الخروج، إصلاح الكود إذا كان أحمر (فاشل).
إذا لم تكن قد قمت بتثبيت CLI بعد، فافعل ذلك أولاً. تشرح كيفية تثبيت Apidog CLI باستخدام وكيل برمجة ذكاء اصطناعي عملية التثبيت باستخدام npm، والمصادقة، والتشغيل الأول، مع قيام الوكيل بالطباعة. يفترض هذا المقال أن apidog --version يطبع رقمًا وأن حسابك في Apidog مصادق عليه.
أي Trae نتحدث عنه
تراي (Trae) هو بيئة تطوير متكاملة (IDE) للذكاء الاصطناعي من ByteDance، مبنية على VS Code، مع وضع وكيل يسمى Builder يقوم بتعديل الملفات وتشغيل أوامر الطرفية بنفسه. يمكنك قراءة تفاصيل المنتج على الموقع الرسمي لتراي. يتناول هذا المقال بيئة التطوير المتكاملة لسطح المكتب، وليس مشروع البحث المستقل trae-agent على GitHub. إذا فتحت Trae، ورأيت لوحة محادثة بجوار محرر النصوص الخاص بك، ويمكنك تبديل الوكيل إلى Builder، فأنت في المكان الصحيح.
يُعد هذا التمييز مهمًا لأن Trae لديها طريقتها الخاصة لتعلم قواعد المشروع، وهذه الآلية تحوّل "تشغيل اختباراتي" لمرة واحدة إلى شيء يسعى إليه البنّاء بنفسه. هذه الآلية هي ملف قواعد المشروع. إذا كنت تريد النسخة المستقلة عن الأداة من سير العمل هذا أولاً، فإن الدليل الكامل لـ Apidog CLI يغطي CLI بحد ذاته.
الخطوة 1: إضافة ملف قواعد المشروع
يقرأ Trae ملفات القواعد قبل أن يبدأ البنّاء بالعمل. يوجد ملف مستوى المشروع في .trae/rules/project_rules.md في جذر مستودعك، وفقًا لـ وثائق قواعد Trae. يقوم الوكيل بتحميل هذه القواعد أثناء التهيئة ويستشهد بها أثناء توليد وتعديل الكود. يوجد أيضًا ملف user_rules.md على مستوى المستخدم ينطبق على جميع مشاريعك؛ ولهذا سير العمل، يكفي ملف مشروع واحد في جذر المستودع.
قم بإنشاء .trae/rules/project_rules.md وأضف كتلة قصيرة تحدد اسم CLI، وأمر السيناريو الدقيق، والقواعد التي تحافظ على شفافية البنّاء:
## اختبار API باستخدام Apidog CLI
عندما تقوم بتغيير كود يلامس نقطة نهاية API، تحقق منه بتشغيل
سيناريو اختبار Apidog، وليس فقط اختبارات الوحدات.
الأمر:
apidog run -t <scenario_id> -e <env_id> -r cli
القواعد:
- `apidog run` يخرج برمز 0 عندما تنجح جميع التأكيدات (assertions) وبرمز غير صفري عند أي فشل.
تعامل مع رمز الخروج غير الصفري على أنه اختبار فاشل، حتى لو كان الملخص يبدو جيدًا.
- هذه الآلة مصادق عليها بالفعل عبر `apidog login`. لا تقم أبدًا بإضافة
علامة --access-token ولا تضع رمزًا مميزًا (token) في هذا الملف أبدًا.
- إذا كانت هناك علامة (flag) غير معروفة، فقم بتشغيل `apidog run --help` واستخدم العلامة الدقيقة من هناك.
لهذا السبب تكتب CLI في project_rules.md بدلاً من ذكرها في الدردشة. معرّف السيناريو الذي يُكتب في لوحة الدردشة يختفي عند انتهاء الجلسة. أما الذي في .trae/rules/project_rules.md فيبقى متاحًا لكل زميل في الفريق وكل عملية تشغيل للبنّاء من الآن فصاعدًا. يقرأ Trae أيضًا مجلدات .trae/rules/ في الدلائل الفرعية، لذا يمكن للمستودع الموحد (monorepo) الاحتفاظ بقواعد خاصة بكل خدمة بجوار كل خدمة.
الخطوة 2: الحصول على الأمر من Apidog
ليس عليك تخمين الأمر. افتح سيناريو الاختبار في Apidog، انتقل إلى علامة تبويب CI/CD الخاصة به، وانسخ سطر apidog run الذي تم إنشاؤه. يحتوي بالفعل على معرف السيناريو الحقيقي بعد -t ومعرف البيئة بعد -e، لذلك أنت تلصق أمرًا يعرف Apidog أنه صالح بدلاً من اختراع المعرفات يدويًا.
ضع هذه المعرفات الدقيقة في الكتلة الموجودة في .trae/rules/project_rules.md، مستبدلاً الحاصرات <scenario_id> و <env_id>. للحصول على المجموعة الكاملة من الأعلام وما يفعله كل منها، راجع مرجع أمر apidog run.
الخطوة 3: جعل البنّاء يُشغّل الاختبار
بعد وضع الكتلة في مكانها، قم بتبديل وكيل Trae إلى Builder وابدأ تشغيله في مستودعك. يقوم البنّاء بتحميل project_rules.md عند تهيئته، لذا فهو يعرف بالفعل أن CLI موجودة. قم بإجراء تغيير يلامس واجهة برمجة التطبيقات (API) الخاصة بك، أو اطلب منه ببساطة تشغيل الفحص:
قم بتشغيل سيناريو اختبار Apidog وأخبرني برمز الخروج.
يصدر البنّاء أمر apidog run من ملف القواعد الخاص بك. نموذج موافقة Trae مهم هنا: عندما يريد الوكيل تشغيل أمر shell، فإنه يوصي بالأمر ويعرض زر "تشغيل"، ويتم تنفيذ الأمر في طرفية Trae فقط بعد النقر عليه. بمجرد تشغيله، يقرأ البنّاء المخرجات ويحللها تلقائيًا. لذا، أنت توافق على apidog run مرة واحدة، ويأخذ الوكيل النتيجة من هناك.
يقوم مُبلّغ -r cli بطباعة نتيجة خطوة بخطوة وملخص مباشرة في الطرفية، حيث يقرأ البنّاء كل طلب وتأكيد أثناء حدوثه. أنت تريد أن ترى عملية التشغيل قيد التنفيذ والبنّاء يقدم تقريرًا عن الملخص ورمز الخروج على حد سواء.
الخطوة 4: قراءة التقرير داخل Trae
عندما يفشل التشغيل (يصبح أحمر)، يحتوي التقرير على الإجابة. باستخدام -r cli، يحصل البنّاء على تفصيل قابل للقراءة في طرفية Trae: كل طلب، كل تأكيد، وأي منها فشل مع القيمة المتوقعة مقابل القيمة الفعلية. يحدد التأكيد الفاشل الحقل الدقيق أو رمز الحالة، وهو عادةً ما يكفي للبنّاء ليجد الإصلاح.
للحصول على تقرير يمكنك فتحه في المتصفح أو تسليمه لزميل في الفريق، أضف مُبلّغ HTML:
apidog run -t <scenario_id> -e <env_id> -r cli,html
يكتب مُبلّغ html ملفًا ذاتيًا إلى ./apidog-reports. حافظ على cli في القائمة حتى يستمر البنّاء في الحصول على الإخراج المضمّن الذي يقرأه ليقرر خطوته التالية. لكل مُبلّغ، بما في ذلك تنسيقات JSON و JUnit التي تحللها لوحات معلومات CI، راجع دليل تقارير اختبار Apidog CLI.
اختبار Trae ضمن حلقته الخاصة
النقطة المهمة هي ما يحدث عندما تتوقف عن الطلب ويقوم البنّاء بتشغيل السيناريو بنفسه لأن project_rules.md أمره بذلك.
تخيل البنّاء يقوم بتعديل معالج يقوم ببناء استجابة الدفع (checkout response). تتغير حلقته: يقوم بتعديل الكود، ثم، بدلاً من إعلان النصر، يقوم بتشغيل سيناريو Apidog الخاص بك مقابل بيئة التدريج (staging)، يقرأ رمز الخروج، ويتصرف بناءً عليه. أخضر (ناجح)، يتقدم. أحمر (فاشل)، يفتح التقرير، يقرأ أي تأكيد فشل (رمز الحالة، الحقل المفقود، القيمة الخاطئة)، يحاول إصلاحًا، ويعيد التشغيل. يصبح اختبار API جزءًا من نفس حلقة التعديل-الاختبار-الإصلاح التي يشغل البنّاء اختبارات الوحدات الخاصة بك من خلالها بالفعل. لقد كتبت تعليمًا واحدًا وقام البنّاء بدمج الأمر في طريقة عمله الحالية.
هذا هو نموذج التفويض ثم التحقق الذي يجعل أي سير عمل للوكيل آمنًا. يقوم البنّاء بتشغيل الأمر وقراءة النتيجة؛ بينما تستمر أنت في تأليف السيناريوهات بصريًا في Apidog وتتحقق بشكل عشوائي من أن الوكيل يقرأ رموز الخروج بصدق. للحصول على النمط الأوسع، راجع كيفية استخدام وكلاء الذكاء الاصطناعي لاختبار API و حزمة اختبار Apidog AI.
تحقق من أن Trae يشغل CLI بالفعل
يبلغ الوكلاء عن نجاح لم يحققوه، والبنّاء ليس استثناءً. ثلاث فحوصات، بترتيب مدى تكرارها في كشف المشاكل.
أولاً، تأكد من أن الأمر قد تم تشغيله على الإطلاق. يعرض Trae الأوامر التي نفذها البنّاء ومخرجاتها في الطرفية. ابحث عن سطر apidog run الحرفي ونتيجة تحته. إذا قال البنّاء إنه أجرى الاختبارات ولكنك لا ترى الأمر، فقد لخص شيئًا لم يفعله أبدًا. اطلب منه التشغيل مرة أخرى وإظهار الإخراج الخام.
ثانيًا، تأكد من رمز الخروج:
ما هو رمز الخروج لأمر apidog run ذاك؟
يخرج apidog run برمز 0 عندما تنجح جميع التأكيدات (assertions) وبرمز غير صفري عندما يفشل أي شيء. هذا السلوك الفردي يتيح للبنّاء، أو لخط أنابيب (pipeline)، التعامل مع التشغيل كبوابة نظيفة. عندما يقول نص البنّاء "اجتازت الاختبارات" ولكن رمز الخروج غير صفري، فإن رمز الخروج هو الصحيح.
ثالثًا، تأكد من أنه استخدم السيناريو الحقيقي. إذا فشل تشغيل مع رسالة "السيناريو غير موجود"، فربما يكون البنّاء قد اخترع أو تذكر معرفًا خاطئًا. أعد التحقق من قيم -t و -e مقابل project_rules.md والأمر الذي أنشأه Apidog في علامة تبويب CI/CD. المعرفات في ملف القواعد الخاص بك هي الحقيقة.
اختياري: ربط خادم Apidog MCP
تشغيل apidog run من project_rules.md يغطي معظم ما تحتاجه. ربط خادم MCP يخطو خطوة أبعد. تعمل وكلاء Trae كعملاء MCP، لذا يمكن للبنّاء استدعاء الأدوات التي يكشفها خادم MCP.
لإضافة واحد، افتح إعدادات Trae، انتقل إلى علامة تبويب MCP، واختر إما خادمًا من السوق أو اختر إضافة يدويًا والصق كتلة JSON تحتوي على command و args و env الخاص بالخادم، وفقًا لـ دليل Trae لإضافة خوادم MCP. يكشف خادم Apidog MCP مواصفات واجهة برمجة التطبيقات (API) الخاصة بك عبر MCP، حتى يتمكن البنّاء من قراءة المخطط الخاص بك أثناء كتابته للكود، وليس فقط بعد الانتهاء. تقسيم العمل واضح: يقوم CLI بتشغيل الاختبارات، ويغذي MCP الوكيل بالمواصفات.
عندما يخطئ Trae
تظهر بعض الأعطال غالبًا أثناء الإعداد.
يتجاهل ملف القواعد. إذا قام البنّاء بتشغيل أمر عام أو لم يشغل أي شيء على الإطلاق، فقد لا يكون الملف قيد التحميل. تأكد من أنه في .trae/rules/project_rules.md في جذر مستودعك وأن المجلد يسمى rules، وليس rule. إعادة تشغيل الجلسة تفرض قراءة جديدة للقواعد.
يمرر رمز وصول على أي حال. إذا حاول البنّاء إضافة --access-token، فهو يخمن من الأمثلة العامة. الكتلة تخبره بالفعل بعدم فعل ذلك، حيث أن الجهاز مصادق عليه عبر apidog login. عزز هذا السطر، ولا تضع أبدًا رمزًا حقيقيًا في project_rules.md. لكيفية تعامل CLI مع بيانات الاعتماد في الاستخدام التفاعلي وفي CI، راجع مصادقة Apidog CLI.
يخترع علامة (flag). خطأ "خيار غير معروف" يعني أن البنّاء خمّن علامة غير موجودة في نسختك. اطلب منه تشغيل apidog run --help ونسخ العلامة الدقيقة من هناك، وهي دائمًا صحيحة لنسختك المثبتة.
يبلغ عن نجاح في تشغيل فاشل. هذه هي أغلى الأخطاء، والسبب في أن قاعدة رمز الخروج موجودة في project_rules.md وخطوة التحقق الخاصة بك. عندما يختلف الملخص ورمز الخروج، يفوز رمز الخروج.
من وكيل يومي إلى حلقة اختبار
هذا هو الإعداد. قم بتثبيت apidog-cli مرة واحدة باتباع دليل التثبيت، أضف كتلة Apidog قصيرة إلى .trae/rules/project_rules.md، وسيعرف البنّاء كيفية تشغيل اختبارات API الخاصة بك وقراءة النتيجة ضمن نفس الحلقة التي يستخدمها بالفعل لتعديل الكود. سيتم اكتشاف نقطة نهاية معطلة بينما لا يزال البنّاء يعمل على التغيير، وليس بعد شحنه.
يُشغل الاختبار خلف واجهة المستخدم الرسومية عندما ينقر الإنسان؛ أما الأمر المكون من سطر واحد فيُشغل كلما قرر البنّاء ذلك. تستمر أنت في بناء السيناريوهات بصريًا في Apidog، ويُشغل وكيلك هذه السيناريوهات حيث لا تراقب. قم بتنزيل Apidog، وقم ببناء سيناريو واحد، ثم ضع أمر apidog run الخاص به في .trae/rules/project_rules.md، وشاهد البنّاء يلتقطه عند التغيير التالي. عندما تكون مستعدًا لتشغيل نفس السيناريو دون وجود وكيل، فإن Apidog CLI في GitHub Actions يغطي الأسرار، والمُبلغين، وبوابات رمز الخروج لـ CI.