كيفية اختبار واجهات برمجة التطبيقات باستخدام بوستمان: دليل عملي

بوستمان (Postman) هي إحدى الأدوات الأكثر استخدامًا لإرسال طلبات HTTP والتحقق من سلوك واجهات برمجة التطبيقات (API). بدأت كإضافة للمتصفح ونمت لتصبح تطبيق سطح مكتب كامل يتعامل مع كل شيء بدءًا من طلب GET السريع وصولاً إلى مجموعات الاختبار المبرمجة التي تعمل في CI. إذا كنت تبني أو تستهلك واجهات برمجة التطبيقات، فمن شبه المؤكد أنك ستصادفها.

يرشدك هذا الدليل خلال اختبار واجهة برمجة تطبيقات (API) في Postman بالطريقة التي ستفعلها يوميًا. سترسل طلبًا، وتفحص الاستجابة، وتكتب تأكيدات في علامة التبويب Tests، وتقوم بإعداد البيئات بحيث يمكنك التبديل بين بيئات التطوير (staging) والإنتاج (production)، وتشغيل مجموعة كاملة مرة واحدة باستخدام Collection Runner. تستخدم الأمثلة واجهة برمجة تطبيقات عامة حتى تتمكن من المتابعة دون الحاجة إلى إعداد أي شيء أولاً.

إعداد Postman وإرسال طلبك الأول

قم بتنزيل Postman من الموقع الرسمي وتثبيت تطبيق سطح المكتب. يمكنك استخدامه بدون حساب للعمل المحلي، على الرغم من أن تسجيل الدخول يقوم بمزامنة مجموعاتك عبر الأجهزة. افتح التطبيق وانقر على الزر New، ثم اختر HTTP Request.

يتطلب الطلب ثلاثة أشياء كحد أدنى: طريقة (method)، وعنوان URL (URL)، وأحيانًا جسم (body). اختر GET من القائمة المنسدلة للطرق وأدخل نقطة نهاية حقيقية. خدمة JSONPlaceholder مفيدة للممارسة:

GET https://jsonplaceholder.typicode.com/users/1

انقر على Send. سيتم ملء لوحة الاستجابة بالجسم، رمز الحالة (200 OK)، وقت الاستجابة، والحجم. قم بتبديل عرض الجسم بين Pretty وRaw وPreview لرؤية JSON منسقًا أو كما أرسله الخادم.

لطلب POST، غيّر الطريقة، افتح علامة التبويب Body، اختر raw، وحدد JSON من القائمة المنسدلة للتنسيق. الصق حمولة (payload) مثل هذه:

{
  "name": "Maria Chen",
  "email": "maria.chen@example.com"
}

تتم إضافة رؤوس (Headers) مثل Content-Type: application/json لك عندما تختار نوع جسم JSON. تتيح لك علامة التبويب Headers إضافة أي شيء آخر تحتاجه واجهة برمجة التطبيقات، مثل رأس Authorization. إذا كنت جديدًا في معرفة رموز الاستجابة المتوقعة، فإن الدليل حول رموز حالة HTTP التي يجب أن تستخدمها واجهات برمجة التطبيقات REST يعد مرجعًا مفيدًا.

تنظيم الطلبات في مجموعات (Collections)

طلب واحد يكفي للتحقق السريع. الاختبار الحقيقي يعني العديد من الطلبات التي تنتمي لبعضها البعض: إنشاء مستخدم، جلب هذا المستخدم، تحديثه، حذفه. Postman يجمع هذه الطلبات في مجموعات (collections).

انقر على Collections في الشريط الجانبي، ثم على أيقونة + لإنشاء واحدة. سمّها اسمًا واضحًا مثل "اختبارات Smoke لواجهة برمجة تطبيقات المستخدم" ("User API smoke tests"). احفظ كل طلب في المجموعة باستخدام Ctrl/Cmd + S وأعطه اسمًا واضحًا. يمكنك تضمين مجلدات داخل المجموعة لفصل، على سبيل المثال، طلبات المصادقة عن طلبات الموارد.

المجموعات هي أيضًا الوحدة التي تشاركها. قم بتصدير واحدة كملف JSON، أو شارك رابطًا إذا قمت بالمزامنة مع السحابة. يقوم أعضاء الفريق باستيرادها ويكون لديهم نفس الطلبات تمامًا التي لديك. هذا هو الأساس لكل شيء آخر، لأن Collection Runner والاختبارات الآلية يعملان على المجموعات بدلاً من الطلبات الفردية.

يمكن للمجموعة أيضًا أن تحمل سلوكًا مشتركًا. يسمح لك Postman بإرفاق نصوص برمجية على مستوى المجموعة أو المجلد، وليس فقط على طلب واحد. يعمل النص البرمجي ما قبل الطلب (pre-request script) على المجموعة قبل كل طلب داخلها، وهو مفيد لتحديث رمز مميز (token) أو ختم طابع زمني (timestamp). يعمل النص البرمجي للاختبار على مستوى المجموعة بعد كل طلب، وهو مفيد لتأكيد تريد تطبيقه في كل مكان، مثل "وقت الاستجابة معقول". تحديد هذه الأمور مرة واحدة يحافظ على تركيز طلباتك الفردية على ما هو فريد لها.

