طلباتي للـ API كانت فوضى: كيف أنقذتني “مجموعات Postman” من جحيم الاختبار اليدوي؟

يا جماعة الخير، خلوني أحكيلكم قصة صارت معي قبل كم سنة. كنت شغال على مشروع ضخم، نظام إدارة محتوى معقد فيه عشرات، بل مئات الـ API endpoints. كان عندي واجهة أمامية (Frontend) وكنت أنا المسؤول عن الواجهة الخلفية (Backend). في بداية المشروع، كنت زي أي مبرمج “مستعجل”، كل ما أعمل endpoint جديد، أروح على Postman، أفتح تبويب جديد، أكتب الـ URL، أضيف الـ body، وأكبس Send. وإذا زبط، بحكي “الحمد لله” وبكمل على اللي بعده.

المشكلة وين بلشت؟ بعد أسبوعين ثلاثة، صار عندي تاريخ (History) في بوستمان أطول من قائمة مشتريات الدار لآخر السنة! طلبات GET، POST، PUT، DELETE، كلها فوق بعضها. إذا بدي أعدّل على طلب قديم، لازم أرجع أدور عليه، أو الأسوأ، أكتبه من أول وجديد. وصلت لمرحلة كنت فاتح ملف `requests.txt` على جهازي، وكل طلب بخلّصه بنسخ الـ cURL تبعه وبلصقه في الملف مع شوية ملاحظات. الوضع كان، زي ما بنحكي عنا، “شوربة”.

الكارثة الحقيقية صارت يوم قررت أغيّر شغلة بسيطة في نظام الـ Authentication. بدال ما التوكن (Token) يرجع باسم `token`، خليته يرجع باسم `accessToken`. تغيير بسيط صح؟ بس هالتغيير كسر كل الطلبات الثانية اللي بتحتاج توثيق. قعدت يوم كامل يا جماعة، يوم كااامل، وأنا بمر على كل طلب محمي وبختبره يدويًا… بنسخ التوكن الجديد من طلب الـ Login، وبروح على طلب “جلب بيانات المستخدم” وبلصقه في الـ Headers، بعدين على طلب “تعديل الملف الشخصي” وبلصق… وهكذا. وقتها قلت لحالي: “يا أبو عمر، لهون وبس! أكيد في طريقة أحسن من هالفوضى”. ومن هنا بدأت رحلتي الحقيقية مع Postman Collections.

ما هي “مجموعات Postman” (Postman Collections) وليش هي مهمة؟

ببساطة شديدة، فكّر في “المجموعة” أو الـ Collection على أنها مجلد أو ملف بنحفظ فيه كل طلبات الـ API المتعلقة بمشروع معين. بدل ما تكون طلباتك مبعثرة في كل مكان، بتصير مرتبة ومنظمة في مكان واحد. الموضوع أشبه بترتيب أغانيك المفضلة في قوائم تشغيل (Playlists) بدل ما تكون كلها مكومة مع بعض.

لكن أهميتها أكبر من مجرد التنظيم. المجموعات هي أساس تحويل Postman من مجرد “مرسل طلبات” إلى أداة اختبار وأتمتة متكاملة. هي اللي بتسمحلك تعمل أشياء خرافية راح نحكي عنها كمان شوي، مثل تشغيل كل الاختبارات بكبسة زر، ومشاركة الطلبات مع فريقك بسهولة.

من الفوضى إلى النظام: رحلتي في بناء أول مجموعة

بعد ما قررت أنظم شغلي، أول إشي عملته هو إني بدأت أنقل طلباتي من الـ History ومن ملف التكست التعيس هذاك إلى مجموعات منظمة. خلوني أفرجيكم كيف.

الخطوة الأولى: وداعاً للنسخ واللصق

بدل ما تفتح تبويب جديد لكل طلب، اعمل مجموعة أولاً. من الشريط الجانبي في Postman، اضغط على زر “+” بجانب Collections واختر “Blank collection”. سمّيها باسم مشروعك، مثلاً “نظام إدارة المحتوى”.

الآن، أي طلب جديد بتعمله، بدل ما تتركه يضيع في الـ History، اضغط على زر “Save” بجانب “Send”. بوستمان راح يسألك وين بدك تحفظه، اختار المجموعة اللي عملتها وخلصنا. هيك صار طلبك محفوظ ومرتب.

