إذا كنت تقوم بتشغيل اختبارات API من inso، واجهة سطر الأوامر (CLI) الخاصة بـ Kong Insomnia، وكنت تفكر في التغيير، فإن هذا الدليل يرشدك خلال العملية من البداية إلى النهاية. ستتعرف على كيفية تصدير مواصفاتك وحزم اختبارك من Insomnia، وإحضارها إلى Apidog، وإعادة كتابة أوامر inso run الخاصة بك كأوامر apidog run. يوجد جدول أوامر "قبل/بعد" حتى تتمكن من مطابقة نصوص CI البرمجية الموجودة لديك سطرًا بسطر.
لماذا تهاجر الفرق من inso إلى Apidog CLI
inso أداة قوية. إنها تجلب تنفيذ الطلبات، وفحص Spectral linting، واختبارات الوحدات إلى الطرفية، وتقرأ من دليل .insomnia الذي أنشأه Git Sync الخاص بـ Insomnia. إذا كان سير العمل هذا يناسبك، فلا توجد قاعدة تقول إنه يجب عليك المغادرة.
تبدأ المشكلة عادةً بتطبيق Insomnia نفسه، وليس واجهة سطر الأوامر (CLI). هناك أمران يدفعان معظم عمليات البحث عن الهجرة:
- الحساب السحابي المطلوب. قدم Insomnia 8، الذي صدر عام 2023، حسابًا سحابيًا/تسجيل دخول إلزاميًا فاجأ العديد من الفرق. كان العديد من المطورين يرغبون في عميل يعمل محليًا أولاً، لكنهم واجهوا جدار تسجيل الدخول بدلاً من ذلك.
- فقدان البيانات ومشكلات الترحيل. واجه بعض المستخدمين حوادث فقدان بيانات وترحيل خلال هذا الانتقال. إذا مررت بواحدة، فأنت تعرف التكلفة بالفعل. إذا كنت تتعافى من إحداها الآن، فإن هذه الإرشادات تساعدك: استعادة وتصدير بيانات Insomnia ودليل استعادة بيانات Insomnia 8 والترحيل الأكثر تفصيلاً.
السبب الآخر هو التوحيد. مع inso، تكون واجهة سطر الأوامر جزءًا واحدًا من مجموعة أدوات: Insomnia للطلبات، وSpectral للفحص، وأدوات منفصلة للمحاكاة والوثائق. يدمج Apidog التصميم، والتصحيح، والاختبار، والمحاكاة، والوثائق في منصة واحدة، وتشغل واجهة سطر الأوامر جانب الاختبار في تلك المنصة. أجزاء متحركة أقل، ومصدر واحد للحقيقة.
إذا كنت ترغب في السياق الأوسع قبل الالتزام، فإن مقارنة Apidog بـ Insomnia واختيار الأداة المناسبة لتطوير API بين Insomnia و Apidog يوضحان المفاضلات للتطبيقات الكاملة، وليس لواجهات سطر الأوامر.
قبل أن تبدأ: ما الذي ينتقل وما الذي لا ينتقل
ضع التوقعات مقدمًا حتى لا يفاجئك شيء في منتصف عملية الترحيل.
| الأصل في Insomnia | هل ينتقل إلى Apidog؟ | كيفية النقل |
|---|---|---|
| وثائق OpenAPI / التصميم | نعم | تصدير إلى YAML/JSON، استيراد إلى Apidog |
| مجموعات الطلبات | نعم | تصدير، ثم استيراد |
| البيئات والمتغيرات | نعم | إعادة إنشائها كبيئات Apidog |
حزم اختبار الوحدات (inso run test) |
جزئيًا | إعادة البناء كسيناريوهات اختبار Apidog |
تكوين فحص Spectral (inso lint spec) |
لا يوجد تطابق 1:1 | انظر الملاحظة الصادقة أدناه |
ملاحظة صادقة: inso lint spec يشغل Spectral، وهو أداة فحص OpenAPI من Stoplight، وهذه نقطة قوة حقيقية. Apidog CLI لا يأتي مع أداة فحص مواصفات مستقلة، أو دليل أنماط، أو أمر تقسيم، أو دمج، أو تجميع. يقوم Apidog بالتحقق من صحة مواصفاتك عند استيرادها، لذلك تظهر المشاكل الهيكلية في وقت الاستيراد، ولكن إذا كان سير عملك يعتمد على مجموعات قواعد Spectral مخصصة كبوابة، فاحتفظ بـ Spectral في CI الخاص بك جنبًا إلى جنب مع Apidog. لا تتوقع apidog lint. إنه غير موجود، والتظاهر بخلاف ذلك سيضرك لاحقًا.
الخطوة 1: تصدير مواصفاتك واختباراتك من Insomnia
يمكن لـ inso كتابة مستند التصميم الخاص بك مباشرة إلى ملف. تتم الإشارة إلى المواصفات بالاسم، وهو نفس الاسم الذي تراه في تطبيق Insomnia:
# Export an OpenAPI design document to a YAML file
inso export spec "My API Design" --output my-api.yaml
إذا لم يتمكن inso من العثور على بياناتك، فوجهه إلى المصدر الصحيح. بشكل افتراضي، يقرأ من دليل .insomnia في دليل العمل أو دليل بيانات تطبيق Insomnia. تجاوز ذلك باستخدام --workingDir أو --src:
inso export spec "My API Design" --workingDir ./design --output my-api.yaml
بالنسبة لمجموعات الطلبات وأي شيء لا يقوم inso بتصديره بشكل نظيف، استخدم تطبيق Insomnia نفسه: افتح التطبيق، حدد مساحة العمل الخاصة بك، واستخدم Export لإنشاء ملف OpenAPI أو Insomnia v4. احتفظ بكل من مستند التصميم وتصدير المجموعة. ستقوم باستيرادهما بشكل منفصل.
إذا كنت في منتصف عملية الاسترداد والتطبيق لا يتعاون، فإن الإرشادات التفصيلية للتصدير والاسترداد تغطي كيفية إخراج البيانات عندما تواجه مشكلة مع Git Sync أو الحساب السحابي.
الخطوة 2: الاستيراد إلى Apidog
افتح Apidog، أنشئ مشروعًا، واستورد ملف YAML أو JSON الذي قمت بتصديره للتو. يقرأ Apidog OpenAPI بشكل طبيعي، لذا فإن نقاط النهاية والمخططات وبيانات الأمثلة الخاصة بك ستصل كموارد منظمة يمكنك تحريرها ومحاكاتها واختبارها.
يمكنك أيضًا الاستيراد من واجهة سطر الأوامر كجزء من إعداد آلي، وهو أمر مفيد عندما تقوم ببرمجة انتقال على مستوى الفريق بدلاً من النقر عبر واجهة المستخدم الرسومية. يستورد Apidog OpenAPI ويدير نقاط النهاية والمخططات والبيئات والفروع وطلبات الدمج كتعليمات برمجية من الطرفية، ويصادق عبر تسجيل الدخول أو رمز الوصول. إذا كنت تقوم بإعداد واجهة سطر الأوامر لأول مرة، فإن دليل تثبيت Apidog CLI والدليل الكامل لواجهة سطر الأوامر يغطيان الإعداد وسير عمل المصادقة.
عند الاستيراد، يتحقق Apidog من صحة المواصفات. إذا كان ملف OpenAPI الخاص بك يحتوي على مشكلات هيكلية، فستكتشفها الآن بدلاً من وقت التشغيل. هذا هو أقرب نظير لـ inso lint spec، مع اختلاف واحد يستحق التكرار: إنه تحقق من الصحة، وليس مجموعة قواعد Spectral قابلة للتكوين.
الخطوة 3: مطابقة أوامرك (الجزء الذي جئت من أجله)
هذا هو جوهر عملية الترحيل. إليك كيفية ترجمة أوامر inso إلى apidog run.
| ما تريد فعله | أمر inso | المقابل في Apidog CLI |
|---|---|---|
| تشغيل حزمة اختبار وحدات | inso run test "Smoke Suite" --env "Staging" |
apidog run --test-scenario "Smoke Suite" -e staging |
| تشغيل مجموعة | inso run collection "Checkout Flow" --env "Staging" |
apidog run "Checkout Flow" -e staging |
| تشغيل سكريبت مسمى | inso script ci-smoke --env <env-id> |
apidog run -e <env-id> (مربوط في سكريبت CI الخاص بك) |
| فحص مواصفات OpenAPI | inso lint spec "My API Design" |
لا يوجد تطابق 1:1؛ Apidog يتحقق من صحتها عند الاستيراد |
| تصدير مواصفات إلى ملف | inso export spec "My API Design" --output api.yaml |
يتم التعامل معه بواسطة استيراد/تصدير Apidog، وليس خطوة تشغيل |
بعض الملاحظات حول المطابقة:
- البيئات. يستخدم
inso--env "name". ويستخدم Apidog-e(--env). كلاهما يختار عنوان URL الأساسي والمتغيرات الخاصة بالبيئة لتطبيقها. أعد إنشاء بيئات Insomnia الخاصة بك كبيئات Apidog أولاً، ثم أشر إليها بالاسم أو المعرّف. - حزم الاختبار تصبح سيناريوهات اختبار. حيث يشغل
inso run testحزمة اختبار وحدات Insomnia، يشغل Apidog سيناريوهات الاختبار. يتطابق المفهوم بوضوح: طلبات مرتبة مع تأكيدات. ستقوم بإعادة بناء الحزمة مرة واحدة في Apidog، ثم ستعمل في كلapidog run. - كان
inso scriptعبارة عن توجيه غير مباشر. إذا قمت بتغليف الأوامر خلف نصوص برمجية مسماة، فما عليك سوى استدعاءapidog runمباشرة في خطوة CI الخاصة بك، أو تغليفه في نص npm/make الخاص بك.
لإجراء مقارنة أعمق بين الأوامر، يتناول Apidog CLI مقابل inso (Insomnia CLI) كل علامة على حدة. إذا كنت قد استخدمت Newman أو Postman CLI في السابق، فإن Apidog CLI مقابل Newman وApidog CLI مقابل Postman CLI يغطيانها أيضًا.
الخطوة 4: نقل أدوات الإبلاغ الخاصة بك
يعتمد inso على مخرجات الاختبار الخاصة به وتقارير بأسلوب JUnit لـ CI. يوفر لك Apidog أدوات إبلاغ بتنسيقات CLI و HTML و JSON، بحيث يمكن لعملية البناء الخاصة بك طباعة نتائج قابلة للقراءة البشرية على وحدة التحكم وإصدار مادة قابلة للقراءة آليًا في نفس الوقت:
# Run a scenario and emit both a CLI summary and an HTML report
apidog run --test-scenario "Smoke Suite" -e staging -r cli,html
اختر json عندما تحتاج أداة لاحقة إلى تحليل النتائج، وhtml عندما يراجع إنسان عملية البناء، وcli لتغذية وحدة التحكم المباشرة. يمكنك أيضًا دفع النتائج إلى تقارير اختبار Apidog السحابية باستخدام --upload-report حتى يرى الفريق بأكمله التشغيل دون البحث في سجلات CI. يغطي دليل تقارير الاختبار التنسيقات بالتفصيل.
الخطوة 5: نقل الاختبارات القائمة على البيانات
إذا كانت حزم Insomnia الخاصة بك تتكرر على البيانات، فإن Apidog يدعم الاختبارات القائمة على البيانات بشكل طبيعي. قم بتغذية مجموعة بيانات CSV أو JSON باستخدام -d وسيعمل السيناريو مرة واحدة لكل صف:
apidog run --test-scenario "Login Matrix" -e staging -d ./users.csv -r cli,json
هذا أحد الأماكن التي يميل فيها Apidog إلى أن يكون أقل تعقيدًا من ربط البيانات الخارجية عبر inso. يتناول دليل الاختبار القائم على البيانات تنسيقات مجموعات البيانات وربط المتغيرات.
الخطوة 6: ربطها بـ CI
الخطوة الأخيرة هي تبديل الأمر في مسار العمل الخاص بك. على الأرجح كانت خطوة GitHub Actions أو GitLab القديمة تبدو هكذا:
# قبل: inso في CI
inso run test "Smoke Suite" --env "CI" --reporter junit
المقابل في Apidog:
# بعد: Apidog CLI في CI
apidog run --test-scenario "Smoke Suite" -e ci -r cli,json --upload-report
صادق المُشغل باستخدام رمز وصول مخزن كسر CI سري، بنفس الطريقة التي تتعامل بها مع أي خطوة تتطلب بيانات اعتماد. يحتوي دليل مسار عمل CI/CD ودليل GitHub Actions على ملفات سير عمل جاهزة للنسخ واللصق. لتفاصيل الرمز المميز وتسجيل الدخول، راجع مصادقة Apidog CLI.
إذا احتفظت بـ Spectral للفحص (موصى به إذا كان لديك قواعد مخصصة)، فإن مسار عملك الآن يحتوي على بوابتين: Spectral يفحص المواصفات، و Apidog يشغل الاختبارات. هذه حالة نهائية معقولة تمامًا، وهي صادقة بشأن ما تفعله كل أداة على أفضل وجه.
إبقاء Spectral في حلقة العمل
لتوضيح الأمر الوحيد الذي لا ينتقل: إذا كان الفحص جزءًا من عقدك، فلا تتجاهله. Spectral مفتوح المصدر ويعمل بشكل جيد خارج Insomnia. يبدو CI الهجين النموذجي هكذا:
# الفحص باستخدام Spectral (محتفظ به من إعداد inso الخاص بك)
npx @stoplight/spectral-cli lint my-api.yaml
# الاختبار باستخدام Apidog CLI
apidog run --test-scenario "Smoke Suite" -e ci -r cli,json
لا تخسر شيئًا من جانب الفحص وتكسب منصة Apidog المتكاملة للتصميم والمحاكاة والاختبار والوثائق في كل شيء آخر. هذه هي المقايضة الدقيقة، وهي جيدة لمعظم الفرق.
inso مقابل Apidog CLI: نظرة سريعة
| القدرة | inso (Insomnia CLI) | Apidog CLI |
|---|---|---|
| تشغيل المجموعات / الحزم | نعم | نعم |
| البيئات | --env |
-e / --env |
| فحص OpenAPI | نعم (Spectral) | لا يوجد أمر مستقل (يتحقق عند الاستيراد) |
| اختبار قائم على البيانات | محدود | نعم (-d, CSV/JSON) |
| تنسيقات التقرير | CLI, JUnit | CLI, HTML, JSON, تحميل سحابي |
| المورد كتعليمات برمجية | يقرأ دليل .insomnia |
نقاط النهاية، المخططات، الفروع، طلبات الدمج |
| جزء من منصة موحدة | Insomnia + أدوات خارجية | منصة واحدة (تصميم، محاكاة، وثائق، اختبار) |
| حساب سحابي مطلوب للتطبيق | نعم (Insomnia 8+) | حساب Apidog، سهل الاستخدام محليًا |
الأسئلة الشائعة
هل سيتم استيراد مواصفات OpenAPI الخاصة بـ Insomnia إلى Apidog بدون تعديلات؟ عادةً نعم. يقرأ Apidog OpenAPI بشكل طبيعي ويتحقق من صحته عند الاستيراد. إذا أشار التحقق إلى شيء ما، فعادة ما تكون مشكلة هيكلية حقيقية في المواصفات، وإصلاحها مرة واحدة يفيد كل أداة تالية.
هل يحتوي Apidog CLI على أمر lint مثل inso lint spec؟ لا. يتحقق Apidog من صحة المواصفات عند الاستيراد، ولكن لا يوجد أداة فحص سطر أوامر مستقلة أو أمر دليل أنماط. إذا كنت تعتمد على مجموعات قواعد Spectral مخصصة، فاحتفظ بـ Spectral في مسار عملك بجانب apidog run. للمقارنة جنبًا إلى جنب، انظر Apidog CLI مقابل Redocly CLI، حيث أن Redocly CLI يتضمن أداة فحص.
هل يمكنني تشغيل Apidog CLI في CI بنفس الطريقة التي شغلت بها inso؟ نعم. قم بتبديل الأمر، وصادق باستخدام رمز وصول من سر CI، واختر أدوات الإبلاغ الخاصة بك. يحتوي دليل CI/CD على أمثلة كاملة لسير العمل.
ماذا يحدث لحزم اختبار وحدات Insomnia الخاصة بي؟ ستقوم بإعادة بنائها كسيناريوهات اختبار Apidog. ينتقل الهيكل مباشرة: طلبات مرتبة بالإضافة إلى تأكيدات. إنها عملية إعادة بناء لمرة واحدة، وبعد ذلك تعمل في كل apidog run.
أنا أهاجر بعيدًا عن Insomnia بسبب حادث فقدان البيانات. من أين أبدأ؟ استرجع بياناتك أولاً باستخدام دليل الاسترداد والتصدير، ثم اتبع الخطوة 2 أعلاه لاستيراد التصدير النظيف إلى Apidog.
خاتمة
الهجرة من inso إلى Apidog CLI هي في الغالب مهمة ترجمة: قم بتصدير مواصفاتك وحزمك، واستوردها إلى Apidog، وأعد كتابة inso run test و inso run collection كـ apidog run، وقم بتبديل --env إلى -e، ووجه أدوات الإبلاغ الخاصة بك إلى مخرجات Apidog بتنسيقات CLI/HTML/JSON. احتفظ بـ Spectral إذا كنت تستخدم الفحص، لأن Apidog يتحقق من الصحة عند الاستيراد ولكنه لا يحل محل مجموعة قواعد مخصصة.
المكافأة هي منصة واحدة بدلاً من مجموعة أدوات عليك الاستمرار في تجميعها. هل أنت مستعد لتجربتها؟ حمل Apidog وقم بتشغيل أول أمر apidog run مقابل المواصفات التي قمت بتصديرها للتو.