DEV Community

Cover image for كيفية استخدام Insomnia لاختبار API
Yusuf Khalidd
Yusuf Khalidd

Posted on • Originally published at apidog.com

كيفية استخدام Insomnia لاختبار API

Insomnia هو عميل API من Kong لإرسال الطلبات وفحص الاستجابات. يدعم HTTP وREST وGraphQL وgRPC وSOAP وWebSocket من واجهة واحدة، ويُستخدم غالبًا عندما تحتاج أداة خفيفة لاختبار واجهات API دون تعقيد أدوات الـIDE الثقيلة.

جرّب Apidog اليوم

في هذا الدليل ستبني تدفق اختبار عملي داخل Insomnia: إنشاء مجموعة طلبات، إرسال طلب، فحص الاستجابة، إعداد البيئات والمتغيرات، ثم كتابة تأكيدات داخل مجموعات الاختبار وتشغيلها من سطر الأوامر باستخدام Inso. سنستخدم JSONPlaceholder حتى تتمكن من التطبيق مباشرة.

تثبيت Insomnia وإنشاء أول طلب

نزّل Insomnia من الموقع الرسمي لـ Kong وثبّته على نظامك. عند التشغيل الأول يمكنك تسجيل الدخول أو العمل محليًا بدون حساب. في الوضع المحلي يخزن Insomnia بياناتك على جهازك، بينما تبقى المزامنة السحابية اختيارية حسب إعدادات الإصدار الذي تستخدمه.

لإنشاء طلب:

  1. افتح Insomnia.
  2. اضغط Create.
  3. اختر Request Collection.
  4. سمِّ المجموعة مثلًا: اختبارات API المستخدمين.
  5. داخل المجموعة، اضغط زر +.
  6. اختر HTTP Request.
  7. اضبط الطريقة على GET.
  8. أدخل عنوان الطلب التالي: 
GET https://jsonplaceholder.typicode.com/users/1
Enter fullscreen mode Exit fullscreen mode

اضغط Send. ستظهر في لوحة الاستجابة:

  • رمز الحالة مثل 200
  • زمن الاستجابة
  • حجم الاستجابة
  • جسم الاستجابة بتنسيق JSON منسق

مثال استجابة مختصر:

{
  "id": 1,
  "name": "Leanne Graham",
  "email": "Sincere@april.biz"
}
Enter fullscreen mode Exit fullscreen mode

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

تكوين الطرق والمعلمات والمصادقة

بعد إنشاء طلب بسيط، ستحتاج غالبًا إلى ضبط الجسم، الاستعلام، الرؤوس، والمصادقة.

إرسال جسم JSON مع POST

أنشئ طلبًا جديدًا واضبط الطريقة على POST، ثم من تبويب Body اختر JSON وأدخل:

{
  "name": "Daniel Okafor",
  "email": "daniel.okafor@example.com"
}
Enter fullscreen mode Exit fullscreen mode

عند اختيار نوع الجسم JSON، يضيف Insomnia رأس Content-Type: application/json تلقائيًا.

إضافة Query Parameters

بدل كتابة المعلمات يدويًا داخل الرابط:

GET https://api.example.com/users?page=1&limit=10
Enter fullscreen mode Exit fullscreen mode

استخدم تبويب Query وأضف:

Name Value
page 1
limit 10

هذا يجعل تشغيل أو تعطيل أي معلمة أسهل أثناء الاختبار.

إضافة Headers

من تبويب Headers أضف أي رؤوس تحتاجها واجهة API، مثل:

Accept: application/json
X-Request-Id: test-001
Enter fullscreen mode Exit fullscreen mode

إعداد المصادقة

من تبويب Auth اختر نوع المصادقة المناسب، مثل:

  • Bearer Token
  • Basic Auth
  • API Key
  • OAuth 1.0 / OAuth 2.0
  • AWS IAM

لواجهة API تستخدم Bearer Token، اختر Bearer Token وضع الرمز. الأفضل ألا تكتبه مباشرة داخل الطلب، بل استخدم متغير بيئة:

Authorization: Bearer {{ _.auth_token }}
Enter fullscreen mode Exit fullscreen mode

إذا كنت تحدد رموز الحالة المتوقعة في اختباراتك، يمكنك الرجوع إلى هذا الدليل حول رموز حالة HTTP التي يجب أن تستخدمها واجهات برمجة تطبيقات REST.

إعداد البيئات والمتغيرات

