يقوم وكيل Cursor بالفعل بتحرير الملفات، وتشغيل محطتك الطرفية، وقراءة الإخراج، وإصلاح ما أفسده. الخطوة التالية هي وضع اختبارات API الخاصة بك في تلك الحلقة: دع Cursor يقوم بتشغيل سيناريوهات Apidog الحقيقية، واقرأ ما إذا كانت ناجحة أم فاشلة، واستمر. الجزء الذي يجعل هذا العمل ممكنًا هو مشغل سطر أوامر يمكن لـ Cursor استدعائه.
هذا المشغل هو Apidog CLI، وهو حزمة npm تُسمى apidog-cli. يقوم بتشغيل سيناريوهات الاختبار التي أنشأتها بصريًا في Apidog من المحطة الطرفية ويخرج برمز حالة يمكن لـ Cursor التصرف بناءً عليه. يغطي هذا الدليل النصف الخاص بـ Cursor: ملف القاعدة الذي يعلم Cursor سير عملك، والموجه الذي يقوم بتشغيل الاختبار، وكيف يندمج التشغيل في حلقة التحرير-الاختبار-الإصلاح الخاصة به، وخادم MCP الاختياري الذي يقدم لـ Cursor مواصفات API الخاصة بك أثناء كتابته للتعليمات البرمجية.
إذا لم يتم تثبيت CLI بعد، فابدأ بـ كيفية تثبيت Apidog CLI باستخدام وكيل برمجة الذكاء الاصطناعي، والذي يوضح لـ Cursor عملية التثبيت والمصادقة. عد عندما يطبع apidog --version رقمًا. تحتاج أيضًا إلى حساب Apidog يحتوي على سيناريو اختبار واحد محفوظ على الأقل. قم بتنزيل Apidog إذا لم يكن لديك واحد.
ماذا يعني "استخدام CLI في Cursor"
لا يوجد مكون إضافي لـ Apidog لـ Cursor، ولا تحتاج إلى واحد. يقوم وكيل Cursor بالفعل بتشغيل أوامر shell في محطة مشروعك. لذا فإن استخدام Apidog CLI في Cursor يعني ثلاثة أشياء:
- علم Cursor سير العمل مرة واحدة بقاعدة مشروع، بحيث يعرف الأمر، والعلامات، وأن رمز الخروج هو مصدر الحقيقة.
- اجعل الوكيل يقوم بتشغيل
apidog runكخطوة عادية في حلقته، تمامًا كما يقوم بتشغيل اختبارات الوحدات الخاصة بك. - اختياريًا، قم بتوصيل خادم Apidog MCP، حتى يتمكن Cursor من قراءة مواصفات API الخاصة بك أثناء كتابته للتعليمات البرمجية التي تتحقق منها تلك الاختبارات.
القاعدة هي ما يجعل هذا الدليل مصممًا لـ Cursor بدلاً من كونه دليلًا عامًا لـ "فتح محطة طرفية والكتابة".
الخطوة 1: إضافة قاعدة مشروع
يقرأ Cursor قواعد المشروع من دليل .cursor/rules في جذر مستودعك. كل قاعدة هي ملف .mdc يحتوي على كتلة frontmatter صغيرة، يتم التحكم في إصدارها جنبًا إلى جنب مع التعليمات البرمجية الخاصة بك بحيث يحصل الفريق بأكمله على نفس السلوك.
قم بإنشاء واحدة بطريقتين: اكتب /create-rule في الدردشة ووصف ما تريد، أو افتح Cursor Settings > Rules, Commands، وانقر فوق + Add Rule. في كلتا الحالتين تحصل على ملف تحت .cursor/rules.
احفظ هذا كـ .cursor/rules/apidog-cli.mdc:
---
description: How to run Apidog API tests from the terminal
alwaysApply: false
---
# Running Apidog API tests
This project has API test scenarios in Apidog. Run them with the
apidog-cli, which is installed globally and already authenticated.
- The command is `apidog run`. The binary is `apidog`.
- Run a single scenario by ID: `apidog run -t <scenarioId> -e <environmentId> -n 1 -r cli`
- `-t` is the test scenario ID, `-e` is the environment ID.
- `-n 1` runs it once. `-r cli` prints a readable report to the terminal.
- Do not pass `--access-token`. Auth is handled by a prior `apidog login`.
- The exit code is the source of truth: `0` means every assertion passed,
non-zero means a failure. Report the exit code, not just a summary.
- If a flag is unknown, run `apidog run --help` and use the exact flag from there.
Never guess at flag names.
- After changing code that touches an endpoint, run the relevant scenario
and read the result before claiming the change works.
الـ frontmatter مهم. description بالإضافة إلى alwaysApply: false يجعل هذه القاعدة قابلة للتطبيق بذكاء: يقوم Cursor بسحبها عندما تكون الدردشة حول تشغيل الاختبارات، بدلاً من استهلاك السياق في كل محادثة. قم بتعيين alwaysApply: true لإبقائها دائمًا في النطاق. لتحديد نطاقها لنوع ملف معين، قم بحذف الوصف وأضف سطر globs، وسيقوم Cursor بإرفاقها تلقائيًا عند فتح ملف مطابق.
المحتوى يقوم بالعمل الحقيقي. يثبت شكل الأمر، ويقول من أين تأتي المصادقة، ويحدد السطر الذي يحافظ على أمان الوكيل: يفوز رمز الخروج على النثر. يقرأ الوكلاء أحيانًا تقريرًا فاشلاً ويقولون "يبدو جيدًا". كتابة هذه القاعدة مرة واحدة يعني أنك لست مضطرًا لاكتشافها يدويًا.
الخطوة 2: الحصول على الأمر من Apidog
قبل أن تطلب من الوكيل تشغيل أي شيء، احصل على أمر معروف بأنه جيد. لا تجعل Cursor يخمن المعرفات.
افتح سيناريو الاختبار الخاص بك في Apidog، وانتقل إلى علامة التبويب CI/CD الخاصة به، واختر خيار سطر الأوامر. يقوم Apidog بإنشاء أمر apidog run الكامل مع معرف السيناريو ومعرف البيئة ورمز الوصول المعبأ بالفعل:
apidog run --access-token YOUR_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r cli
605067 هو معرف سيناريو الاختبار و1629989 هو معرف البيئة؛ ستختلف المعرفات الخاصة بك. نظرًا لأنك قمت بمصادقة CLI أثناء التثبيت، قم بحذف جزء --access-token واحتفظ بالمعرفات. هذا هو الأمر الذي أمرت به قاعدتك Cursor باستخدامه.
الخطوة 3: اجعل الوكيل يقوم بتشغيل الاختبار
افتح وكيل Cursor (وضع الدردشة الذي يقوم بتشغيل أوامر المحطة الطرفية، وليس التحرير المضمن). مع وجود القاعدة في مكانها، يكون الموجه قصيرًا:
قم بتشغيل سيناريو اختبار Apidog الخاص بي واعرض لي الإخراج الكامل وأخبرني برمز الخروج.
يقترح Cursor الأمر، وبعد موافقتك عليه، يقوم بتشغيله في المحطة الطرفية المدمجة:
apidog run -t 605067 -e 1629989 -n 1 -r cli
بشكل افتراضي، يطلب Cursor الإذن قبل تنفيذ أمر طرفي، لذلك ترى بالضبط ما هو على وشك تشغيله. وافق عليه، ويقوم الوكيل بتشغيل السيناريو، ثم يقرأ التنفيذ والملخص.
التحقق الخاص بك: انظر إلى رمز الخروج، وليس الملخص. يخرج apidog run برمز 0 عندما تمر جميع التأكيدات وبقيمة غير صفرية عندما يفشل أحدها. هذا السلوك هو السبب الرئيسي وراء عمل هذا كبوابة، لـ CI وللوكيل. إذا قال Cursor "اجتازت الاختبارات" ولكن رمز الخروج كان غير صفري، فهو خاطئ؛ ثق بالرمز. هذا هو الفشل الدقيق الذي تمنعه قاعدة الخطوة 1.
للحصول على تنسيق تقرير مختلف أو المزيد من التكرارات، اطلب من الوكيل تشغيل apidog run --help ليقرأ قائمة العلامات الحقيقية للإصدار المثبت لديك. دليل Apidog CLI الكامل يوثق كل علامة، بما في ذلك التقارير html وjson وjunit والتكرار المعتمد على البيانات.
الخطوة 4: قراءة التقرير داخل Cursor
يقوم مُبلغ -r cli بطباعة النتائج إلى المحطة الطرفية التي يقرأها Cursor بالفعل، مما يجعله مناسبًا لعمل الوكيل. يرى الوكيل نفس الأسطر التي تراها: أي سيناريو تم تشغيله، كل طلب، كل تأكيد، والعدد النهائي للنجاح أو الفشل.
عندما يصبح التشغيل أحمر (فاشلًا)، يحدد التقرير التأكيد الفاشل، والقيمة المتوقعة، وما أرجعه نقطة النهاية. نظرًا لأن هذا النص موجود في سياق الوكيل، تابع في نفس الدردشة:
فشل السيناريو. اقرأ التأكيد الفاشل في التقرير، وابحث عن المعالج الذي ينتج هذا الحقل، واقترح إصلاحًا. ثم أعد تشغيل السيناريو واعرض لي رمز الخروج الجديد.
الآن الاختبار هو جزء من الحلقة. يقوم Cursor بتحرير المعالج، ويعيد تشغيل apidog run، ويقرأ رمز الخروج الجديد، ثم ينتقل أو يحاول مرة أخرى. تعيش فحوصات API الخاصة بك في نفس دورة التحرير-الاختبار-الإصلاح التي يستخدمها Cursor لاختبارات الوحدات، باستثناء أنها تعمل ضد نقاط نهاية حقيقية. بالنسبة للنمط الأوسع، يغطي كيفية استخدام وكلاء الذكاء الاصطناعي لاختبار API مكان ملاءمته ومكان عدم ملاءمته.
اختياري: توصيل خادم Apidog MCP
يتيح لك CLI لـ Cursor تشغيل اختباراتك. يتيح خادم Apidog MCP لـ Cursor قراءة مواصفات API الخاصة بك أثناء كتابته للتعليمات البرمجية. الاثنان يتراكمان: يغذي خادم MCP مخططك لـ Cursor بحيث يقوم بإنشاء تعليمات برمجية مطابقة للعقد، ويتحقق CLI من تلك التعليمات البرمجية مقابل سيناريوهات حقيقية.
يدعم Cursor خوادم MCP من خلال تهيئة JSON. ضع الخوادم المخصصة للمشروع في .cursor/mcp.json في جذر مستودعك، أو الخوادم العامة في ~/.cursor/mcp.json. الشكل عبارة عن كائن mcpServers مفتاح باسم، كل منها يحتوي على command، ومصفوفة args، وقيم env اختيارية:
{
"mcpServers": {
"apidog": {
"command": "npx",
"args": ["-y", "apidog-mcp-server@latest", "--project=YOUR_PROJECT_ID"],
"env": {
"APIDOG_ACCESS_TOKEN": "YOUR_ACCESS_TOKEN"
}
}
}
}
ملاحظتان. MCP مقيد بمفتاح تبديل في بعض عمليات التثبيت، لذا افتح إعدادات Cursor، وابحث عن قسم بروتوكول سياق النموذج (Model Context Protocol)، وتأكد من تمكين خادم Apidog. وإذا قمت بتثبيت .cursor/mcp.json، فلا تقم بترميز الرمز المميز مباشرة؛ قم بالإشارة إلى متغير بيئة. للإعداد الكامل، بما في ذلك مكان الحصول على معرف المشروع والرمز المميز، راجع دليل خادم Apidog MCP. للحصول على سير عمل مجمع وقابل لإعادة الاستخدام بدلاً من توصيله يدويًا، يوضح دليل Apidog CLI مع مهارات Claude الإصدار القائم على المهارات.
من الحلقة المحلية إلى CI
بمجرد أن يقوم Cursor بتشغيل السيناريو محليًا والتصرف بناءً على رمز الخروج، تكون قد قمت بالتحقق من الأمر الدقيق الذي ستستخدمه مسار التوصيل الخاص بك. القفزة إلى CI صغيرة: نفس apidog run، مع تمرير الرمز المميز كسِر مقنع بدلاً من تسجيل دخول مخزن. يمكنك حتى أن تطلب من Cursor كتابة الخطوة، لأنه يعرف الأمر من قاعدتك:
توجد آليات هذه الخطوة (الأسرار، التقارير، بوابة رمز الخروج) في Apidog CLI في GitHub Actions. نفس الأمر يعمل الآن في ثلاثة أماكن: محطتك الطرفية، حلقة وكيل Cursor، و CI، وكلها تثق بنفس رمز الخروج.
المشكلات الشائعة
القاعدة لا تنطبق. مع description و alwaysApply: false، يقوم Cursor بتحميل القاعدة فقط عندما يرى أن الدردشة ذات صلة. إذا لم يقم اختبار الجلسة بالتقاطها، فاذكرها باستخدام @apidog-cli في الدردشة، أو قم بالتبديل إلى alwaysApply: true.
لا يمكن للوكيل تشغيل الأمر. إذا كان يقترح الأوامر فقط بدلاً من تشغيلها، فمن المحتمل أنك في وضع التحرير بدلاً من الوكيل، أو أنك فاتتك مطالبة الموافقة. تأكد من أنك في دردشة الوكيل ووافق عندما يطلب Cursor. إذا فشلت عمليات التشغيل الطرفية تمامًا، فعادة ما تكون مشكلة PATH "apidog: command not found" التي يغطيها دليل التثبيت.
apidog whoami يظهر أنك غير مصادق. يتم تخزين معلومات تسجيل الدخول على جهازك، وليس في Cursor. قم بتشغيل apidog login --with-token بنفسك باستخدام رمز مميز جديد من Apidog، ثم اطلب من الوكيل التأكيد باستخدام apidog whoami. احتفظ بالرمز المميز بعيدًا عن الدردشة.
يخترع علامة. إذا فشل التشغيل بخطأ "خيار غير معروف"، فقد خمن الوكيل علامة غير موجودة في إصدارك. اطلب منه تشغيل apidog run --help وانسخ العلامة الدقيقة من هناك.
الخلاصة
إعداد Cursor هو ملف واحد وعادة واحدة: قاعدة .cursor/rules/apidog-cli.mdc التي تحدد الأمر، ومصدر المصادقة، وقاعدة رمز الخروج، بالإضافة إلى عادة السماح للوكيل بتشغيل apidog run والتحقق من رمز الخروج بنفسك. أضف خادم Apidog MCP، ويمكن لـ Cursor أيضًا قراءة مواصفاتك أثناء كتابته للتعليمات البرمجية.
تستمر في تأليف السيناريوهات بصريًا في Apidog؛ يقوم Cursor فقط بتشغيلها. من هنا، وجه نفس الأمر إلى مسار التوصيل الخاص بك باستخدام Apidog CLI في GitHub Actions، أو اقرأ المرجع الكامل للعلامات في دليل Apidog CLI الكامل.