DEV Community

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

Posted on • Originally published at apidog.com

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

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

جرّب Apidog اليوم

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

نزّل Postman من الموقع الرسمي وثبّت تطبيق سطح المكتب. يمكنك استخدامه محليًا بدون حساب، لكن تسجيل الدخول يساعدك على مزامنة المجموعات بين الأجهزة.

لإرسال أول طلب:

  1. افتح Postman.
  2. اضغط New.
  3. اختر HTTP Request.
  4. اختر الطريقة GET.
  5. أدخل عنوان URL التالي: 
GET https://jsonplaceholder.typicode.com/users/1
Enter fullscreen mode Exit fullscreen mode

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

  • رمز الحالة مثل 200 OK
  • وقت الاستجابة
  • حجم الاستجابة
  • جسم الاستجابة بصيغة JSON

جرّب التبديل بين Pretty و Raw و Preview لفهم شكل البيانات كما يعرضها Postman أو كما أرسلها الخادم.

لإرسال طلب POST:

  1. غيّر الطريقة إلى POST.
  2. افتح تبويب Body.
  3. اختر raw.
  4. اختر JSON من قائمة نوع المحتوى.
  5. أضف الحمولة التالية: 
{
  "name": "Maria Chen",
  "email": "maria.chen@example.com"
}
Enter fullscreen mode Exit fullscreen mode

عند اختيار JSON، يضيف Postman عادةً رأسًا مثل:

Content-Type: application/json
Enter fullscreen mode Exit fullscreen mode

إذا احتجت رؤوسًا إضافية، افتح تبويب Headers وأضف مثلًا:

Authorization: Bearer <token>
Enter fullscreen mode Exit fullscreen mode

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

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

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

لإنشاء مجموعة:

  1. افتح تبويب Collections من الشريط الجانبي.
  2. اضغط أيقونة +.
  3. سمّ المجموعة مثلًا: User API smoke tests.
  4. أنشئ الطلبات واحفظ كل طلب باستخدام Ctrl/Cmd + S.
  5. استخدم أسماء واضحة مثل:
    • Get user by ID
    • Create user
    • Update user
    • Delete user

يمكنك أيضًا إنشاء مجلدات داخل المجموعة، مثل:

User API smoke tests
├── Auth
│   └── Login
├── Users
│   ├── Get user by ID
│   ├── Create user
│   └── Update user
└── Cleanup
    └── Delete user
Enter fullscreen mode Exit fullscreen mode

المجموعة هي الوحدة التي تشاركها مع الفريق. يمكنك تصديرها كملف JSON أو مشاركتها عبر رابط إذا كنت تستخدم مزامنة Postman.

يمكنك كذلك تعريف سلوك مشترك على مستوى المجموعة أو المجلد:

  • Pre-request script: يعمل قبل كل طلب، مناسب لتجهيز token أو timestamp.
  • Tests script: يعمل بعد كل طلب، مناسب لتأكيدات عامة مثل زمن الاستجابة أو وجود رأس معين.

مثال اختبار عام يمكن وضعه على مستوى المجموعة:

pm.test("Response time is acceptable", function () {
    pm.expect(pm.response.responseTime).to.be.below(1000);
});
Enter fullscreen mode Exit fullscreen mode

بهذا لن تحتاج لتكرار نفس التأكيد داخل كل طلب.

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

إرسال الطلب يخبرك بما أعاده الخادم. الاختبار يخبرك هل ما عاد صحيح أم لا.

في Postman، تكتب الاختبارات باستخدام JavaScript من منطقة Scripts أو تبويب Tests في الإصدارات الأقدم. الكائن الأساسي هو pm.

النمط العام:

pm.test("Test name", function () {
    // assertion here
});
Enter fullscreen mode Exit fullscreen mode

أمثلة عملية ستستخدمها كثيرًا:

// 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");
});
Enter fullscreen mode Exit fullscreen mode

يعتمد أسلوب التأكيدات على Chai، لذلك يمكنك استخدام صيغ مثل:

pm.expect(value).to.eql(expectedValue);
pm.expect(value).to.include("text");
pm.expect(number).to.be.above(0);
pm.expect(number).to.be.below(500);
Enter fullscreen mode Exit fullscreen mode

بعد الضغط على Send، افتح تبويب Test Results لرؤية الاختبارات الناجحة والفاشلة.

