يعد وضع العميل (Agent mode) في GitHub Copilot حلقة تتضمن: تحرير الملفات، تشغيل أوامر الطرفية، قراءة المخرجات، وتحديد الخطوة التالية. فلماذا لا تكون اختبارات API الخاصة بك في هذه الحلقة؟ إنها موجودة في Apidog خلف واجهة رسومية، وتعمل عندما يتذكر أحدهم النقر. Copilot لا يلمسها أبدًا.
الحل هو ملف تهيئة واحد. إن واجهة سطر الأوامر (CLI) الخاصة بـ Apidog هي حزمة npm، apidog-cli، تقوم بتشغيل سيناريوهات الاختبار التي أنشأتها في Apidog مباشرة من الطرفية. بمجرد تثبيت CLI ومعرفة Copilot بوجودها، يقوم وضع العميل بتشغيل سيناريو Apidog بنفس الطريقة التي يشغل بها اختبارات الوحدة الخاصة بك: تشغيل الأمر، قراءة رمز الخروج، وإصلاح الكود إذا كان أحمر.
button
إذا لم تكن قد قمت بتثبيت CLI بعد، فافعل ذلك أولاً. كيفية تثبيت Apidog CLI مع وكيل برمجة بالذكاء الاصطناعي يتناول عملية تثبيت npm، وتسجيل الدخول، والتشغيل الأول، مع قيام الوكيل بالطباعة. يفترض هذا المقال أن apidog --version يطبع رقمًا وأن حسابك في Apidog موثوق.
عن أي Copilot نتحدث؟
Copilot هو عدة منتجات، وتتداخل الأسماء بطرق مربكة. يتناول هذا المقال الواجهات التي يمكنها تشغيل أوامر shell.
الواجهة الرئيسية هي وضع العميل في VS Code. تفتح عرض Copilot Chat، وتقوم بتبديل القائمة المنسدلة للوضع إلى Agent، ويمكنه تحرير ملفات متعددة، وتشغيل أوامر الطرفية، والتكرار حتى تكتمل المهمة. عندما يريد تشغيل أمر، فإنه يعرض لك الأمر ويطلب التأكيد قبل التنفيذ. خطوة التأكيد هذه هي بالضبط حيث يتناسب apidog run.
هناك واجهتان ذات صلة تستحقان الذكر حتى تعرف أيهما تستخدم. يقوم وكيل برمجة Copilot بالعمل بشكل غير متزامن في GitHub Actions بعد أن تقوم بتعيين مشكلة له؛ وينتج طلب سحب بدلاً من العمل في محرر الكود الخاص بك. إن Copilot CLI هو عميل طرفي منفصل. كلاهما يمكنه تشغيل الأوامر، ولكن هذا المقال يستهدف وضع العميل في VS Code، لأنه المكان الذي تجلس فيه أثناء البرمجة وحيث تكون حلقة التعديل-الاختبار-الإصلاح هي الأكثر إحكامًا. الإعداد أدناه يعمل أيضًا لوكيل البرمجة، الذي يقرأ نفس ملف التعليمات. للحصول على جولة أوسع حول ما تغير عندما أصبح Copilot عاملاً، راجع وكيل برمجة GitHub Copilot الجديد.
التمييز مهم لأن Copilot لديه طريقة خاصة به لتعلم قواعد المشروع، وهذه الآلية تحول "تشغيل اختباراتي" لمرة واحدة إلى شيء يصل إليه Copilot بمفرده. تلك الآلية هي ملف تعليمات مخصص.
الخطوة 1: أضف قواعد Apidog إلى ملف تعليمات Copilot
يقرأ Copilot تعليمات المستودع المخصصة من ملف واحد: .github/copilot-instructions.md في جذر المستودع الخاص بك. يقوم وضع العميل، وCopilot Chat، ومراجعة الكود، ووكيل البرمجة بتحميله تلقائيًا، وفقًا لـ مستندات GitHub حول تعليمات المستودع المخصصة. فكر فيه على أنه CLAUDE.md لـ Claude Code أو AGENTS.md لـ Codex: ملف Markdown عادي لتعليمات المشروع التي يسحبها Copilot إلى السياق قبل أن يبدأ العمل.
أنشئ الملف وأضف كتلة Apidog قصيرة:
## API testing with the Apidog CLI
When you change an API endpoint, verify it with the Apidog CLI before
declaring the task done. Run:
apidog run -t 812345 -e 671234 -r cli
- `apidog run` exits 0 when every assertion passes, non-zero on any failure.
Treat a non-zero exit as a failing test, even if the summary text looks fine.
- The machine is already authenticated via `apidog login`. Do NOT add an
`--access-token` flag and never put a token in this file.
- If you hit an "unknown option" error, run `apidog run --help` and use the
real flags. Do not guess.
استبدل قيم -t و -e بسيناريو الاختبار الفعلي ومعرفات البيئة الخاصة بك من الخطوة التالية.
اكتبها في ملف التعليمات بدلاً من ذكرها في الدردشة لأن معرف السيناريو الذي يتم كتابته في الدردشة يختفي عند انتهاء الجلسة. أما الذي في .github/copilot-instructions.md فهو موجود لكل زميل في الفريق، وكل جلسة في وضع العميل، وكل طلب سحب يفتحه وكيل البرمجة من الآن فصاعدًا. إذا كنت تريد أن تنطبق القاعدة على ملفات معينة فقط، فإن GitHub يدعم أيضًا تعليمات خاصة بالمسار في .github/instructions/NAME.instructions.md، ولكن ملفًا واحدًا على مستوى المستودع يكفي هنا.
الخطوة 2: احصل على الأمر من Apidog
ليس عليك كتابة الأمر apidog run يدويًا. Apidog يولدها لك.
افتح سيناريو الاختبار في Apidog، انتقل إلى علامة التبويب CI/CD، وانسخ الأمر. يخرج الأمر كاملاً مع معرف السيناريو الصحيح (-t)، ومعرف البيئة (-e)، وعلامة المبلّغ:
apidog run -t 812345 -e 671234 -r cli
الصق هذه المعرفات بالضبط في الكتلة الموجودة في ملف .github/copilot-instructions.md الخاص بك. هذه المعرفات هي مصدر الحقيقة؛ عندما يختلف Copilot وملف التعليمات الخاص بك، تفوز علامة تبويب CI/CD. للحصول على المجموعة الكاملة من العلامات والمبلّغين، راجع مرجع أمر apidog run.
الخطوة 3: اجعل وضع العميل يشغل الاختبار
افتح عرض Copilot Chat في VS Code وقم بتبديل القائمة المنسدلة للوضع إلى Agent. نظرًا لأن وضع العميل يقوم بتحميل .github/copilot-instructions.md عند بدء تشغيله، فإنه يعرف بالفعل أن واجهة سطر الأوامر موجودة. قم بإجراء تغيير يمس واجهة برمجة التطبيقات الخاصة بك، أو اطلب منه مباشرة:
Run the Apidog API test scenario and tell me the result.
يصدر Copilot الأمر apidog run من ملف التعليمات الخاص بك. لا يقوم وضع العميل بتشغيل أوامر الطرفية بصمت؛ بل يعرض لك الأمر ويطلب منك التأكيد قبل تنفيذه، حتى ترى بالضبط ما سيتم تشغيله. وافق عليه. ثم يقوم المبلّغ -r cli بطباعة نتيجة خطوة بخطوة وملخص مباشرة في الطرفية المدمجة، حيث تشاهد كل طلب وتأكيد أثناء حدوثه.
أنت تريد أن ترى شيئين: تشغيل الاختبار، وإبلاغ Copilot بالملخص ورمز الخروج. إذا وافقت على الأمر مرة واحدة، يمكن لـ VS Code أن يتذكر اختيارك لهذا الأمر في مساحة العمل، لذلك يتم تنفيذ مكالمات apidog run اللاحقة دون إعادة المطالبة. سيناريو اختبار للقراءة فقط مقابل بيئة الاختبار (staging) هو بالضبط نوع الأمر الآمن داخل مساحة العمل الذي لا بأس بالسماح به.
الخطوة 4: اقرأ التقرير داخل Copilot
عندما يفشل التشغيل، يحتوي التقرير على الإجابة. باستخدام -r cli، يحصل Copilot على تفصيل قابل للقراءة في الطرفية: كل طلب، كل تأكيد، وأي منها فشل مع القيمة المتوقعة مقابل القيمة الفعلية. يحدد التأكيد الفاشل الحقل الدقيق أو رمز الحالة، وهو ما يكفي عادة لـ Copilot لإيجاد الإصلاح في تكراره التالي.
للحصول على تقرير يمكنك فتحه في المتصفح أو تسليمه لزميل في الفريق، أضف مبلّغ HTML:
apidog run -t 812345 -e 671234 -r cli,html
يقوم مبلّغ html بكتابة ملف مستقل إلى ./apidog-reports. احتفظ بـ cli في القائمة حتى يستمر Copilot في الحصول على الإخراج المضمّن الذي يقرأه لتحديد خطوته التالية. لكل تنسيق مبلّغ، بما في ذلك إخراج JUnit الذي تحلله لوحات معلومات CI، راجع دليل Apidog CLI الكامل و كيفية قراءة تقارير اختبار Apidog CLI.
اختبار Copilot داخل حلقته الخاصة
المهم هو ما يحدث عندما تتوقف عن السؤال ويقوم Copilot بتشغيل السيناريو بمفرده لأن ملف التعليمات أخبره بذلك.
تخيل وضع العميل يقوم بتحرير معالج ينشئ استجابة سلة المشتريات. تتغير حلقته. يقوم بتحرير الكود، ثم، بدلاً من إعلان النصر، يقوم بتشغيل سيناريو Apidog الخاص بك مقابل بيئة الاختبار، ويقرأ رمز الخروج، ويتصرف بناءً عليه. إذا كان أخضر، ينتقل. إذا كان أحمر، يفتح التقرير، يقرأ أي تأكيد فشل (رمز الحالة، الحقل المفقود، القيمة الخاطئة)، يحاول إصلاحًا، ويعيد التشغيل. يصبح اختبار API جزءًا من نفس حلقة التعديل-الاختبار-الإصلاح التي يديرها Copilot بالفعل لاختبارات الوحدة الخاصة بك. لقد كتبت تعليمات واحدة وقام Copilot بدمج الأمر في طريقة عمله بالفعل.
هذا هو نموذج التفويض ثم التحقق الذي يجعل أي سير عمل للعميل آمنًا. يقوم Copilot بتشغيل الأمر ويقرأ النتيجة؛ تستمر أنت في بناء السيناريوهات بصريًا في Apidog وتتحقق من أن العميل يقرأ رموز الخروج بصدق. للنمط الأوسع، راجع كيفية استخدام وكلاء الذكاء الاصطناعي لاختبار API و أداة اختبار Apidog AI.
تحقق من أن Copilot يقوم بتشغيل CLI بالفعل
يبلغ الوكلاء عن نجاح لم يحققوه، وCopilot ليس استثناءً. ثلاث فحوصات، حسب تكرار اكتشافها للمشاكل.
أولاً، تأكد من أن الأمر قد تم تشغيله على الإطلاق. يعرض وضع العميل الأوامر التي نفذها ومخرجاتها مضمنة في الطرفية. ابحث عن السطر الحرفي apidog run ... ونتيجة تحته. إذا قال Copilot إنه أجرى الاختبارات ولكنك لا ترى الأمر، فقد لخص شيئًا لم يفعله أبدًا. اطلب منه التشغيل مرة أخرى وإظهار الإخراج الخام.
ثانياً، تأكد من رمز الخروج، وهو ما يهم:
What was the exit code of that apidog run command?
يخرج apidog run برمز 0 عندما تمر جميع التأكيدات، وبرمز غير صفري عند أي فشل. هذا السلوك الواحد يسمح لـ Copilot، أو لخط أنابيب، بمعاملة التشغيل كبوابة نظيفة. عندما يقول نص Copilot "مرت الاختبارات" ولكن رمز الخروج غير صفري، فإن رمز الخروج هو الصحيح.
ثالثاً، تأكد من أنه استخدم السيناريو الحقيقي. إذا فشل التشغيل بـ "لم يتم العثور على السيناريو"، فربما يكون Copilot قد اختلق أو تذكر معرفًا خاطئًا. أعد التحقق من قيم -t و -e مقابل ملف التعليمات الخاص بك والأمر الذي أنشأه Apidog في علامة التبويب CI/CD. المعرفات من Apidog هي الحقيقة.
اختياري: ربط خادم Apidog MCP
تشغيل apidog run من ملف التعليمات الخاص بك يغطي معظم ما تحتاجه. للذهاب خطوة أبعد، قم بربط خادم Apidog MCP.
يقرأ وضع العميل في VS Code خوادم MCP من ملف .vscode/mcp.json لمساحة العمل في جذر المستودع الخاص بك، وفقًا لـ مستندات GitHub حول توسيع Copilot باستخدام MCP. يعرض خادم Apidog MCP مواصفات API الخاصة بك عبر MCP، حتى يتمكن Copilot من قراءة مخططك أثناء كتابة الكود، وليس بعد ذلك. تقسيم العمل نظيف: واجهة سطر الأوامر (CLI) تشغل الاختبارات، وMCP يغذي العميل بالمواصفات.
إذا قمت بتشغيل وكيل برمجة Copilot في GitHub Actions بدلاً من ذلك، فإن تهيئة MCP الخاصة به تكون في مكان مختلف. يمكنك إضافتها كـ JSON تحت إعدادات المستودع، في قسم Copilot تحت Cloud agent، مع تخزين أي بيانات سرية كأسرار Actions مسبوقة بـ COPILOT_MCP_. ملف .vscode/mcp.json مخصص لوضع العميل في محرر الكود الخاص بك.
عندما يخطئ Copilot
تظهر بعض الأخطاء بشكل متكرر أثناء الإعداد.
يتجاهل ملف التعليمات. إذا قام Copilot بتشغيل أمر عام أو لم يقم بتشغيل أي شيء على الإطلاق، فقد لا يتم تحميل الملف. تأكد من تسميته بالضبط .github/copilot-instructions.md، وأنه موجود في دليل .github في جذر المستودع الخاص بك، وأن التعليمات المخصصة ممكّنة في إعدادات VS Code الخاصة بك. المسار الخاطئ يعني أن Copilot لن يقرأه أبدًا.
يمرر رمز وصول على أي حال. إذا حاول Copilot إضافة --access-token، فهو يخمن من الأمثلة العامة. الكتلة تخبره بالفعل بعدم القيام بذلك، نظرًا لأن الجهاز موثوق به عبر apidog login. عزز السطر، ولا تضع أبدًا رمزًا حقيقيًا في ملف التعليمات. لنموذج المصادقة، راجع مصادقة Apidog CLI.
يخترع علامة. يعني خطأ "خيار غير معروف" أن Copilot خمن علامة لا يمتلكها إصدارك. اطلب منه تشغيل apidog run --help وانسخ العلامة الدقيقة من هناك، والتي تكون دائمًا صحيحة لإصدارك المثبت.
يبلغ عن نجاح في تشغيل فاشل. هذا هو الأغلى، والسبب في أن قاعدة رمز الخروج موجودة في ملف التعليمات الخاص بك وخطوة التحقق الخاصة بك. عندما يختلف الملخص ورمز الخروج، يفوز رمز الخروج.
من وكيل يومي إلى حلقة مختبرة
هذا هو الإعداد. قم بتثبيت apidog-cli مرة واحدة باتباع دليل التثبيت، وأضف كتلة Apidog قصيرة إلى ملف .github/copilot-instructions.md الخاص بمستودعك، وسيعرف Copilot كيفية تشغيل اختبارات API الخاصة بك وقراءة النتيجة داخل نفس الحلقة التي يستخدمها بالفعل لتحرير الكود. يتم اكتشاف نقطة نهاية معطلة بينما لا يزال Copilot يعمل على التغيير، وليس بعد نشره.
الاختبار خلف واجهة رسومية يعمل عندما ينقر إنسان؛ أمر سطر واحد يعمل عندما يقرر Copilot ذلك. تستمر أنت في بناء السيناريوهات بصريًا في Apidog، ويقوم وكيلك بتشغيلها بينما لا تراقب. قم بتنزيل Apidog، وقم ببناء سيناريو واحد، وأسقط الأمر apidog run الخاص به في .github/copilot-instructions.md، وشاهد Copilot يلتقطه عند التغيير التالي. عندما تكون جاهزًا لتشغيل نفس الأمر في خط أنابيب بدون وجود Copilot، يغطي Apidog CLI في GitHub Actions الأسرار، والمبلّغين، وبوابات رمز الخروج.