كتابة الاختبارات في علامة التبويب Tests

إرسال طلب يخبرك بما عاد. يخبرك الاختبار (test) إذا كان ما عاد صحيحًا، تلقائيًا، في كل مرة. يشغل Postman جافاسكريبت في منطقة Scripts الخاصة بالطلب (الإصدارات القديمة كانت تسميها علامة التبويب Tests) بعد وصول الاستجابة.

يعرض Postman كائن pm لكتابة التأكيدات (assertions). النمط الأساسي هو pm.test(name, callback)، حيث يقوم رد الاتصال (callback) بإلقاء خطأ إذا فشل التوقع. إليك التأكيدات التي ستستخدمها باستمرار:

// Check the status code
pm.test("Status code is 200", function () {
    pm.response.to.have.status(200);
});

// Check response time
pm.test("Response is under 500ms", function () {
    pm.expect(pm.response.responseTime).to.be.below(500);
});

// Check a field in the JSON body
pm.test("User has the expected email", function () {
    const body = pm.response.json();
    pm.expect(body.email).to.eql("maria.chen@example.com");
});

// Check a header
pm.test("Content-Type is JSON", function () {
    pm.expect(pm.response.headers.get("Content-Type"))
      .to.include("application/json");
});

يأتي بناء جملة التأكيد من Chai، لذا فإن pm.expect يدعم .to.eql، .to.include، .to.be.above، والبقية. انقر على Send وستظهر النتائج في علامة التبويب Test Results، حيث يكون كل اختبار باللون الأخضر أو الأحمر.

تحافظ بعض العادات على فائدة الاختبارات. قم بتسمية كل كتلة pm.test بناءً على السلوك الذي تتحقق منه، وليس نقطة النهاية، بحيث تبدو رسالة الفشل وكأنها جملة. تحقق من الأشياء التي قد تؤدي بالفعل إلى تعطيل مستهلك واجهة برمجة التطبيقات: رمز الحالة، وشكل الجسم، والحقول التي يعتمد عليها العميل. تجنب التأكيد على القيم التي لا تتحكم فيها، مثل الطابع الزمني الذي تم إنشاؤه بواسطة الخادم، لأنها تنتج إخفاقات غير موثوقة تدرب الأشخاص على تجاهل الإشارات الحمراء. يأتي Postman أيضًا مع لوحة Snippets بجانب المحرر تحتوي على تأكيدات جاهزة يمكنك النقر لإدراجها، وهي أسرع طريقة لتعلم واجهة برمجة التطبيقات pm. إذا كنت تريد نظرة أعمق على تصميم التأكيد، فراجع تفصيل تأكيدات API وكيفية كتابتها جيدًا. للحصول على فكرة أوسع حول هيكلة الفحوصات في حالات مسماة، فإن دليل مثال حالة اختبار API يستحق القراءة بجانب هذا.

استخدام البيئات والمتغيرات

ترميز https://api.staging.example.com بشكل ثابت في كل طلب أمر مؤلم بمجرد أن تحتاج إلى التوجيه إلى بيئة الإنتاج. البيئات (Environments) تحل هذه المشكلة. البيئة هي مجموعة مسماة من المتغيرات.

انقر على أيقونة البيئات في الشريط الجانبي وأنشئ واحدة تسمى "Staging". أضف متغيرًا base_url بقيمة https://jsonplaceholder.typicode.com. أنشئ بيئة ثانية تسمى "Production" مع base_url مختلف. الآن قم بالإشارة إلى المتغير في طلباتك باستخدام الأقواس المعقوفة المزدوجة:

GET {{base_url}}/users/1

اختر البيئة النشطة من القائمة المنسدلة في أعلى اليمين، وكل طلب يستخدم {{base_url}} سيتحول معها.

تحمل المتغيرات أيضًا البيانات بين الطلبات. يمكن لطلب تسجيل الدخول التقاط رمز مميز (token) من استجابته وتخزينه لاستخدامه في الطلبات اللاحقة:

pm.test("Save the auth token", function () {
    const token = pm.response.json().token;
    pm.environment.set("auth_token", token);
});

يمكن لأي طلب لاحق بعد ذلك إرسال Authorization: Bearer {{auth_token}}. هذا التسلسل هو كيف تختبر التدفقات التي تعتمد على الحالة، مثل إنشاء مورد ثم التحقق من وجوده.

يحتوي Postman على نطاقين متعلقين بالمتغيرات يستحقان المعرفة. متغيرات البيئة (Environment variables) تنتمي إلى البيئة المحددة وتتغير عند التبديل بين البيئات. متغيرات المجموعة (Collection variables) تنتمي إلى مجموعة بغض النظر عن البيئة، وهو ما يناسب القيم الثابتة لواجهة برمجة التطبيقات هذه. توجد أيضًا متغيرات عامة (global variables)، تنطبق في كل مكان، ومتغيرات محلية (local variables) قصيرة العمر موجودة لمرة واحدة فقط. اختيار النطاق الصحيح يحافظ على القيمة في مكانها الصحيح ويتجنب المفاجآت عند تبديل الأهداف.

