DEV Community

Cover image for ما هو inso؟ Insomnia CLI
Yusuf Khalidd
Yusuf Khalidd

Posted on • Originally published at apidog.com

ما هو inso؟ Insomnia CLI

إذا كنت تستخدم عميل Insomnia API، فأنت تملك واجهة رسومية لإرسال الطلبات، تصميم مواصفات OpenAPI، وكتابة الاختبارات. لكن عند نقل نفس الفحوصات إلى CI/CD أو تشغيل تدقيق مواصفة API في كل Pull Request، تحتاج إلى أداة تعمل من الطرفية. هنا يأتي دور inso.

جرّب Apidog اليوم

في هذا الدليل العملي ستتعرف على inso، طريقة تثبيته، أهم أوامره اليومية، كيف يقرأ بيانات Insomnia، وكيف تستخدمه داخل GitHub Actions. في النهاية ستعرف متى يكون مناسبًا لسير عملك، ومتى تحتاج إلى بديل أكثر تكاملًا.

ما هو inso؟

inso هو واجهة سطر الأوامر الخاصة بـ Insomnia، عميل API مفتوح المصدر الذي تديره Kong. وظيفته نقل بعض إمكانات Insomnia من الواجهة الرسومية إلى الطرفية، خصوصًا:

  • تشغيل اختبارات Insomnia
  • تشغيل مجموعات الطلبات Collections
  • تدقيق مواصفات OpenAPI
  • تصدير المواصفات
  • تشغيل scripts معرفة داخل بيانات Insomnia

inso CLI

ببساطة: inso يسمح لك بتشغيل ما بنيته داخل Insomnia دون فتح Insomnia. هذا يجعله مناسبًا لفحوصات CI/CD التي تعتمد على نفس بيانات المشروع.

تثبيت inso CLI

اختر طريقة التثبيت المناسبة لبيئتك.

باستخدام Homebrew

على macOS أو Linux:

brew install inso
Enter fullscreen mode Exit fullscreen mode

باستخدام Docker

مناسب أكثر لبيئات CI التي لا تريد فيها تثبيت أدوات محلية كثيرة:

docker pull kong/inso:latest
Enter fullscreen mode Exit fullscreen mode

تنزيل مباشر

تنشر Kong ملفات zip لأنظمة Windows وLinux وmacOS عبر توثيق inso CLI. هذا مناسب إذا أردت تثبيت إصدار محدد داخل بيئة build.

تاريخيًا كان inso متاحًا عبر npm باسم insomnia-inso، لكن المسارات الموثقة والمفضلة حاليًا هي Homebrew وDocker والتنزيل المباشر.

تحقق من التثبيت:

inso --version
Enter fullscreen mode Exit fullscreen mode

أوامر inso الأساسية

واجهة inso صغيرة ومباشرة. هذه هي الأوامر التي ستستخدمها غالبًا في المشاريع اليومية.

تشغيل اختبار: inso run test

إذا كان لديك test suite داخل Insomnia باسم Payments API tests وبيئة باسم Staging:

inso run test "Payments API tests" --env "Staging"
Enter fullscreen mode Exit fullscreen mode

إذا فشل أي assertion، يُرجع الأمر exit code غير صفري. هذا يعني أنه يمكن استخدامه مباشرة كبوابة CI:

inso run test "Payments API tests" --env "CI"
Enter fullscreen mode Exit fullscreen mode

تشغيل Collection: inso run collection

لتشغيل كل الطلبات داخل Collection بالترتيب:

inso run collection "Checkout flow" --env "Staging"
Enter fullscreen mode Exit fullscreen mode

استخدم هذا عندما تريد smoke test سريعًا للتأكد من أن مجموعة endpoints تستجيب كما هو متوقع.

تدقيق OpenAPI Spec: inso lint spec

لتدقيق مواصفة API باسم Orders API:

inso lint spec "Orders API"
Enter fullscreen mode Exit fullscreen mode

يستخدم inso lint spec أداة Spectral، وهي linter مفتوح المصدر لمواصفات OpenAPI وJSON. هذا يعني أنك لا تحصل فقط على فحص syntax بسيط، بل على تدقيق قائم على قواعد يمكن استخدامه لفرض API style guide داخل الفريق.

مثال لاستخدامه كبوابة قبل الدمج:

inso lint spec "Orders API" --workingDir .
Enter fullscreen mode Exit fullscreen mode

تصدير Spec: inso export spec

لتصدير مواصفة OpenAPI من Insomnia إلى ملف محلي:

inso export spec "Orders API" --output orders.yaml
Enter fullscreen mode Exit fullscreen mode

هذا مفيد إذا كنت تريد:

  • تمرير المواصفة إلى generator خارجي
  • حفظ snapshot داخل المستودع
  • تسليم ملف YAML لأداة أخرى

تشغيل Script: inso script

لتشغيل script معرف داخل بيانات Insomnia:

inso script deploy-smoke --env env_9f2a
Enter fullscreen mode Exit fullscreen mode

هذا مناسب للخطوات المخصصة التي لا تدخل مباشرة ضمن تشغيل test suite أو collection.

كيف يعثر inso على المواصفات والمجموعات؟