تنظيم الطلبات: مش مجرد مجلد وبس!

الأمور صارت أحسن، بس لسا ممكن تكون أفضل. المجموعة ممكن تحتوي على مجلدات فرعية (sub-folders). وهذا إشي عبقري للتنظيم. في مشروعي، عملت مجلدات بناءً على وظيفة الـ API. مثلاً:

• مجموعة: نظام إدارة المحتوى
  • مجلد: التوثيق (Authentication)
    • POST /login
    • POST /register
    • POST /forgot-password
  • مجلد: المستخدمون (Users)
    • GET /users/me
    • PUT /users/profile
    • DELETE /users/account
  • مجلد: المقالات (Articles)
    • GET /articles
    • POST /articles
    • GET /articles/{id}

شايفين كيف الترتيب؟ صار سهل جداً أوصل لأي طلب بدي ياه بثواني. ما في داعي أتذكر الـ URL كامل، بس بروح على المجلد الصح وبلاقي طلبي جاهز.

قوة المتغيرات (Variables): سر الكود النظيف في Postman

هون بتبلش الحلاوة جد. بتتذكروا لما حكيتلكم عن تغيير الـ URL من السيرفر المحلي (localhost) لسيرفر الإنتاج (production)؟ كنت أغيره يدوياً في كل طلب! هاد الحكي جنون.

الحل هو “المتغيرات”. بتقدر تعرف متغير على مستوى المجموعة كلها. بتروح على إعدادات المجموعة (اضغط على الثلاث نقاط بجانب اسمها واختار Edit)، ومن هناك روح على تبويب “Variables”.

أنا عملت متغير اسمه baseUrl وحطيت قيمته المبدئية http://localhost:5000. الآن، في كل طلباتي داخل هاي المجموعة، بدل ما أكتب الـ URL كامل، بكتب هيك:

{{baseUrl}}/api/auth/login

لما بدي أنقل شغلي لسيرفر الاختبار أو الإنتاج، كل اللي بعمله هو إني أغير قيمة متغير baseUrl في مكان واحد فقط! كل الطلبات راح تتحدث تلقائياً. هادي لحالها وفرت علي ساعات من التعديل اليدوي ومنعت أخطاء لا حصر لها.

نصيحة من أبو عمر: استخدم “البيئات” (Environments) لتكون أكثر احترافية. اعمل بيئة اسمها “Local” وحط فيها المتغيرات المحلية، وبيئة ثانية اسمها “Production” وحط فيها متغيرات الإنتاج. هيك بتقدر تتبدل بينهم بكبسة زر من الزاوية اليمين فوق في Postman.

الارتقاء بمستوى الاختبار: ما بعد الطلب الفردي

لهون الوضع ممتاز: تنظيم ومتغيرات. بس القوة الحقيقية للمجموعات بتظهر لما نبدأ بأتمتة الاختبارات.

سحر الـ “Collection Runner”: اختبار كل شيء بكبسة زر

هذا هو المنقذ. الـ Collection Runner هي أداة داخل Postman بتسمحلك تشغل كل الطلبات الموجودة في مجموعة (أو مجلد) بالترتيب، واحد ورا الثاني، بشكل آلي.

بتضغط على الثلاث نقاط بجانب اسم المجموعة وبتختار “Run collection”. بتفتحلك شاشة جديدة، بتحدد الطلبات اللي بدك تشغلها، وبتكبس “Run”. بوستمان راح يمر عليهم كلهم ويعطيك تقرير في النهاية: أي طلب نجح (أعطى status 200 مثلاً) وأي طلب فشل.

تخيلوا معي الموقف اللي حكيته أول المقال، لما غيرت إشي بالـ Authentication. بدل ما أقضي يوم كامل أختبر يدوياً، اليوم بكبسة زر واحدة بقدر أعيد اختبار كل الـ 50 أو 100 endpoint في دقيقة واحدة وأشوف شو اللي انكسر وشو اللي لسا شغال.

نصوص ما قبل الطلب وما بعده (Pre-request & Test Scripts)

هنا Postman بتحول من أداة بسيطة لوحش حقيقي في الاختبار. لكل طلب في مجموعتك، عندك تبويبين مهمين: “Pre-request Script” و “Tests”. هدول بياخدوا كود JavaScript.