نصائح لكتابة اختبارات مفيدة:

  • اجعل اسم الاختبار جملة واضحة، مثل: Response contains user email.
  • اختبر الأشياء التي تكسر العميل فعلًا: status code، شكل JSON، الحقول المطلوبة.
  • لا تختبر قيمًا غير مستقرة مثل timestamps التي يولدها الخادم، إلا إذا كنت تتحقق من شكلها فقط.
  • اجعل كل pm.test يتحقق من شيء واحد حتى تكون رسالة الفشل واضحة.
  • استخدم لوحة Snippets في Postman لإدراج أمثلة جاهزة بسرعة.

مثال لفحص شكل الاستجابة بدل الاعتماد على قيم ثابتة:

pm.test("Response has required user fields", function () {
    const body = pm.response.json();

    pm.expect(body).to.have.property("id");
    pm.expect(body).to.have.property("name");
    pm.expect(body).to.have.property("email");
});
Enter fullscreen mode Exit fullscreen mode

للتعمق في تصميم التأكيدات، راجع تأكيدات API وكيفية كتابتها جيدًا. ولتنظيم الفحوصات في حالات اختبار أوضح، اقرأ مثال حالة اختبار API.

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

لا تكتب عنوان الخادم ثابتًا في كل طلب مثل:

https://api.staging.example.com
Enter fullscreen mode Exit fullscreen mode

بدلًا من ذلك، استخدم Environments. البيئة هي مجموعة متغيرات يمكنك التبديل بينها.

أنشئ بيئة باسم Staging وأضف متغيرًا:

base_url = https://jsonplaceholder.typicode.com
Enter fullscreen mode Exit fullscreen mode

ثم استخدمه في الطلب:

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

عند التبديل إلى بيئة أخرى مثل Production، يتغير base_url بدون تعديل الطلب نفسه.

حفظ بيانات من استجابة لاستخدامها لاحقًا

يمكنك استخراج قيمة من الاستجابة وحفظها في متغير بيئة. مثال: حفظ token بعد تسجيل الدخول:

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

ثم استخدمه في طلب لاحق داخل Header:

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

هذا النمط مهم لاختبار التدفقات المعتمدة على الحالة، مثل:

  1. تسجيل الدخول.
  2. حفظ auth_token.
  3. إنشاء مورد.
  4. حفظ resource_id.
  5. جلب المورد.
  6. حذفه.

مثال حفظ id من استجابة إنشاء مورد:

pm.test("Save created user ID", function () {
    const body = pm.response.json();
    pm.environment.set("user_id", body.id);
});
Enter fullscreen mode Exit fullscreen mode

ثم استخدامه:

GET {{base_url}}/users/{{user_id}}
Enter fullscreen mode Exit fullscreen mode

نطاقات المتغيرات في Postman

استخدم النطاق المناسب حتى لا تختلط القيم:

  • Environment variables: تختلف حسب البيئة، مثل base_url و auth_token.
  • Collection variables: ثابتة داخل المجموعة، مناسبة لقيم تخص API نفسها.
  • Global variables: متاحة في كل مكان، استخدمها بحذر.
  • Local variables: مؤقتة أثناء التشغيل الحالي.

قاعدة عملية:

base_url       -> Environment variable
auth_token     -> Environment variable
api_version    -> Collection variable
temporary_id   -> Local or Environment variable حسب التدفق
Enter fullscreen mode Exit fullscreen mode

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

بدل الضغط على Send لكل طلب، استخدم Collection Runner لتشغيل المجموعة كاملة بالترتيب.

الخطوات:

  1. افتح المجموعة.
  2. اضغط Run أو من قائمة النقاط اختر Run collection.
  3. اختر البيئة المناسبة.
  4. حدد عدد التكرارات.
  5. أضف ملف بيانات CSV أو JSON إذا احتجت.
  6. اضغط Run.

سيشغّل Postman الطلبات من الأعلى إلى الأسفل ويعرض نتيجة كل تأكيد.

ترتيب الطلبات مهم. مثال ترتيب عملي:

1. Login
2. Create user
3. Get created user
4. Update user
5. Delete user
Enter fullscreen mode Exit fullscreen mode

إذا كان طلب Login يحفظ auth_token، فكل الطلبات التي بعده يمكنها استخدام:

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

وإذا كان طلب Create user يحفظ user_id، فالطلبات التالية يمكنها استخدام:

{{base_url}}/users/{{user_id}}
Enter fullscreen mode Exit fullscreen mode