البيئات في Insomnia تساعدك على عدم تكرار القيم مثل base_url أو auth_token، وتسهّل التبديل بين التطوير، الاختبار، والإنتاج.

افتح قائمة البيئة من أعلى الشريط الجانبي، ثم اختر Manage Environments. داخل Base Environment أو بيئة فرعية، أضف:

{
  "base_url": "https://jsonplaceholder.typicode.com",
  "auth_token": "your-token-here"
}
Enter fullscreen mode Exit fullscreen mode

بعدها استخدم المتغير داخل الطلب:

GET {{ _.base_url }}/users/1
Enter fullscreen mode Exit fullscreen mode

عند تغيير البيئة النشطة، سيستخدم كل طلب القيم الخاصة بهذه البيئة تلقائيًا.

مثال عملي لبيئتين

بيئة التطوير:

{
  "base_url": "https://dev-api.example.com",
  "auth_token": "dev-token"
}
Enter fullscreen mode Exit fullscreen mode

بيئة الإنتاج:

{
  "base_url": "https://api.example.com",
  "auth_token": "prod-token"
}
Enter fullscreen mode Exit fullscreen mode

نفس الطلب يعمل على البيئتين دون تعديل الرابط:

GET {{ _.base_url }}/users/1
Enter fullscreen mode Exit fullscreen mode

استخدام Template Tags

يدعم Insomnia علامات القوالب لإنشاء أو استخراج قيم ديناميكية، مثل:

  • Timestamp
  • UUID
  • قيمة من استجابة طلب سابق

مثال عملي: إذا كان لديك طلب تسجيل دخول يعيد:

{
  "token": "abc123"
}
Enter fullscreen mode Exit fullscreen mode

يمكنك استخدام Template Tag لاستخراج $.token من استجابة تسجيل الدخول ثم استخدامه في الطلبات المحمية:

Authorization: Bearer <token-from-login-response>
Enter fullscreen mode Exit fullscreen mode

بهذا يمكن لـ Insomnia تشغيل طلب تسجيل الدخول عند الحاجة، استخراج الرمز، ثم تمريره للطلبات التالية دون كتابة كود ربط إضافي.

للاطلاع على طريقة تنظيم الفحوصات المرتبطة بسيناريوهات API، راجع مثال حالة اختبار API.

كتابة مجموعات الاختبار مع التأكيدات

إرسال الطلب يدويًا جيد أثناء التطوير، لكن الاختبار الفعلي يحتاج تأكيدات قابلة للتكرار. في Insomnia يتم ذلك عبر Test Suites أو تبويب Unit Tests حسب الإصدار.

لإنشاء اختبار:

  1. افتح المجموعة.
  2. انتقل إلى Tests.
  3. أنشئ Test Suite.
  4. أضف اختبارًا جديدًا.
  5. اختر الطلب الذي سيستهدفه الاختبار من القائمة.
  6. اكتب التأكيدات باستخدام JavaScript وChai.

اختبار بسيط للتحقق من رمز الحالة:

const response = await insomnia.send();

expect(response.status).to.equal(200);
Enter fullscreen mode Exit fullscreen mode

اختبار يفحص الجسم:

const response = await insomnia.send();
const body = JSON.parse(response.data);

expect(response.status).to.equal(200);
expect(body).to.have.property("id");
expect(body.email).to.equal("Sincere@april.biz");
Enter fullscreen mode Exit fullscreen mode

اختبار للرؤوس:

const response = await insomnia.send();

expect(response.headers["content-type"]).to.include("application/json");
Enter fullscreen mode Exit fullscreen mode

اختبار لقيمة داخل مصفوفة:

const response = await insomnia.send();
const body = JSON.parse(response.data);

expect(body).to.be.an("array");
expect(body.length).to.be.greaterThan(0);
expect(body[0]).to.have.property("email");
Enter fullscreen mode Exit fullscreen mode

بعد كتابة الاختبارات، اضغط Run Tests. سيعرض Insomnia نتيجة كل اختبار، زمن التنفيذ، وأي رسالة فشل.

تنظيم الاختبارات

استخدم تنظيمًا بسيطًا قابلًا للتوسع:

  • مجموعة اختبار لكل مورد: Users, Posts, Orders
  • اختبار واحد لكل سلوك
  • أسماء واضحة مثل:
    • GET /users/1 returns 200
    • GET /users/999 returns 404
    • POST /users rejects invalid email

لا تجعل اختبارًا واحدًا يتحقق من كل شيء. عند الفشل، يجب أن تعرف السبب من اسم الاختبار مباشرة.

