إذا كنت قد استخدمت عميل Insomnia API، فلديك مكان رسومي لإرسال الطلبات، وتصميم مواصفات OpenAPI، وكتابة الاختبارات. لكن الأدوات الرسومية تتوقف عند حدود جهازك. في اللحظة التي تريد فيها تشغيل نفس الاختبارات داخل مسار CI، أو تريد تدقيق مواصفة في كل طلب سحب، فأنت بحاجة إلى شيء يعيش في الطرفية. هذا الشيء هو inso.
يشرح هذا الدليل ماهية inso، وكيفية تثبيته، والأوامر الدقيقة التي ستستخدمها يوميًا، وكيف يعثر على مواصفاتك ومجموعاتك، وأين تظهر حدوده. بحلول النهاية، ستعرف ما إذا كانت واجهة سطر أوامر inso تناسب سير عملك، وما الذي يجب اللجوء إليه إذا لم تكن كذلك.
ما هو inso؟
inso هو الرفيق الذي يعمل بسطر الأوامر لـ Insomnia، عميل API مفتوح المصدر الذي تديره Kong الآن. يأخذ ثلاثة أشياء يفعلها Insomnia في واجهة المستخدم الخاصة به ويجعلها قابلة للبرمجة: تشغيل الاختبارات، تنفيذ مجموعات الطلبات، وتدقيق مواصفات API. وهذا يجعله الجسر بين Insomnia على سطح مكتبك والفحوصات الآلية التي تريدها في CI/CD.
النسخة المختصرة من "ما هو inso": إنه كيف تقوم بتشغيل عمل Insomnia الخاص بك دون فتح Insomnia. توجهه إلى مستند تصميم أو مجموعة بالاسم، ويقوم بالتنفيذ مقابل نفس البيانات التي يعرفها تطبيقك بالفعل.
تثبيت واجهة سطر أوامر inso
لديك بعض المسارات الموثقة. اختر المسار الذي يتناسب مع طريقة عملك.
Homebrew هو الأبسط على macOS و Linux:
brew install inso
Docker هو الخيار الأنظف لمشغلي CI، حيث لا تريد إدارة مجموعة أدوات محلية:
docker pull kong/inso:latest
يمكنك أيضًا الحصول على تنزيل مباشر. تنشر Kong أرشيفات zip لنظامي التشغيل Windows و Linux و macOS على موقع توثيق CLI الخاص بـ inso، وهو مفيد عندما تريد إصدارًا مثبتًا في قطعة بناء.
تاريخيًا، تم توزيع inso أيضًا على npm باسم insomnia-inso. لا يزال هذا المسار موجودًا، لكن المسارات الموثقة والموصى بها الآن هي Homebrew و Docker والتنزيلات المباشرة. إذا كنت تقوم بإعداد شيء جديد، ففضل هذه المسارات.
تأكيد أن التثبيت تم بنجاح:
inso --version
أوامر inso الأساسية
يحتوي inso على سطح صغير ومركّز. إليك الأوامر التي ستستخدمها فعليًا، مع أمثلة حقيقية.
inso run test
تشغيل مجموعة اختبار وحدات قمت بتأليفها في Insomnia، مقابل بيئة مسماة:
inso run test "Payments API tests" --env "Staging"
يتم الإشارة إلى المجموعة والبيئة بالاسم، تمامًا كما تظهر في بيانات Insomnia الخاصة بك. يخرج الأمر inso run test بقيمة غير صفرية إذا فشل أي تأكيد، وهذا ما يجعله قابلاً للاستخدام كبوابة CI.
inso run collection
تشغيل كل طلب في مجموعة بالتسلسل، مرة أخرى مقابل بيئة مسماة:
inso run collection "Checkout flow" --env "Staging"
هذا هو أقرب مكافئ لـ "تشغيل المجلد بأكمله" في واجهة المستخدم. إنه مفيد لاختبارات التحقق السريع حيث تريد التأكد من أن سلسلة من نقاط النهاية تستجيب جميعها كما هو متوقع.
inso lint spec
التحقق من صحة مستند تصميم OpenAPI:
inso lint spec "Orders API"
تحت الغطاء، يستخدم inso lint spec Spectral، مدقق OpenAPI و JSON مفتوح المصدر من Stoplight. هذه قوة حقيقية تستحق الإشارة إليها بوضوح: تحصل على تدقيق مواصفات حقيقي قائم على القواعد مع مجموعة قواعد ناضجة، وليس فحصًا سطحيًا للنحو. إذا كان فريقك يهتم بفرض دليل الأنماط على المواصفات، فهذا الأمر هو السبب وراء احتفاظ الكثيرين بـ inso.
inso export spec
سحب مستند تصميم إلى ملف على القرص:
inso export spec "Orders API" --output orders.yaml
مفيد عندما تريد تغذية المواصفة لمولد آخر، أو الالتزام بلقطة، أو تسليمها لأداة تتوقع ملف YAML عاديًا.
inso script
تشغيل نص برمجي مسمى معرف في بيانات Insomnia الخاصة بك، مع تمرير بيئة بواسطة معرف:
inso script deploy-smoke --env env_9f2a
هذه هي مخرج الطوارئ لربط خطواتك المخصصة.
كيف يعثر inso على مواصفاتك ومجموعاتك
هذا هو الجزء الذي يربك الناس، لذا من الجدير أن نكون دقيقين. لا يقوم inso بتخزين أي شيء بنفسه. يقرأ من أحد مكانين:
- دليل
.insomniaفي دليل عملك. هذا ما ينتجه Git Sync الخاص بـ Insomnia، لذا عندما تلتزم بمشروع API الخاص بك في مستودع، يمكن لـ inso قراءته مباشرة من النسخة المستخرجة. هذا هو النمط الذي تريده لـ CI. - دليل بيانات تطبيق Insomnia، إذا كان التطبيق مثبتًا على الجهاز. هذا مناسب محليًا ولكنه عديم الفائدة على مشغل CI نظيف لم يتم تثبيت التطبيق عليه مطلقًا.
يمكنك تجاوز المصدر صراحةً:
inso lint spec "Orders API" --workingDir ./api-project
# or point at an exact source
inso run test "Payments API tests" --src ./api-project/.insomnia
النموذج الذهني الأساسي: يشير inso إلى كل شيء بالاسم (أو المعرف)، وتُحل هذه الأسماء مقابل أي مصدر بيانات عثر عليه. إذا لم يكن الاسم موجودًا في دليل .insomnia أو بيانات التطبيق، فلا يمكن لـ inso تشغيله. لا يوجد مفهوم توجيه inso إلى ملف OpenAPI منفصل والقول "اختبر هذا" ما لم يكن هذا الملف موجودًا داخل بنية مشروع Insomnia.
مثال بسيط لـ CI
فيما يلي مهمة GitHub Actions تقوم بتدقيق مواصفة وتشغيل مجموعة اختبار عند كل عملية دفع، باستخدام دليل .insomnia المتزامن مع Git والمُلتزم به في المستودع:
name: API checks
on: [push]
jobs:
inso:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install inso
run: |
curl -sSL https://github.com/Kong/insomnia/releases/latest/download/inso-linux-x64.zip -o inso.zip
unzip inso.zip && sudo mv inso /usr/local/bin/
- name: Lint the spec
run: inso lint spec "Orders API" --workingDir .
- name: Run the test suite
run: inso run test "Payments API tests" --env "CI" --workingDir .
نظرًا لأن كلا الأمرين يخرجان بقيمة غير صفرية عند الفشل، فإن المواصفة المعطلة أو التأكيد الفاشل يؤدي إلى فشل المهمة. هذه هي الفكرة الرئيسية لنقل هذه الفحوصات خارج الواجهة الرسومية.
قيود صريحة
inso جيد فيما يفعله، ولكن لديه حدود حقيقية.
إنه مرتبط بمصادر بيانات Insomnia. يجب أن تعيش مواصفاتك ومجموعاتك ومجموعات الاختبار الخاصة بك في مشروع Insomnia، يتم إظهارها إما من خلال Git Sync أو التطبيق المثبت. إذا لم يستخدم فريقك Insomnia كمصدر للحقيقة، فلن يكون لدى inso ما يعمل عليه.
يتم الإشارة إلى كل شيء بالاسم. هذا قابل للقراءة، ولكنه هش. أعد تسمية مجموعة في واجهة المستخدم وستتعطل مهمة CI التي تشفر الاسم القديم بصمت حتى التشغيل التالي. يجب أن تكون الأسماء أيضًا فريدة بما يكفي لحلها بشكل نظيف.
النطاق ضيق حسب التصميم. يقوم inso بتشغيل الاختبارات، وتشغيل المجموعات، وتدقيق المواصفات، والتصدير، وتشغيل البرامج النصية. إنه ليس منصة تصميم-نماذج-وثائق-اختبار. لأي شيء يتجاوز هذه الأفعال، ستعود إلى الواجهة الرسومية أو ستلجأ إلى أدوات أخرى.
inso مقابل البديل المتكامل
inso هو رفيق قوي في الطرفية عندما يكون Insomnia بالفعل عميلك. المفاضلة هي أنك تجمع القطع معًا: Insomnia للتصميم والتصحيح، inso لـ CI، قواعد Spectral للتدقيق، وأدوات منفصلة للنماذج والوثائق.
Apidog يتخذ موقفًا معاكسًا. يضع التصميم، النماذج، التوثيق، والاختبار في منصة واحدة، وتعمل واجهة سطر أوامر Apidog على تشغيل سيناريوهات الاختبار ومجموعاتك من نفس مصدر الحقيقة، مع اختبار يعتمد على البيانات، وتنسيقات تقارير متعددة، والموارد والفرع ككود. من العدل الإشارة هنا: لا يشحن Apidog CLI مدقق مواصفات مستقل بالطريقة التي يفعلها inso مع Spectral، لذا إذا كان فرض دليل الأنماط على غرار Spectral هو أولويتك، فإن inso لديه ميزة حقيقية هناك. حيث يتفوق Apidog هو التكامل. أنت لا تقوم بلصق خمس أدوات معًا.
إذا كنت ترغب في مقارنة الاثنين وجهاً لوجه، فراجع Apidog CLI مقابل inso (واجهة سطر أوامر Insomnia)، أو اقرأ الخلفية الأعمق في ما هو inso (واجهة سطر أوامر Insomnia). إذا كنت قد قررت أن inso ليس هو المكان المناسب، فإن ملخص أفضل بدائل inso و دليل الترحيل من inso إلى Apidog CLI يشرحان الخطوات خطوة بخطوة. للحصول على سياق أوسع حول عملاء الواجهة الرسومية أنفسهم، يعد Apidog مقابل Insomnia و كيفية استخدام Insomnia لاختبار API نقاط بداية جيدة.
يمكنك تنزيل Apidog مجانًا إذا كنت ترغب في رؤية النهج المتكامل جنبًا إلى جنب مع إعداد inso الخاص بك.