بهذا تتحول المجموعة إلى رحلة مستخدم قابلة للتشغيل آليًا.

اختبار قائم على البيانات باستخدام CSV أو JSON

إذا أردت اختبار نفس الطلب بعدة مدخلات، لا تكرر الطلب. استخدم ملف بيانات في Collection Runner.

مثال CSV:

email,password,expected_status
valid@example.com,correct-password,200
wrong@example.com,bad-password,401
missing@example.com,,400
Enter fullscreen mode Exit fullscreen mode

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

{
  "email": "{{email}}",
  "password": "{{password}}"
}
Enter fullscreen mode Exit fullscreen mode

وفي الاختبارات:

pm.test("Status code matches expected status", function () {
    pm.response.to.have.status(Number(pm.iterationData.get("expected_status")));
});
Enter fullscreen mode Exit fullscreen mode

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

لشرح أوسع، راجع اختبار API القائم على البيانات باستخدام CSV و JSON.

ولت running نفس المجموعة داخل CI بدون واجهة رسومية، استخدم Newman. اقرأ مقارنة Newman مقابل Postman.

تشغيل اختبارات Postman في CI باستخدام Newman

Newman هو مشغل سطر أوامر لمجموعات Postman.

ثبّته:

npm install -g newman
Enter fullscreen mode Exit fullscreen mode

صدّر المجموعة والبيئة من Postman، ثم شغّل:

newman run collection.json -e environment.json
Enter fullscreen mode Exit fullscreen mode

إذا فشل أي اختبار، يخرج Newman برمز غير صفري، وهذا يسمح لنظام CI بإفشال الـ pipeline.

مثال مبسط في GitHub Actions:

name: API Tests

on:
  push:
    branches:
      - main

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

    steps:
      - uses: actions/checkout@v4

      - name: Install Newman
        run: npm install -g newman

      - name: Run Postman collection
        run: newman run collection.json -e environment.json
Enter fullscreen mode Exit fullscreen mode

لربط ذلك بخط CI/CD بشكل أوضح، راجع أتمتة اختبارات API في CI/CD.

الجوانب التي يصبح فيها Postman ثقيلًا

Postman مناسب جدًا للاختبار الاستكشافي ومجموعات الاختبار الصغيرة والمتوسطة. لكن مع نمو المشروع تظهر غالبًا مشكلتان:

  1. التأكيدات تُكتب بـ JavaScript، وهذا قد يبطئ أعضاء الفريق الذين يفضلون واجهة مرئية.
  2. التصميم، الاختبار، المحاكاة، والتوثيق قد تعيش في أماكن منفصلة، مما يزيد احتمال اختلاف الاختبارات عن عقد API الحقيقي.

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

إذا كنت تقارن الخيارات، راجع بدائل Postman لاختبار API. ويمكنك تنزيل Apidog واستيراد مجموعة موجودة للمقارنة عمليًا.

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

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

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

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

ما الفرق بين Collection و Environment في Postman؟

الـ Collection تحتوي الطلبات والاختبارات. الـ Environment تحتوي القيم المتغيرة مثل base_url و auth_token.

مثال:

Collection:
- Login
- Get user
- Create user

Environment:
- base_url
- auth_token
Enter fullscreen mode Exit fullscreen mode

يمكنك تشغيل نفس المجموعة على بيئات مختلفة مثل staging و production بتغيير البيئة فقط.

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

استخدم Newman:

newman run collection.json -e environment.json
Enter fullscreen mode Exit fullscreen mode

إذا فشل اختبار، يفشل الأمر، ويمكن لنظام CI إيقاف النشر أو إظهار الخطأ في pipeline.

هل يمكن لـ Postman اختبار أكثر من REST APIs؟

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

كم عدد التأكيدات المناسب لكل طلب؟

اكتب ما يكفي للتحقق من صحة الاستجابة بدون مبالغة. غالبًا يكفي:

  • رمز الحالة
  • زمن الاستجابة
  • الحقول المهمة في JSON
  • رأس مهم مثل Content-Type

مثال جيد:

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

pm.test("Response contains required fields", function () {
    const body = pm.response.json();

    pm.expect(body).to.have.property("id");
    pm.expect(body).to.have.property("email");
});
Enter fullscreen mode Exit fullscreen mode

اجعل كل اختبار يتحقق من توقع واحد قدر الإمكان حتى يكون سبب الفشل واضحًا.

Top comments (0)