لتحسين جودة التأكيدات، راجع دليل تأكيدات API، ولتنظيم الاختبارات مع نمو المشروع راجع مجموعات الاختبار لأتمتة اختبار API.

التشغيل من سطر الأوامر باستخدام Inso

واجهة Insomnia مناسبة أثناء التطوير، لكن CI يحتاج تشغيلًا بدون واجهة. لذلك يوفر Insomnia أداة سطر أوامر باسم Inso.

بعد تصدير المجموعة أو مزامنتها، شغّل الاختبارات من الطرفية:

inso run test "اختبارات API المستخدمين"
Enter fullscreen mode Exit fullscreen mode

إذا فشل أي اختبار، يرجع Inso رمز خروج غير صفري. هذا يسمح لـ CI بإيقاف البناء تلقائيًا.

مثال مبسط داخل GitHub Actions:

name: API Tests

on:
  push:
    branches:
      - main

jobs:
  insomnia-tests:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Install Inso
        run: npm install -g insomnia-inso

      - name: Run Insomnia tests
        run: inso run test "اختبارات API المستخدمين"
Enter fullscreen mode Exit fullscreen mode

يمكنك ربط هذا بأي مسار CI/CD بحيث تعمل اختبارات API عند كل دفع للكود أو قبل النشر.

للنمط العام في الأتمتة، راجع أتمتة اختبارات API في CI/CD.

تغيير السحابة في الإصدار 8، وبديل

في Insomnia 8 تحول المنتج نحو نموذج يعتمد على السحابة أولًا، حيث دفع المستخدمين لإنشاء حساب Kong وتخزين المشاريع في السحابة. لم يكن هذا مناسبًا لبعض الفرق، خاصة التي تحتاج عملًا محليًا بالكامل أو لا تسمح بخروج بيانات API من بيئتها الداخلية.

أعادت الإصدارات اللاحقة خيارات أوضح للعمل المحلي فقط أو استخدام Scratch Pad، لكن هذا التغيير جعل بعض الفرق تقيم بدائل أخرى.

إذا كنت تحتاج منصة API أوسع، فإن Apidog يستحق التجربة. يغطي التصميم، التصحيح، المحاكاة، الاختبار، والتوثيق، ويدعم استيراد صادرات Insomnia حتى لا تبدأ من الصفر. يمكنك بناء التأكيدات بصريًا دون JavaScript، مع دعم النصوص البرمجية عند الحاجة.

يمكنك تنزيل Apidog واستيراد مجموعة Insomnia للمقارنة. وللاطلاع على خيارات أخرى، راجع قائمة أدوات اختبار API المجانية عبر الإنترنت.

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

الأسئلة الشائعة

هل Insomnia مجاني للاستخدام؟

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

ما البروتوكولات التي يدعمها Insomnia؟

يدعم Insomnia:

  • HTTP
  • REST
  • GraphQL
  • gRPC
  • SOAP
  • WebSocket

يختلف إعداد الطلب حسب البروتوكول، لكن فحص الاستجابة واختبارات الطلبات المستندة إلى HTTP تعمل بنمط متقارب.

كيف أكتب التأكيدات في Insomnia؟

استخدم Test Suites. افتح عرض الاختبارات داخل المجموعة، أنشئ Suite، ثم أضف اختبارًا يستدعي:

const response = await insomnia.send();
Enter fullscreen mode Exit fullscreen mode

بعدها استخدم expect بأسلوب Chai للتحقق من الحالة، الرؤوس، أو جسم الاستجابة:

expect(response.status).to.equal(200);
Enter fullscreen mode Exit fullscreen mode

ما الذي تغير في Insomnia 8؟

تحول Insomnia 8 إلى افتراضي يعتمد على السحابة أولًا، ما دفع المستخدمين لتسجيل الدخول إلى حساب Kong ومزامنة المشاريع. لم يناسب ذلك بعض المستخدمين الذين اعتادوا العمل المحلي الكامل. لاحقًا أصبحت خيارات العمل المحلي أوضح، لكن التغيير دفع بعض الفرق للبحث عن بدائل.

هل يمكنني تشغيل اختبارات Insomnia في CI؟

نعم. استخدم Inso من سطر الأوامر:

inso run test "<اسم المجموعة>"
Enter fullscreen mode Exit fullscreen mode

إذا فشل اختبار، يرجع Inso رمز خروج غير صفري، وبالتالي يمكن لـ CI تعليم البناء على أنه فاشل تلقائيًا.

Top comments (0)