Insomnia هو عميل API بُني بواسطة Kong لإرسال الطلبات وفحص الاستجابات. يُعرف بواجهته النظيفة والخالية من التشتيت ودعمه لـ HTTP و REST و GraphQL و gRPC و SOAP و WebSocket في مكان واحد. يلجأ إليه المطورون عندما يريدون شيئًا أخف من أداة ثقيلة بأسلوب IDE ولكنها لا تزال قادرة على القيام بعمل اختبار حقيقي.
يوضح هذا الدليل كيفية اختبار API في Insomnia من البداية إلى النهاية. ستنشئ مجموعة طلبات، وترسل وتفحص استجابة، وتُعد البيئات حتى تتمكن من تبديل عناوين URL الأساسية والرموز، وتستخدم ميزة مجموعات الاختبار لكتابة تأكيدات تعمل تلقائيًا. تستخدم الأمثلة واجهة برمجة تطبيقات عامة حتى تتمكن من المتابعة على الفور.
تثبيت Insomnia وإنشاء طلب
قم بتنزيل Insomnia من الموقع الرسمي لـ Kong وقم بتثبيته لمنصتك. عند التشغيل الأول، يسألك Insomnia إذا كنت ترغب في تسجيل الدخول. يمكنك اختيار العمل محليًا بدون حساب إذا كنت تفضل ذلك، ويقوم Insomnia بتخزين بياناتك على جهازك الخاص. المزامنة السحابية اختيارية وهي ما تغير في الإصدار 8، والذي نغطيه أدناه.
ينظم Insomnia العمل في مجموعات (collections) و مستندات (documents). انقر على إنشاء (Create) في لوحة التحكم واختر مجموعة طلبات (Request Collection). امنحها اسمًا واضحًا مثل "اختبارات API المستخدمين". داخل المجموعة، انقر على زر + واختر طلب HTTP (HTTP Request).
يتطلب الطلب طريقة وعنوان URL. اختر GET وأدخل نقطة نهاية حقيقية. تعمل خدمة JSONPlaceholder بشكل جيد للتدريب:
GET https://jsonplaceholder.typicode.com/users/1
انقر على إرسال (Send). تعرض اللوحة اليمنى نص الاستجابة، ورمز الحالة، ووقت الاستجابة، والحجم. يقوم Insomnia بطباعة JSON بشكل جميل تلقائيًا ويتيح لك تصفية النص باستخدام استعلام JSONPath أو XPath، وهو مفيد عندما تكون الاستجابة كبيرة.
تكوين الطرق والمعلمات والمصادقة
لأي شيء يتجاوز القراءة البسيطة، ستقوم بتعيين المزيد في الطلب. يجمع Insomnia هذه تحت علامات تبويب أسفل شريط URL.
تتعامل علامة التبويب الجسم (Body) مع حمولات الطلبات. لطلب POST، اختر JSON وأدخل البيانات:
{
"name": "Daniel Okafor",
"email": "daniel.okafor@example.com"
}
يقوم Insomnia بتعيين رأس Content-Type لك عندما تختار نوع جسم. تتيح لك علامة التبويب الاستعلام (Query) إضافة معلمات سلسلة الاستعلام دون تعديل عنوان URL يدويًا، مما يحافظ على وضوح عنوان URL الطويل ويتيح لك تشغيل وإيقاف المعلمات الفردية. علامة التبويب الرؤوس (Headers) مخصصة لأي شيء آخر تتوقعه واجهة برمجة التطبيقات، مثل X-Request-Id مخصص أو رأس Accept للتفاوض على تنسيق الاستجابة.
تتعامل علامة التبويب المصادقة (Auth) مع بيانات الاعتماد. يدعم Insomnia قائمة طويلة من المخططات: Bearer Token، Basic Auth، API Key، OAuth 1.0 و 2.0، AWS IAM، وغيرها. اختر المخطط الذي تستخدمه واجهة برمجة التطبيقات واملأ الحقول. لـ API محمي بالرمز، اختر Bearer Token والصق الرمز، أو الأفضل، ارجع إلى متغير بيئة حتى لا يكون الرمز مشفرًا بشكل ثابت. إذا لم تكن متأكدًا من رموز الحالة المتوقعة، فإن المرجع على رموز حالة HTTP التي يجب أن تستخدمها واجهات برمجة تطبيقات REST هو رفيق جيد.
إعداد البيئات والمتغيرات
تتيح لك البيئات تجنب تكرار القيم وتسهيل تبديل الأهداف. في Insomnia، البيئة هي كائن JSON من المتغيرات المرتبطة بمجموعة.
انقر على القائمة المنسدلة للبيئة بالقرب من أعلى الشريط الجانبي وافتح إدارة البيئات (Manage Environments). تحتوي البيئة الأساسية (Base Environment) على قيم مشتركة. أضف بيئات فرعية لكل هدف:
{
"base_url": "https://jsonplaceholder.typicode.com",
"auth_token": "your-token-here"
}
أنشئ بيئة فرعية ثانية للإنتاج بقيم مختلفة. ارجع إلى متغير في أي طلب باستخدام صياغة القالب {{ _.base_url }}، ليصبح عنوان URL:
GET {{ _.base_url }}/users/1
بدّل البيئة النشطة من القائمة المنسدلة وسيتم تحديث كل طلب يستخدم المتغير. يدعم Insomnia أيضًا علامات القوالب (template tags)، وهي دوال صغيرة يمكنك إدراجها في حقل لإنشاء طابع زمني، أو UUID، أو لسحب قيمة من استجابة سابقة. يتيح لك هذا الأخير ربط الطلبات، على سبيل المثال، التقاط رمز من استجابة تسجيل الدخول وتغذيته في الطلبات اللاحقة.
تستحق علامة قالب الاستجابة نظرة فاحصة لأنها الطريقة التي يتعامل بها Insomnia مع تبعيات الطلبات بدون برمجة نصية. يمكنك إضافة علامة تقول "استخدم نص طلب تسجيل الدخول، في JSONPath $.token،" وإسقاطها في رأس Authorization لكل طلب محمي. عند تشغيل طلب محمي، يقوم Insomnia بتشغيل طلب تسجيل الدخول أولاً إذا لزم الأمر، ويستخرج الرمز، ويستبدله. تظل السلسلة تصريحية، لذلك لا يوجد رمز ربط (glue code) للحفاظ عليه. للاطلاع على الفكرة الأوسع لتجميع الفحوصات ذات الصلة، انظر الدليل التفصيلي مثال حالة اختبار API.
كتابة مجموعات الاختبار مع التأكيدات
يظهر لك إرسال الطلب الاستجابة. للتحقق من صحة الاستجابة تلقائيًا، تستخدم ميزة مجموعات الاختبار (test suites) في Insomnia، والتي تظهر أحيانًا كعلامة التبويب اختبارات الوحدة (Unit Tests) في المجموعة.
افتح مجموعتك وانتقل إلى عرض الاختبارات (Tests). أنشئ مجموعة اختبار (test suite)، ثم أضف اختبارات فردية بداخلها. كل اختبار هو جزء صغير من JavaScript. يستخدم Insomnia مكتبة تأكيدات Chai ويوفر لك مساعدًا لإرسال طلب والحصول على استجابته. يبدو الاختبار كالتالي:
const response = await insomnia.send();
expect(response.status).to.equal(200);
يمكنك أن تكون أكثر تحديدًا عن طريق تحليل الجسم والتحقق من الحقول:
const response = await insomnia.send();
const body = JSON.parse(response.data);
expect(response.status).to.equal(200);
expect(body.email).to.equal("daniel.okafor@example.com");
expect(body).to.have.property("id");
يستهدف كل اختبار في المجموعة طلبًا من مجموعتك، يتم اختياره من قائمة منسدلة، حتى يعرف الاختبار ما يجب إرساله. انقر على تشغيل الاختبارات (Run Tests) ويقوم Insomnia بتنفيذ كل اختبار في المجموعة، مع إظهار كل واحد منها على أنه ناجح أو فاشل مع الوقت الذي استغرقه. هذا هو فحص الانحدار الخاص بك: قم بتشغيل المجموعة بعد تغيير وسترى على الفور ما إذا كان API لا يزال يتصرف بشكل صحيح.
تعد طريقة تنظيم المجموعات مهمة مع تزايد عددها. النمط الشائع هو مجموعة واحدة لكل مورد، بحيث تكون جميع اختبارات المقالات معًا وجميع اختبارات المستخدمين معًا. داخل المجموعة، اجعل كل اختبار يركز على سلوك واحد: اختبار واحد للمسار الناجح، واختبارات منفصلة لحالة عدم العثور وحالة خطأ التحقق. عندما يفشل اختبار ما، يجب أن يخبرك اسمه ونطاقه الضيق بما حدث دون الحاجة إلى قراءة كود التأكيد. للحصول على نظرة أعمق حول كتابة فحوصات جيدة، يشرح دليل تأكيدات API ما يجب تأكيده وما يجب تخطيه، وتغطي مقالة مجموعات الاختبار لأتمتة اختبار API كيفية هيكلة المجموعات مع نموها.
التشغيل من سطر الأوامر باستخدام Inso
الواجهة الرسومية (GUI) جيدة للتطوير، لكن الأتمتة تتطلب شيئًا بلا واجهة (headless). يشحن Insomnia رفيقًا لسطر الأوامر يسمى Inso. بعد تصدير مجموعتك أو مزامنتها، يمكنك تشغيل مجموعة الاختبار الخاصة بك من طرفية:
inso run test "اختبارات API المستخدمين"
يخرج Inso برمز حالة غير صفري إذا فشل أي اختبار، وهذا هو بالضبط ما يحتاجه مسار CI لتعليم البناء على أنه معطل. يمكنك ربط هذا بـ GitHub Actions أو أي مشغل آخر بحيث يتم تنفيذ اختبارات Insomnia الخاصة بك عند كل دفعة، مما يكتشف نقطة نهاية معطلة قبل أن تصل إلى زميل أو إلى الإنتاج. يمكن لـ Inso أيضًا تحليل مواصفات API الخاصة بك وإنشاء تقارير اختبار بتنسيقات قياسية، مما يجعله مفيدًا بخلاف مجرد تشغيل المجموعات. توضح المقالة حول أتمتة اختبارات API في CI/CD النمط العام، والذي ينطبق بشكل نظيف على Inso.
تغيير السحابة في الإصدار 8، وبديل
تحول Insomnia 8 نحو نموذج يعتمد على السحابة أولاً. بشكل افتراضي، دفع المستخدمين لإنشاء حساب Kong وتخزين المشاريع في السحابة. أثار هذا القرار استياء جزء من المجتمع، حيث كانت الإصدارات السابقة محلية بالكامل وصديقة للعمل دون اتصال بالإنترنت. استعادت الإصدارات اللاحقة خيارًا أوضح للعمل المحلي فقط أو "لوحة المسودات" (Scratch Pad)، لكن هذه الواقعة دفعت بعض الفرق للبحث عن بدائل، خاصة في البيئات التي لا يمكن للبيانات أن تغادر المبنى.
إذا كان هذا يصف حالتك، فإن Apidog يستحق المراجعة. إنه منصة API شاملة تغطي التصميم، التصحيح، المحاكاة، الاختبار، والتوثيق، ويستورد صادرات Insomnia بحيث لا تضطر إلى البدء من جديد. يتيح لك Apidog بناء التأكيدات بصريًا دون كتابة JavaScript، مع دعم النصوص البرمجية عندما تريدها. نظرًا لأن مواصفات API، بيانات الاختبار، وخادم المحاكاة تشترك في مشروع واحد، تظل اختباراتك متوافقة مع العقد الحقيقي بدلاً من الانجراف. يمكنك تنزيل Apidog واستيراد مجموعة Insomnia للمقارنة جنبًا إلى جنب. لإجراء مسح أوسع، تغطي قائمة أدوات اختبار API المجانية عبر الإنترنت العديد من الخيارات.
لا يزال Insomnia عميلاً قويًا ومركّزًا، خاصة للمطورين الفرديين والفرق الصغيرة التي تقدر واجهته البسيطة والخالية من التشتيت وبدء التشغيل السريع. يعتمد الاختيار الصحيح على كيفية عمل فريقك ومقدار دورة حياة API التي تريد التعامل معها في مكان واحد بدلاً من نشرها عبر أدوات منفصلة.
الأسئلة الشائعة
هل Insomnia مجاني للاستخدام؟
يحتوي Insomnia على طبقة مجانية تغطي الاستخدام الفردي، بما في ذلك إرسال الطلبات وتشغيل مجموعات الاختبار محليًا. تضيف الخطط المدفوعة تعاون الفريق وحدود مزامنة سحابية أكبر. يمكنك استخدام العميل الأساسي دون الدفع، وتتيح لك الإصدارات الحديثة العمل محليًا بالكامل إذا كنت تفضل عدم استخدام المزامنة السحابية.
ما هي البروتوكولات التي يدعمها Insomnia؟
يتعامل Insomnia مع HTTP، REST، GraphQL، gRPC، SOAP، و WebSocket. يختلف إعداد الطلب لكل بروتوكول، لكن فحص الاستجابة، وبالنسبة للطلبات المستندة إلى HTTP، تعمل تأكيدات مجموعات الاختبار بشكل متسق عبرها.
كيف أكتب التأكيدات في Insomnia؟
استخدم ميزة مجموعات الاختبار. افتح عرض الاختبارات (Tests) في مجموعة، أنشئ مجموعة (suite)، وأضف اختبارات. كل اختبار هو JavaScript يستدعي insomnia.send() لتشغيل طلب، ثم يستخدم تأكيدات expect بأسلوب Chai على الحالة (status)، أو الرؤوس (headers)، أو الجسم المحلل (parsed body). قم بتشغيل المجموعة بأكملها باستخدام زر "تشغيل الاختبارات" (Run Tests).
ما الذي تغير في Insomnia 8؟
تحول Insomnia 8 إلى افتراضي يعتمد على السحابة أولاً، مما دفع المستخدمين لتسجيل الدخول إلى حساب Kong ومزامنة المشاريع مع السحابة. لم يحب بعض المستخدمين تدفق الحساب الإلزامي والابتعاد عن تطبيق محلي بحت. أضافت التحديثات اللاحقة خيارات أوضح للعمل المحلي فقط، لكن التغيير دفع بعض الفرق لتقييم البدائل.
هل يمكنني تشغيل اختبارات Insomnia في مسار CI؟
نعم. استخدم Inso، الرفيق لسطر الأوامر. قم بتصدير أو مزامنة مجموعتك، ثم قم بتشغيل inso run test "<اسم المجموعة>" في مسارك. يعيد Inso رمز خروج غير صفري عند الفشل، لذلك يمكن لـ CI أن يفشل البناء تلقائيًا عندما يتعطل اختبار API.