مثال عملي: أتمتة الحصول على التوكن

المشكلة الأزلية: كل طلب محمي بيحتاج توكن مصادقة (JWT). بدل ما أنسخ وألصق التوكن يدوياً مع كل طلب، عملت الآتي:

1. في طلب الـ Login، رحت على تبويب “Tests”.
2. كتبت كود بسيط ليقرأ الرد (response) بعد ما ينجح الطلب، ياخد التوكن، ويخزنه في متغير على مستوى المجموعة.

// هذا الكود يوضع في تبويب "Tests" لطلب الـ Login
// pm object هو الـ Postman object اللي بيعطينا وصول لكل شي
if (pm.response.code === 200) {
    const responseData = pm.response.json();
    // افترض أن التوكن موجود في الرد تحت اسم accessToken
    if (responseData.accessToken) {
        // خزّن التوكن في متغير على مستوى المجموعة
        pm.collectionVariables.set("authToken", responseData.accessToken);
        console.log("تم حفظ التوكن بنجاح!");
    }
}

الآن، في كل الطلبات الثانية اللي بتحتاج توثيق (مثل “جلب بيانات المستخدم”)، بروح على تبويب “Authorization”، بختار النوع “Bearer Token”، وفي خانة التوكن بكتب المتغير تبعي:

{{authToken}}

وهيك، لما أشغل الـ Collection Runner، هو راح يشغل طلب الـ Login أولاً، يحفظ التوكن تلقائياً، وبعدين كل الطلبات اللي بعده راح تستخدم هاد التوكن الجديد تلقائياً. وداعاً للنسخ واللصق إلى الأبد!

كتابة اختبارات حقيقية

في تبويب “Tests” بتقدر كمان تكتب تأكيدات (assertions) لتتأكد من صحة الرد. مثلاً، في طلب “جلب بيانات المستخدم”، ممكن أتأكد إنه:

1. الـ Status Code هو 200 (OK).
2. الرد يحتوي على object اسمه `user`.
3. الـ `user` object يحتوي على خاصية `email`.

// هذا الكود يوضع في تبويب "Tests" لطلب جلب المستخدم
pm.test("Status code is 200", function () {
    pm.response.to.have.status(200);
});

pm.test("Body matches string", function () {
    pm.expect(pm.response.json()).to.have.property('user');
});

pm.test("User has an email", function () {
    const jsonData = pm.response.json();
    pm.expect(jsonData.user).to.have.property('email');
});

لما تشغل الـ Runner، راح تشوف نتائج هاي الاختبارات (Pass/Fail) لكل طلب. هيك بصير عندك شبكة أمان حقيقية لأي تغيير بتعمله على الكود.

نصائح من أبو عمر (خلاصة خبرة)

• وثّق شغلَك: بوستمان بيسمحلك تكتب وصف (description) لكل طلب ولكل مجموعة باستخدام صيغة Markdown. اكتب شرح بسيط عن وظيفة كل طلب، والـ body المتوقع، والردود الممكنة. زميلك في الفريق (أو أنت المستقبلي بعد 3 شهور) راح يدعيلك.
• شارك مجموعاتك: لو بتشتغل ضمن فريق، لا تخلي المجموعة عندك وبس. استخدم خاصية “Export” لتصدير المجموعة كملف JSON وابعته لفريقك، أو الأفضل، استخدم مساحات العمل (Workspaces) في بوستمان للمشاركة والتعاون بشكل مباشر.
• ابدأ بسيطاً ثم تطور: لا تشعر إنك لازم تطبق كل هالأشياء من أول يوم. ابدأ بالأساس: أنشئ مجموعة ورتب طلباتك في مجلدات. بعد ما ترتاح، ابدأ باستخدام المتغيرات. بعدها، جرب الـ Runner. وأخيراً، تعمق في كتابة الـ Scripts. خطوة بخطوة.

الخلاصة: من فوضى لراحة بال 🧘‍♂️

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

اليوم، ما بقدر أتخيل أبدأ أي مشروع Backend بدون ما أفتح Postman وأنشئ مجموعة جديدة من أول يوم. الاستثمار في تنظيم أدواتك هو استثمار مباشر في وقتك، جودة عملك، وصحتك النفسية كمبرمج. جربوها، وصدقوني ما راح تندموا.