inso لا يخزن بيانات API بنفسه. هو يقرأ بيانات Insomnia من أحد مصدرين:

  1. مجلد .insomnia داخل working directory

    هذا هو الخيار المناسب لـ CI. عادة ينتج هذا المجلد من Git Sync في Insomnia، ثم يتم حفظه داخل المستودع.

  2. مجلد بيانات تطبيق Insomnia المحلي

    هذا يعمل على جهازك إذا كان Insomnia مثبتًا، لكنه غير مناسب غالبًا لـ CI runner نظيف.

مثال باستخدام مجلد المشروع الحالي:

inso lint spec "Orders API" --workingDir .
Enter fullscreen mode Exit fullscreen mode

أو تحديد مصدر البيانات مباشرة:

inso run test "Payments API tests" --src ./api-project/.insomnia
Enter fullscreen mode Exit fullscreen mode

النقطة المهمة: inso يشير إلى المواصفات، الاختبارات، والمجموعات بالاسم أو المعرف. إذا لم يكن الاسم موجودًا داخل .insomnia أو بيانات التطبيق، فلن يتمكن من تشغيله.

لا يمكنك عادة تمرير ملف OpenAPI منفصل إلى inso وقول "اختبر هذا" ما لم يكن هذا الملف جزءًا من بنية مشروع Insomnia.

مثال GitHub Actions لتشغيل inso في CI

هذا workflow يقوم بتدقيق المواصفة وتشغيل test suite عند كل push:

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 .
Enter fullscreen mode Exit fullscreen mode

إذا فشل تدقيق المواصفة أو فشل أي اختبار، ستفشل مهمة CI لأن أوامر inso ترجع exit code غير صفري عند الفشل.

نمط استخدام عملي داخل الفريق

لجعل inso مستقرًا داخل CI، اتبع هذا النمط:

  1. أنشئ API project داخل Insomnia.
  2. فعّل Git Sync أو احفظ مجلد .insomnia داخل المستودع.
  3. استخدم أسماء ثابتة وواضحة للـ specs والـ test suites.
  4. أنشئ بيئة مخصصة لـ CI مثل CI.
  5. شغّل محليًا قبل رفع التغييرات: 
inso lint spec "Orders API" --workingDir .
inso run test "Payments API tests" --env "CI" --workingDir .
Enter fullscreen mode Exit fullscreen mode
  1. أضف نفس الأوامر إلى pipeline.

بهذه الطريقة يصبح نفس الاختبار الذي يعمل محليًا قابلاً للتشغيل آليًا في CI.

قيود يجب الانتباه لها

inso مفيد، لكنه محدود عن قصد.

يعتمد على بيانات Insomnia

يجب أن تكون المواصفات، المجموعات، والاختبارات موجودة داخل مشروع Insomnia. إذا لم يكن Insomnia هو مصدر الحقيقة لفريقك، فلن يكون لدى inso ما يعمل عليه.

الأسماء قد تكون هشة

الأوامر تعتمد غالبًا على أسماء مثل:

inso run test "Payments API tests" --env "CI"
Enter fullscreen mode Exit fullscreen mode

إذا غيّر شخص اسم test suite داخل Insomnia، سيفشل CI في التشغيل التالي. لذلك من الأفضل الاتفاق على أسماء ثابتة وتجنب إعادة التسمية العشوائية.

النطاق ضيق

inso يركز على:

  • تشغيل tests
  • تشغيل collections
  • تدقيق specs
  • تصدير specs
  • تشغيل scripts

هو ليس منصة كاملة للتصميم، التوثيق، mock servers، وإدارة الاختبارات. ستحتاج إلى Insomnia أو أدوات أخرى لباقي سير العمل.

inso مقابل البديل المتكامل

inso خيار جيد إذا كان Insomnia هو عميل API الأساسي لديك وتريد فقط تشغيل بعض أعماله من الطرفية. لكن سير العمل يصبح غالبًا مكونًا من عدة أدوات:

  • Insomnia للتصميم والتصحيح
  • inso للتشغيل في CI
  • Spectral للتدقيق
  • أدوات أخرى للـ mocks والتوثيق والتقارير

Apidog

Apidog يتبع نهجًا مختلفًا: يجمع التصميم، النماذج، التوثيق، والاختبار في منصة واحدة. كما تتيح واجهة سطر أوامر Apidog تشغيل سيناريوهات الاختبار والمجموعات من نفس مصدر الحقيقة، مع دعم الاختبار المعتمد على البيانات، وتنسيقات تقارير متعددة، والتعامل مع الموارد والفروع ككود.

مع ذلك، من المهم توضيح الفرق: Apidog CLI لا يوفر linter مستقلًا للمواصفات بنفس طريقة inso مع Spectral. إذا كان فرض API style guide عبر Spectral هو أولويتك الأساسية، فـ inso يملك ميزة واضحة هنا. أما إذا كنت تريد تقليل عدد الأدوات وربط التصميم والاختبار والتوثيق في سير عمل واحد، فالتكامل هو نقطة قوة Apidog.

للمقارنة التفصيلية، راجع:

يمكنك أيضًا تنزيل Apidog مجانًا لتجربة النهج المتكامل بجانب إعداد inso الحالي.

Top comments (0)