Claude Code هو حلقة: يقوم بتحرير الملفات، وتشغيل الأوامر في محطتك الطرفية، وقراءة المخرجات، وتحديد الخطوة التالية. فلماذا لا تكون اختبارات API الخاصة بك ضمن هذه الحلقة؟ إنها موجودة في Apidog خلف واجهة مستخدم رسومية وتُشغل عندما يتذكر أحدهم النقر. وكيلك لا يلمسها أبدًا.
الحل هو كتلة تكوين واحدة. واجهة Apidog CLI هي حزمة npm، apidog-cli، تقوم بتشغيل سيناريوهات الاختبار التي بنيتها في Apidog مباشرة من المحطة الطرفية. بمجرد تثبيت CLI ومعرفة Claude Code بوجودها، يقوم وكيلك بتشغيل سيناريو Apidog بنفس الطريقة التي يشغل بها اختبارات الوحدة الخاصة بك: قم بتشغيل الأمر، اقرأ رمز الخروج، وقم بإصلاح الكود إذا كان أحمر.
يغطي هذا الدليل الجزء الخاص بـ Claude Code الذي يتخطاه دليل التثبيت العام: السطر الدقيق لملف CLAUDE.md الخاص بك، وكيف يشغل Claude Code الأمر apidog run ضمن نموذج صلاحياته، وكيفية قراءة النتائج داخل حلقة التعديل والاختبار والإصلاح الخاصة به.
إذا لم تقم بتثبيت CLI بعد، فافعل ذلك أولاً. يشرح كيفية تثبيت Apidog CLI باستخدام وكيل ترميز AI عملية تثبيت npm والتشغيل الأول، مع قيام الوكيل بالطباعة. يفترض هذا المقال أن الأمر apidog --version يطبع رقمًا وأن حسابك في Apidog موثق.
أي Claude Code يدور حوله هذا الموضوع
هذا هو Claude Code CLI، وكيل الترميز من Anthropic الذي يعمل في محطتك الطرفية (أو تطبيق سطح المكتب). يقرأ مستودعك، ويحرر الملفات، ويشغل أوامر shell، طالبًا الموافقة بناءً على وضع الصلاحية الخاص بك. إنه ليس تطبيق دردشة Claude وليس مجرد استدعاء API. إذا قمت بتشغيل claude في مستودع وحصلت على وكيل تفاعلي يقترح تعديلات وتشغيل أوامر، فأنت في المكان الصحيح. الأوامر التي تكتبها للمحطة الطرفية موجودة في أوامر سلاش Claude Code وملف القواعد الخاص به، وهذا الملف هو المكان المناسب لـ Apidog CLI.
يهم هذا التمييز لأن Claude Code لديه طريقته الخاصة في تعلم قواعد المشروع، وهذه الآلية تحول "تشغيل اختباراتي" لمرة واحدة إلى شيء يسعى إليه Claude بمفرده. هذه الآلية هي CLAUDE.md.
الخطوة 1: أضف كتلة Apidog إلى CLAUDE.md
يقرأ Claude Code ملفات CLAUDE.md في بداية كل جلسة. هذا هو النظير المباشر لـ AGENTS.md لـ Codex؛ في الواقع، تشير وثائق Anthropic إلى أن Claude Code يقرأ CLAUDE.md، وليس AGENTS.md، وتقترح استيراد ملف AGENTS.md موجود باستخدام @AGENTS.md إذا كنت تحتفظ بواحد لوكيل آخر. إذا كنت قد قمت بالفعل بإعداد Apidog CLI في Codex، فهذه هي نفس الفكرة ولكن باسم ملف مختلف.
ضع ملف CLAUDE.md في جذر مستودعك (يقبل Claude Code أيضًا ./.claude/CLAUDE.md، وملف ~/.claude/CLAUDE.md عام للافتراضات الشخصية). يتتبع Claude Code شجرة الدليل من حيث أطلقته ويحمّل كل ملف CLAUDE.md يجده، لذا فإن ملفًا واحدًا في جذر المستودع يصل إلى كل جلسة. أضف كتلة قصيرة مثل هذه:
## API testing with Apidog CLI
This project has Apidog test scenarios. To check the API, run:
`apidog run -t <scenario_id> -e <env_id> -r cli`
- Exit code 0 means every assertion passed. Non-zero means something failed; open the report and fix it before moving on.
- The machine is already authenticated via `apidog login`. Never add an `--access-token` flag and never put a token in this file.
- If a flag is unknown, run `apidog run --help` and use the exact flag from there.
لهذا السبب تكتب CLI في CLAUDE.md بدلاً من ذكره في الدردشة. معرّف السيناريو الذي يتم كتابته في جلسة يختفي عند انتهاء تلك الجلسة. أما الذي في CLAUDE.md فهو موجود لكل زميل في الفريق ولكل تشغيل لـ Claude Code من الآن فصاعدًا. يتم تحميل الملف بالكامل عند الإطلاق ويصمد أمام أمر /compact، لذا تظل التعليمات حية طوال الجلسة.
الخطوة 2: احصل على الأمر من Apidog
<scenario_id> و <env_id> في تلك الكتلة ليستا قيمًا تخمنها. افتح سيناريو الاختبار الخاص بك في Apidog، انتقل إلى علامة التبويب CI/CD، وانسخ أمر apidog run ... الذي تم إنشاؤه. يحتوي بالفعل على معرّف السيناريو الحقيقي، ومعرّف البيئة، ومُبلغ -r cli معبأً. الصق تلك المعرفات الدقيقة في كتلة CLAUDE.md الخاصة بك.
يطبع مُبلغ -r cli نتيجة خطوة بخطوة وملخصًا مباشرة في المحطة الطرفية، وهذا هو بالضبط المخرج الذي يقرأه Claude Code ليقرر خطوته التالية. للحصول على تفصيل كامل لكل علامة، راجع دليل Apidog CLI الكامل و مرجع أمر apidog run.
الخطوة 3: اجعل Claude Code يشغل الاختبار
بعد وضع الكتلة في مكانها، ابدأ Claude Code في مستودعك:
claude
يقوم Claude Code بتحميل CLAUDE.md عند بدء تشغيله، لذا فهو يعرف بالفعل أن CLI موجود. قم بإجراء تغيير يؤثر على واجهة برمجة التطبيقات الخاصة بك، أو اطلب منه ببساطة تشغيل الفحص. يصدر Claude Code أمر apidog run من ملف CLAUDE.md الخاص بك.
هنا يهم نموذج الصلاحيات. في وضعه الافتراضي، يطلب Claude Code الموافقة قبل تشغيل أمر shell لم تتم الموافقة عليه من قبل. وافق على أمر apidog run عندما يطلب ذلك. لإيقاف طلب أمر تثق به، أضف قاعدة صلاحية بحيث يعمل CLI بدون طلب: قم بتشغيل /permissions داخل الجلسة، أو أضف قاعدة سماح لـ Bash(apidog run *) في .claude/settings.json. سيناريو اختبار للقراءة فقط ضد بيئة التجريب هو أمر آمن لإضافته إلى القائمة البيضاء. للتشغيل غير المراقب، يوجد --dangerously-skip-permissions، الذي يتخطى المطالبات بالكامل؛ احفظ ذلك لـ CI، وليس لاستخدامك اليومي.
أنت تريد أن ترى التشغيل قيد التنفيذ و Claude Code يبلغ عن الملخص ورمز الخروج، وليس مجرد جملة تدعي النجاح.
الخطوة 4: اقرأ التقرير داخل Claude Code
عندما يفشل التشغيل (يصبح "أحمر")، يحتوي التقرير على الإجابة. باستخدام -r cli، يحصل Claude Code على تفصيل قابل للقراءة في المحطة الطرفية: كل طلب، كل تأكيد، وأيها فشل مع القيمة المتوقعة مقابل القيمة الفعلية. يحدد التأكيد الفاشل الحقل الدقيق أو رمز الحالة، وهو ما يكفي عادةً لـ Claude Code لإيجاد الحل.
للحصول على تقرير يمكنك فتحه في متصفح أو تسليمه لزميل في الفريق، أضف مُبلغ HTML:
apidog run -t <scenario_id> -e <env_id> -r cli,html
يكتب مُبلغ html ملفًا ذاتيًا إلى ./apidog-reports. حافظ على cli في القائمة لكي يظل Claude Code يحصل على المخرج المضمن الذي يقرأه لتحديد خطوته التالية. لتنسيق JUnit الذي تقوم لوحات تحكم CI بتحليله والمُبلغين الآخرين، راجع تقارير اختبار Apidog CLI.
اختبار Claude Code داخل حلقته الخاصة
النقطة هي ما يحدث عندما تتوقف عن السؤال ويقوم Claude Code بتشغيل السيناريو بمفرده لأن CLAUDE.md أخبره بذلك.
تخيل Claude Code وهو يعدل مُعالجًا ينشئ استجابة سحب. تتغير حلقته: يقوم بتحرير الكود، ثم، بدلاً من إعلان النصر، يقوم بتشغيل سيناريو Apidog الخاص بك ضد بيئة التجريب، ويقرأ رمز الخروج، ويتصرف بناءً عليه. إذا كان أخضر، ينتقل. إذا كان أحمر، يفتح التقرير، ويقرأ أي تأكيد فشل (رمز الحالة، الحقل المفقود، القيمة الخاطئة)، ويحاول إصلاحًا، ويعيد التشغيل. يصبح اختبار API جزءًا من نفس حلقة التعديل والاختبار والإصلاح التي يمر بها Claude Code بالفعل في اختبارات الوحدة الخاصة بك. لقد كتبت تعليمات واحدة وقام Claude بدمج الأمر في طريقة عمله بالفعل.
هذا هو نموذج التفويض ثم التحقق الذي يجعل أي سير عمل للوكيل آمنًا. يقوم Claude Code بتشغيل الأمر وقراءة النتيجة؛ بينما تستمر في تأليف السيناريوهات بصريًا في Apidog وتتحقق بشكل عرضي من أن الوكيل يقرأ رموز الخروج بصدق. للاطلاع على النمط الأوسع، راجع كيفية استخدام وكلاء AI لاختبار API و حزام اختبار Apidog AI.
تحقق من أن Claude Code يشغل CLI بالفعل
تبلغ الوكلاء عن نجاح لم يكسبوه، و Claude Code ليس استثناءً. ثلاثة فحوصات، بترتيب تكرار اكتشافها للمشاكل.
أولاً، تأكد من أن الأمر تم تشغيله على الإطلاق. يعرض Claude Code الأوامر التي نفذها ومخرجاتها المضمنة. ابحث عن السطر الحرفي apidog run ... ونتيجة تحته. إذا قال Claude إنه قام بتشغيل الاختبارات ولكنك لا ترى الأمر، فقد لخص شيئًا لم يفعله أبدًا. اطلب منه التشغيل مرة أخرى وإظهار المخرجات الأولية.
ثانيًا، تأكد من رمز الخروج، وهو الرمز الذي يهم. اسأله مباشرة: "ما هو رمز الخروج لأمر apidog run هذا؟" يخرج apidog run بـ 0 عندما تمر جميع التأكيدات، وبقيمة غير صفرية عندما يفشل أي شيء. هذا السلوك الواحد يتيح لـ Claude Code، أو لخط أنابيب، التعامل مع التشغيل كبوابة نظيفة. عندما يقول نص Claude "الاختبارات مرت" ولكن رمز الخروج غير صفري، فإن رمز الخروج هو الصحيح.
ثالثًا، تأكد من أنه استخدم السيناريو الحقيقي. إذا فشل التشغيل بـ "السيناريو غير موجود"، فقد يكون Claude قد اخترع أو نسي معرّفًا. أعد التحقق من قيم -t و -e مقابل CLAUDE.md والأمر الذي أنشأه Apidog في علامة التبويب CI/CD. المعرفات في CLAUDE.md هي الحقيقة.
اختياري: ربط خادم Apidog MCP
تشغيل apidog run من CLAUDE.md يغطي معظم ما تحتاجه. للمضي قدمًا خطوة أخرى، قم بربط خادم MCP بحيث يمكن لـ Claude Code قراءة مواصفات API الخاصة بك أثناء كتابة الكود، وليس فقط الاختبار بعد الواقعة.
يدعم Claude Code بروتوكول Model Context Protocol. يمكنك إضافة خادم باستخدام claude mcp add ... أو عن طريق عمل commit لملف .mcp.json في جذر مشروعك واختيار --scope project ليحصل عليه الفريق بأكمله. يكشف خادم Apidog MCP مواصفات API الخاصة بك عبر MCP، بحيث يقرأ Claude المخطط الخاص بك أثناء قيامه بالترميز. فكر في الأمر على أنه تقسيم للعمل: CLI يشغل الاختبارات، و MCP يزود الوكيل بالمواصفات.
عندما يخطئ Claude Code
تظهر بعض الأخطاء غالبًا أثناء الإعداد.
يتجاهل كتلة CLAUDE.md. إذا قام Claude بتشغيل أمر عام أو لم يشغل أي أمر على الإطلاق، فقد لا تكون الكتلة قيد التحميل. تأكد من أن اسم الملف هو CLAUDE.md بالضبط وأنه موجود في جذر مستودعك أو في دليل أبوي لدليلك الحالي. قم بتشغيل /memory داخل الجلسة لسرد الملفات التي قام Claude بتحميلها فعليًا؛ إذا لم يكن ملفك موجودًا هناك، فلن يتمكن Claude من رؤيته. إعادة تشغيل الجلسة تفرض قراءة جديدة.
يمرر رمز وصول على أي حال. إذا حاول Claude إضافة --access-token، فهو يخمن من الأمثلة العامة. تخبره الكتلة بالفعل بعدم فعل ذلك، حيث يتم توثيق الجهاز عبر apidog login. عزز هذا السطر، ولا تضع أبدًا رمزًا حقيقيًا في CLAUDE.md. لمعرفة كيفية توثيق الجهاز مرة واحدة، راجع مصادقة Apidog CLI.
يخترع علامة. يعني خطأ "خيار غير معروف" أن Claude خمن علامة لا تحتوي عليها نسختك. اطلب منه تشغيل apidog run --help وانسخ العلامة الدقيقة من هناك، والتي تكون دائمًا صحيحة لنسختك المثبتة.
يبلغ عن نجاح في تشغيل فاشل. هذا هو الأكثر تكلفة، والسبب في وجود قاعدة رمز الخروج في CLAUDE.md وخطوة التحقق الخاصة بك. عندما لا يتفق الملخص ورمز الخروج، فإن رمز الخروج هو الذي يرجح.
من وكيل يومي إلى حلقة مختبرة
هذا هو الإعداد. قم بتثبيت apidog-cli مرة واحدة باتباع دليل التثبيت، أضف كتلة Apidog قصيرة إلى ملف CLAUDE.md في مستودعك، وسيعرف Claude Code كيفية تشغيل اختبارات API الخاصة بك وقراءة النتيجة داخل نفس الحلقة التي يستخدمها بالفعل لتحرير الكود. يتم اكتشاف نقطة نهاية معطلة بينما لا يزال Claude يعمل على التغيير، وليس بعد إطلاقه.
يتم تشغيل اختبار خلف واجهة مستخدم رسومية عندما ينقر إنسان؛ ويتم تشغيل أمر من سطر واحد كلما قرر Claude ذلك. تستمر في بناء السيناريوهات بصريًا في Apidog، ويقوم وكيلك بتشغيلها حيث لا تراقب. قم بتنزيل Apidog، أنشئ سيناريو واحدًا، أسقط أمر apidog run الخاص به في CLAUDE.md، وشاهد Claude يلتقطه في التغيير التالي. عندما تكون مستعدًا لتشغيل نفس الأمر في خط أنابيب بدون وجود Claude، يغطي Apidog CLI في GitHub Actions الأسرار والمُبلغين وبوابة رمز الخروج.