Codex هي حلقة: تقوم بتعديل الملفات، وتشغيل الأوامر، وقراءة المخرجات، ثم تقرر الخطوة التالية. فلماذا لا تكون اختبارات API الخاصة بك ضمن هذه الحلقة؟ إنها موجودة في Apidog خلف واجهة المستخدم الرسومية، وتُشغل عندما يتذكر شخص ما النقر عليها. لا يلمسها وكيلك أبدًا.
الحل هو كتلة تكوين واحدة. واجهة سطر الأوامر (CLI) الخاصة بـ Apidog هي حزمة npm، apidog-cli، تشغل سيناريوهات الاختبار التي بنيتها في Apidog مباشرة من الطرفية. بمجرد تثبيت CLI ومعرفة Codex بوجودها، يقوم وكيلك بتشغيل سيناريو Apidog بنفس الطريقة التي يشغل بها اختبارات الوحدة الخاصة بك: قم بتشغيل الأمر، واقرأ رمز الخروج، وقم بإصلاح الكود إذا كان أحمر.
يغطي هذا الدليل الجزء الخاص بـ Codex الذي يتخطاه دليل التثبيت العام: السطر الدقيق لملف AGENTS.md الخاص بك، الأمر الذي يُعطى لـ Codex، وكيف يشغل apidog run داخل حلقته الخاصة، وكيفية قراءة النتيجة.
إذا لم تكن قد قمت بتثبيت CLI بعد، فافعل ذلك أولاً. كيفية تثبيت Apidog CLI باستخدام وكيل ترميز بالذكاء الاصطناعي يشرح تثبيت npm، ورمز الوصول، والتشغيل الأول، مع قيام Codex بالطباعة. يفترض هذا المقال أن apidog --version يطبع رقمًا وأن حسابك على Apidog موثق.
أي Codex يدور الحديث عنه
كل من OpenAI Codex CLI وتطبيق Codex App. يعمل محليًا، يقرأ مستودعك، يعدل الملفات، وينفذ أوامر shell داخل بيئة معزولة، ويطلب الموافقة بناءً على وضع أذونك. إنه ليس واجهة برمجة تطبيقات (API) إكمال الكود القديمة لـ Codex. إذا قمت بتشغيل codex وحصلت على واجهة بملء الشاشة تعرض الفروقات ومخرجات الأوامر، فأنت في المكان الصحيح. دليل OpenAI Codex CLI يغطي الأساسيات.
التمييز مهم لأن Codex له طريقته الخاصة في تعلم قواعد المشروع، وهذه الآلية تحول "شغل اختباراتي" لمرة واحدة إلى شيء يصل إليه Codex بمفرده. هذه الآلية هي AGENTS.md.
الآلية: AGENTS.md، وليس تذكيرًا في الدردشة
يقرأ Codex ملفات AGENTS.md قبل أن يبدأ العمل. فكر في الأمر كـ CLAUDE.md لـ Claude Code: ملف Markdown عادي يحتوي على تعليمات المشروع يقوم Codex بتحميلها في السياق في بداية كل جلسة. يبني مجموعة التعليمات عن طريق الانتقال من جذر Git الخاص بك وصولاً إلى دليلك الحالي، وربط كل ملف AGENTS.md من الجذر أولاً، بحيث تفوز الملفات الأقرب في حالة التعارضات. يوجد أيضًا ملف ~/.codex/AGENTS.md عالمي. لغرضنا، ملف واحد في جذر المستودع يكفي.
هذا هو السبب في أنك تكتب CLI في AGENTS.md بدلاً من ذكره في الدردشة. معرّف السيناريو الذي يتم كتابته في الدردشة يختفي عند انتهاء الجلسة. بينما المعرّف الموجود في AGENTS.md يبقى متاحًا لكل زميل في الفريق ولكل تشغيل لـ Codex من الآن فصاعدًا.
الخطوة 1: أعط Codex الأمر وشاهد كيف يعمل
مع وجود الكتلة في مكانها، ابدأ Codex في مستودعك:
يقوم Codex بتحميل AGENTS.md عند بدء التشغيل، لذلك فهو يعرف بالفعل أن CLI موجود. قم بإجراء تغيير يمس واجهة برمجة التطبيقات (API) الخاصة بك، أو اطلب منه تشغيل التحقق:
يصدر Codex أمر apidog run من ملف AGENTS.md الخاص بك. في وضعه التلقائي الافتراضي (Auto mode)، يمكنه قراءة الملفات وتعديلها وتشغيل الأوامر داخل دليل العمل بمفرده، لذا فإن أمر apidog run العادي عادة ما ينفذ دون الحاجة إلى توجيه. يقوم الـ reporter -r cli بطباعة نتيجة وملخص خطوة بخطوة مباشرة في الطرفية، حيث تشاهد كل طلب وتأكيد يحدث.
تريد أن ترى التشغيل قيد التنفيذ و Codex يُبلغ عن الملخص ورمز الخروج معًا. إذا كان وضع الأذونات لديك للقراءة فقط (Read-only)، يتوقف Codex ويطلب الموافقة قبل التشغيل؛ وافق عليه، أو قم بتغيير الوضع باستخدام /permissions داخل الجلسة. الوضع التلقائي (Auto) هو الافتراضي المعقول، حيث إن سيناريو اختبار للقراءة فقط مقابل بيئة تجريبية هو بالضبط نوع الأمر الآمن داخل مساحة العمل الذي صمم هذا الوضع لأجله.
الخطوة 2: اختبار Codex داخل حلقته الخاصة
النقطة هي ما يحدث عندما تتوقف عن السؤال ويقوم Codex بتشغيل السيناريو بمفرده لأن AGENTS.md أمره بذلك.
تخيل أن Codex يقوم بتعديل معالج يقوم ببناء استجابة للدفع. تتغير حلقته: يقوم بتعديل الكود، ثم، بدلاً من إعلان الانتصار، يشغل سيناريو Apidog الخاص بك مقابل البيئة التجريبية، ويقرأ رمز الخروج، ويتصرف بناءً عليه. أخضر، ينتقل إلى الخطوة التالية. أحمر، يفتح التقرير، ويقرأ أي تأكيد فشل (رمز الحالة، الحقل المفقود، القيمة الخاطئة)، ويحاول الإصلاح، ويعيد التشغيل. يصبح اختبار API جزءًا من نفس حلقة التعديل والاختبار والإصلاح التي يشغل Codex من خلالها اختبارات الوحدة الخاصة بك. لقد كتبت تعليمات واحدة وقام Codex بدمج الأمر في طريقة عمله بالفعل.
هذا هو نموذج التفويض ثم التحقق (delegate-then-verify) الذي يجعل أي سير عمل للوكيل آمنًا. يقوم Codex بتشغيل الأمر وقراءة النتيجة؛ بينما تستمر في صياغة السيناريوهات بصريًا في Apidog والتحقق من أن الوكيل يقرأ رموز الخروج بصدق. للاطلاع على النمط الأوسع، راجع كيفية استخدام وكلاء الذكاء الاصطناعي لاختبار واجهة برمجة التطبيقات (API) و أداة اختبار Apidog AI.
تحقق من أن Codex يقوم بتشغيل CLI بالفعل
يُبلغ الوكلاء عن نجاح لم يحققوه، وCodex ليس استثناءً. ثلاث عمليات تحقق، بترتيب مدى تكرار اكتشافها للمشاكل.
أولاً، تأكد من أن الأمر قد تم تشغيله على الإطلاق. تعرض واجهة Codex الأوامر التي نفذتها ومخرجاتها مضمنة. ابحث عن السطر الحرفي apidog run ... ونتيجة تحته. إذا قال Codex إنه قام بتشغيل الاختبارات ولكنك لا ترى الأمر، فقد قام بتلخيص شيء لم يفعله أبدًا. اطلب منه التشغيل مرة أخرى وإظهار المخرجات الخام.
ثانيًا، تأكد من رمز الخروج، وهو الرمز الذي يهم:
ما هو رمز الخروج لأمر apidog run هذا؟
يخرج apidog run بالرمز 0 عندما تمر جميع التأكيدات، وبقيمة غير صفرية عندما يفشل أي شيء. يتيح هذا السلوك الفردي لـ Codex، أو لخط أنابيب (pipeline)، التعامل مع التشغيل كبوابة نظيفة. عندما يقول نص Codex "الاختبارات اجتازت" ولكن رمز الخروج غير صفري، فإن رمز الخروج هو الصحيح.
ثالثًا، تأكد من استخدامه للسيناريو الحقيقي. إذا فشل تشغيل ما بعبارة "السيناريو غير موجود"، فقد يكون Codex قد اخترع أو نسي معرفًا. أعد التحقق من قيم -t و -e مقابل AGENTS.md والأمر الذي أنشأه Apidog في علامة تبويب CI/CD. المعرفات في AGENTS.md هي الحقيقة.
قراءة تقرير الاختبار
عندما يصبح التشغيل أحمر (فاشل)، فإن التقرير يحتوي على الإجابة. باستخدام -r cli، يحصل Codex على تفصيل قابل للقراءة في الطرفية: كل طلب، كل تأكيد، وأي منها فشل مع القيمة المتوقعة مقابل القيمة الفعلية. يذكر التأكيد الفاشل الحقل الدقيق أو رمز الحالة، وهو عادة ما يكون كافيًا لـ Codex لإيجاد الإصلاح.
للحصول على تقرير يمكنك فتحه في متصفح أو تسليمه لزميل في الفريق، أضف مُصدر تقارير HTML
يكتب مُصدر التقارير html ملفًا ذاتيًا إلى ./apidog-reports. احتفظ بـ cli في القائمة حتى لا يزال Codex يحصل على المخرجات المضمنة التي يقرأها ليقرر خطوته التالية. لكل علامة ومُصدر تقارير، بما في ذلك تنسيق JUnit الذي تحلله لوحات معلومات CI، راجع الدليل الكامل لـ Apidog CLI و مرجع الأمر apidog run.
طريقتان للتعمق أكثر من أوامر shell
تشغيل apidog run من AGENTS.md يغطي معظم ما تحتاجه. هناك مساران للتعمق أكثر.
المسار الأول هو MCP. يدعم Codex بروتوكول سياق النموذج (Model Context Protocol)، ويمكنك إضافة خوادم باستخدام codex mcp add أو عن طريق تعديل ~/.codex/config.toml بكتلة [mcp_servers.NAME]. يقوم خادم Apidog MCP بتعريض مواصفات API الخاصة بك عبر MCP، بحيث يمكن لـ Codex قراءة مخططك أثناء كتابة الكود، وليس فقط بعد الحقيقة. يقوم CLI بتشغيل الاختبارات؛ ويغذي MCP الوكيل بالمواصفات.
الطريقة الثانية هي codex exec. بينما تفتح codex العادية الواجهة التفاعلية، تقوم codex exec "..." بتشغيل Codex بطريقة غير تفاعلية وتوجيه النتيجة إلى الإخراج القياسي (stdout)، وهذا ما تستخدمه في السكربتات والتكامل المستمر (CI). لتشغيل apidog run في خط أنابيب بدون وجود Codex، يغطي مقال Apidog CLI في GitHub Actions الأسرار، ومُصدري التقارير، والتحكم في رمز الخروج.
عندما يخطئ Codex
تظهر بعض الإخفاقات بشكل متكرر أثناء الإعداد.
يتجاهل كتلة AGENTS.md. إذا قام Codex بتشغيل أمر عام أو لم يقم بذلك على الإطلاق، فقد لا تكون الكتلة قيد التحميل. تأكد من أن اسم الملف هو AGENTS.md بالضبط وأنه يقع في جذر Git الخاص بك أو في دليل أبوي لدليلك الحالي. خطأ إملائي في اسم الملف يعني أن Codex لن يقرأه أبدًا؛ إعادة تشغيل الجلسة تفرض قراءة جديدة.
يحاول تمرير رمز وصول على أي حال. إذا حاول Codex إضافة --access-token، فهو يخمن من الأمثلة العامة. الكتلة تخبره بالفعل ألا يفعل ذلك، لأن الجهاز موثق عبر apidog login. عزز السطر، ولا تضع أبدًا رمزًا حقيقيًا في AGENTS.md.
يخترع علامة (flag). يعني خطأ "خيار غير معروف" أن Codex خمن علامة لا يمتلكها إصدارك. اطلب منه تشغيل apidog run --help وانسخ العلامة الدقيقة من هناك، وهي صحيحة دائمًا لإصدارك المثبت.
يبلغ عن اجتياز تشغيل فاشل. هذا هو الأكثر تكلفة، وهو السبب في أن قاعدة رمز الخروج موجودة في AGENTS.md وفي خطوة التحقق الخاصة بك. عندما يتعارض الملخص ورمز الخروج، يفوز رمز الخروج.
من وكيل يومي إلى حلقة مختبرة
هذا هو الإعداد. قم بتثبيت apidog-cli مرة واحدة باتباع دليل التثبيت، أضف كتلة Apidog قصيرة إلى ملف AGENTS.md في مستودعك، وسيعرف Codex كيفية تشغيل اختبارات API الخاصة بك وقراءة النتيجة داخل نفس الحلقة التي يستخدمها بالفعل لتعديل الكود. يتم اكتشاف نقطة نهاية معطلة بينما لا يزال Codex يعمل على التغيير، وليس بعد نشره.
الاختبار الذي يتم تشغيله خلف واجهة مستخدم رسومية يعمل عندما ينقر عليه إنسان؛ أما أمر من سطر واحد فيعمل متى قرر Codex ذلك. تستمر أنت في بناء السيناريوهات بصريًا في Apidog، ويشغلها وكيلك حيث لا تراقب. قم بتنزيل Apidog، أنشئ سيناريو واحدًا، أسقط أمر apidog run الخاص به في AGENTS.md، وشاهد Codex يلتقطه في التغيير التالي.