تشغيل مجموعة كاملة باستخدام Collection Runner

النقر على Send في كل طلب يصبح قديمًا بسرعة. يقوم Collection Runner بتنفيذ كل طلب في المجموعة بالترتيب، ويشغل جميع اختباراته، ويقدم لك ملخصًا للنجاح/الفشل.

افتح مجموعة، انقر على الزر Run (أو قائمة النقاط الثلاث، ثم Run collection). يعرض المشغل (runner) طلباتك بالتسلسل. اختر البيئة، حدد عدد التكرارات المراد تشغيلها، وقم اختياريًا بإرفاق ملف بيانات. انقر على Run ويقوم Postman بتشغيل كل طلب، من الأعلى إلى الأسفل، منفذًا اختبارات كل طلب.

تعرض صفحة النتائج كل تأكيد عبر كل طلب، مع إجماليات للناجح والفاشل. هذا هو فحص الانحدار (regression check) الخاص بك. قم بتشغيله بعد النشر وستعرف في ثوانٍ ما إذا كانت واجهة برمجة التطبيقات لا تزال تعمل بشكل صحيح. يحتفظ المشغل أيضًا بسجل للتشغيلات السابقة، حتى تتمكن من مقارنة نتيجة اليوم بنتائج الأمس وتحديد متى بدأت مجموعة كانت خضراء في الفشل.

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

لاختبار قائم على البيانات، قم بإرفاق ملف CSV أو JSON في المشغل. يصبح كل صف تكرارًا واحدًا، وتشير إلى الأعمدة كمتغيرات مثل {{username}}. يتيح ذلك لطلب واحد اختبار عشرات من مجموعات المدخلات دون تكرار الطلب. على سبيل المثال، يمكن ضرب نقطة نهاية تسجيل الدخول بصف واحد من بيانات الاعتماد الصحيحة وعدة صفوف من البيانات الخاطئة، مع تأكيد كل صف على رمز الحالة الذي يتوقعه. يغطي المقال حول اختبار API القائم على البيانات باستخدام CSV و JSON هذا النمط بالتفصيل. لتشغيل نفس المجموعة في CI بدون واجهة المستخدم الرسومية (GUI)، يوفر Postman أداة سطر الأوامر Newman، الموضحة في مقارنة Newman مقابل Postman.

الجوانب التي يصبح فيها Postman ثقيلًا، وما يجب أخذه في الاعتبار

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

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

لا يعني أي من هذا أنه يجب عليك التخلي عن Postman. إنه يظل خيارًا قويًا، خاصة للفحوصات السريعة والفرق التي استثمرت فيه بالفعل. النقطة هي معرفة مكان كل أداة.

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

هل أحتاج إلى كتابة كود لاختبار واجهات برمجة التطبيقات في Postman؟

لإرسال الطلبات وقراءة الاستجابات، لا. بالنسبة للتأكيدات التلقائية، نعم، على الأقل قليلاً. تشغل علامة التبويب Tests في Postman لغة JavaScript وتستخدم كائن pm. الأنماط بسيطة ويمكنك نسخها من لوحة Snippets المدمجة في Postman، ولكنها لا تزال JavaScript. إذا كنت تريد منشئ تأكيدات مرئي بدون كود، فإن منصة مخصصة مثل Apidog تتولى ذلك.

ما الفرق بين مجموعة Postman والبيئة؟

المجموعة (collection) هي مجموعة من الطلبات المجمعة معًا، غالبًا مع اختباراتها. البيئة (environment) هي مجموعة مسماة من المتغيرات، مثل base_url أو auth_token. المجموعات تحتوي على ما ترسله. البيئات تحتوي على القيم التي تتغير بين بيئات التطوير (staging) والإنتاج (production) والبيئات المحلية. يمكنك توجيه مجموعة واحدة إلى بيئات مختلفة لاختبار نفس الطلبات مقابل خوادم مختلفة.

كيف أقوم بتشغيل اختبارات Postman تلقائيًا في CI؟

استخدم Newman، مشغل سطر الأوامر الخاص بـ Postman. قم بتصدير مجموعتك وبيئتك، ثم قم بتشغيل newman run collection.json -e environment.json. يخرج Newman برمز غير صفري إذا فشل أي اختبار، وهذا ما يتحقق منه خط أنابيب CI الخاص بك. يرشدك الدليل حول أتمتة اختبارات API في CI/CD خلال ربط هذا بخط الأنابيب.

هل يمكن لـ Postman اختبار أكثر من واجهات برمجة تطبيقات REST؟

نعم. يدعم Postman الحديث طلبات GraphQL و gRPC و WebSocket و SOAP بالإضافة إلى HTTP و REST العاديين. تعمل علامة التبويب Tests والتأكيدات عبر معظم هذه التقنيات، على الرغم من أن إعداد الطلب الدقيق يختلف حسب البروتوكول.

كم عدد التأكيدات التي يجب أن يحتوي عليها الطلب الواحد؟

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