DEV Community

Cover image for كيفية اختبار GraphQL APIs في Apidog (الاستعلامات، التحويرات، والأتمتة)
Yusuf Khalidd
Yusuf Khalidd

Posted on • Originally published at apidog.com

كيفية اختبار GraphQL APIs في Apidog (الاستعلامات، التحويرات، والأتمتة)

لديك نقطة نهاية GraphQL وتريد اختبار السلوك الفعلي، لا مجرد التأكد من أن الخادم يعمل: هل يعيد استعلام user الحقول التي يستهلكها التطبيق؟ هل تحفظ عملية createOrder طلبًا جديدًا؟ وهل تبقى الاستجابة صحيحة عند تغيير المتغيرات؟ بما أن GraphQL يرسل العمليات إلى عنوان URL واحد عادةً عبر POST، فأنت تحتاج إلى عميل يفهم الاستعلامات والمخطط والمتغيرات، ويتيح لك التحقق من JSON الناتج.

جرّب Apidog اليوم

يتعامل Apidog مع GraphQL كنوع طلب أساسي إلى جانب HTTP وgRPC وWebSocket وSSE وSOAP. في هذا الدليل ستنشئ طلب GraphQL، وتجلب المخطط لتفعيل الإكمال التلقائي، وتمرر المتغيرات، وتشغّل mutation لإنشاء طلب، ثم تضيف تحققًا قابلًا للتكرار. يعتمد المثال على API لمتجر إلكتروني. وللتفاصيل النظرية، راجع وثائق GraphQL الرسمية ومقارنة REST وGraphQL.

ما الذي تختبره ولماذا يختلف GraphQL

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

لذلك يختلف الاختبار في نقطتين أساسيتين:

  1. الطلب عبارة عن مستند GraphQL داخل الجسم، لا عنوان URL مختلفًا لكل مورد. بدلًا من: 
   GET /users/42
Enter fullscreen mode Exit fullscreen mode

ترسل عملية مثل:

   user(id: 42) {
     ...
   }
Enter fullscreen mode Exit fullscreen mode
  1. رمز HTTP 200 OK لا يعني بالضرورة نجاح العملية. قد يعيد GraphQL حالة 200 OK مع مصفوفة errors في الجسم: 
   {
     "data": null,
     "errors": [
       {
         "message": "User not found"
       }
     ]
   }
Enter fullscreen mode Exit fullscreen mode

لذلك لا تعتمد على رمز الحالة فقط. يجب أن تتحقق من errors ومن القيم داخل data.

إنشاء طلب GraphQL في Apidog

ابدأ بتنزيل Apidog أو فتحه من المتصفح، ثم افتح مشروعك أو أنشئ مشروعًا جديدًا.

الخطوة 1: أنشئ طلبًا واضبط الجسم على GraphQL

  1. انقر على +.
  2. اختر New Request.
  3. اضبط الطريقة على POST.
  4. أضف عنوان نقطة نهاية GraphQL: 
   https://api.yourstore.com/graphql
Enter fullscreen mode Exit fullscreen mode
  1. افتح قسم Body.
  2. اختر GraphQL.

سيظهر محرر يحتوي على حقل Query لكتابة العملية، وحقل للمتغيرات عند الحاجة.

إذا كانت نقطة النهاية محمية، افتح Authorization وأضف رمز Bearer أو آلية التخويل المطلوبة. رغم أن محتوى الجسم هو GraphQL، يبقى الطلب في الأساس طلب HTTP عاديًا.

الخطوة 2: اكتب استعلامًا أوليًا

في تبويب Run، أضف استعلامًا لجلب مستخدم وطلباته:

query GetUserWithOrders {
  user(id: "usr_1024") {
    id
    name
    email
    orders {
      id
      total
      status
      createdAt
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

هذا الاستعلام يطلب مستخدمًا واحدًا وقائمة طلباته المتداخلة. يجب أن تتطابق أسماء الحقول، مثل email وcreatedAt، مع مخطط API الفعلي.

الخطوة 3: اجلب المخطط لتفعيل الإكمال التلقائي

بدل تخمين أسماء الحقول والأنواع:

  1. تأكد من تعيين عنوان URL الصحيح.
  2. انقر على Fetch Schema.
  3. انتظر حتى ينتهي طلب الاستكشاف (introspection).
  4. ابدأ كتابة حقل داخل الاستعلام للحصول على اقتراحات صالحة من المخطط.

بعد جلب المخطط، يساعدك المحرر على اكتشاف:

  • الحقول المتاحة لكل نوع.
  • أنواع الوسائط والمدخلات.
  • الحقول المتداخلة الصالحة.
  • أخطاء التهجئة قبل إرسال الطلب.

الإكمال التلقائي لا يبدأ تلقائيًا؛ يجب تشغيل Fetch Schema يدويًا. إذا كانت بيئة الإنتاج تعطل الاستكشاف لأسباب أمنية، استخدم وثائق API أو مخططًا متاحًا داخليًا. وأعد الجلب بعد أي تعديل على المخطط.

الخطوة 4: شغّل الطلب وافحص بنية الاستجابة

انقر على Send. قد تكون الاستجابة الناجحة بهذا الشكل:

{
  "data": {
    "user": {
      "id": "usr_1024",
      "name": "Dana Whitfield",
      "email": "dana@example.com",
      "orders": [
        {
          "id": "ord_5001",
          "total": 89.9,
          "status": "SHIPPED",
          "createdAt": "2026-07-01T09:14:00Z"
        },
        {
          "id": "ord_5002",
          "total": 12.5,
          "status": "PENDING",
          "createdAt": "2026-07-12T16:03:00Z"
        }
      ]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

توجد نتيجة العملية داخل data. عند كتابة تأكيداتك لاحقًا، استخدم مسارات مثل:

$.data.user.id
$.data.user.orders
Enter fullscreen mode Exit fullscreen mode

ولا تفترض أن القيم موجودة في جذر الاستجابة.

تمرير المتغيرات لجعل الطلب قابلًا لإعادة الاستخدام

تشفير "usr_1024" داخل الاستعلام مناسب للتجربة السريعة، لكنه غير مناسب لاختبار قابل لإعادة الاستخدام. استخدم متغيرات GraphQL لتغيير القيم دون تعديل الاستعلام نفسه. راجع وثائق متغيرات GraphQL للصيغة القياسية.

عدّل الاستعلام كالتالي:

query GetUserWithOrders($userId: ID!) {
  user(id: $userId) {
    id
    name
    orders {
      id
      total
      status
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

ثم أضف القيمة في جسم المتغيرات:

{
  "userId": "usr_1024"
}
Enter fullscreen mode Exit fullscreen mode

الآن يمكنك تشغيل العملية للمستخدمين المختلفين بتغيير JSON فقط.

لجعل الطلب يعمل بين البيئات، استخدم متغيرات البيئة في Apidog لعنوان الخادم أو قيم التخويل، مثل:

{{baseUrl}}/graphql
Enter fullscreen mode Exit fullscreen mode

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

كتابة mutation لإنشاء طلب

تستخدم mutation لتغيير البيانات. لا تحتاج إلى تبويب منفصل: اكتبها في مربع Query نفسه، لكن استخدم الكلمة المفتاحية mutation بدل query.

مثال لإنشاء طلب جديد:

mutation CreateOrder($input: CreateOrderInput!) {
  createOrder(input: $input) {
    id
    total
    status
    createdAt
  }
}
Enter fullscreen mode Exit fullscreen mode

مرر الحمولة عبر المتغيرات:

{
  "input": {
    "userId": "usr_1024",
    "items": [
      {
        "sku": "TSHIRT-BLK-M",
        "quantity": 2
      },
      {
        "sku": "MUG-CERAMIC",
        "quantity": 1
      }
    ],
    "currency": "USD"
  }
}
Enter fullscreen mode Exit fullscreen mode

بعد الضغط على Send، قد تحصل على استجابة مثل:

{
  "data": {
    "createOrder": {
      "id": "ord_5003",
      "total": 42.3,
      "status": "PENDING",
      "createdAt": "2026-07-15T10:22:11Z"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

لا تشغّل عمليات الكتابة على الإنتاج أثناء الاختبار. استخدم بيئة اختبار أو مرحلة.

نمط عملي مفيد للاختبار:

  1. شغّل استعلام المستخدم.
  2. شغّل createOrder.
  3. احفظ id الطلب الناتج.
  4. أعد تشغيل استعلام المستخدم.
  5. تحقق من ظهور الطلب الجديد ضمن orders.

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

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

بالنسبة لطلبات GraphQL، أضف هذه التحققات:

  • تأكيد أن حالة HTTP تساوي 200.
  • تأكيد غياب الحقل errors.
  • تأكيد القيم المتوقعة داخل data.

أمثلة لمسارات JSONPath:

$.data.createOrder.status
$.data.createOrder.id
$.data.user.orders
Enter fullscreen mode Exit fullscreen mode

أمثلة للتحقق:

التحقق القيمة المتوقعة
حالة HTTP 200
errors غير موجود
$.data.createOrder.status PENDING
$.data.createOrder.id موجود وغير فارغ
$.data.user.orders الطول أكبر من صفر

هذا يمنع حالات الفشل الشائعة، مثل استجابة 200 تحتوي على errors، أو نجاح العملية مع بنية استجابة غير متوقعة.

احفظ التدفق في سيناريو اختبار

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

  1. جلب مستخدم.
  2. إنشاء طلب جديد.
  3. استخراج id من استجابة createOrder.
  4. جلب المستخدم أو الطلب مرة أخرى.
  5. التحقق من استمرار البيانات الجديدة.

تتيح لك سيناريوهات Apidog تمرير البيانات بين الخطوات وتشغيل التدفق كاملًا بنقرة واحدة. راجع كيفية كتابة سيناريو اختبار باستخدام Apidog لإعداد السيناريو.

اربط التأكيدات بكل خطوة، خصوصًا:

  • غياب errors.
  • وجود معرف الطلب بعد الإنشاء.
  • تطابق حالة الطلب مع القيمة المتوقعة.
  • ظهور الطلب في الاستعلام اللاحق.

للمقارنة بين الأساليب المختلفة، راجع REST مقابل GraphQL مقابل gRPC وأدوات اختبار ومحاكاة GraphQL. وإذا كنت تختبر SOAP أيضًا، فراجع كيفية اختبار واجهات برمجة تطبيقات SOAP في Apidog.

أتمتة سير العمل باستخدام Apidog CLI

بعد حفظ السيناريوهات في المشروع، يمكنك تشغيل سيناريوهات الاختبار المحفوظة من الطرفية أو من مشغل تكامل مستمر.

ثبّت Apidog CLI وسجّل الدخول:

npm install -g apidog-cli
apidog login --with-token <your-token>
Enter fullscreen mode Exit fullscreen mode

شغّل سيناريو محفوظًا باستخدام معرف السيناريو والبيئة:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
Enter fullscreen mode Exit fullscreen mode

المعاملات الأساسية:

  • -t: معرف سيناريو الاختبار.
  • -e: معرف البيئة.
  • -r: نوع التقرير، مثل cli أو html أو junit.

يمكنك إنشاء أكثر من تقرير:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r html,cli
Enter fullscreen mode Exit fullscreen mode

تشير وثائق CLI إلى تنفيذ سيناريوهات HTTP، لكنها لا تؤكد صراحة دعم السيناريوهات التي تحتوي خطوات GraphQL دون واجهة رسومية. استخدم CLI لتشغيل اختبارات HTTP المحفوظة ومزامنة المواصفات عبر أمر import، ونفّذ عمليات GraphQL والاستعلامات والتحقق منها داخل التطبيق عند الحاجة.

للتفاصيل، راجع دليل تثبيت Apidog CLI وApidog CLI في خط أنابيب GitHub Actions.

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

هل أحتاج إلى خطة مدفوعة لاختبار GraphQL في Apidog؟

لا تقيد وثائق طلب GraphQL هذه الميزة بخطة محددة. يمكنك البدء بالطبقة المجانية ومراجعة Apidog لمعرفة تفاصيل الخطط الحالية.

لماذا يعيد طلب GraphQL حالة 200 لكنه يفشل؟

لأن نجاح النقل عبر HTTP لا يضمن نجاح عملية GraphQL. تحقق دائمًا من غياب errors بالإضافة إلى فحص حالة HTTP، كما هو موضح في تأكيدات API.

كيف أحصل على اقتراحات الحقول أثناء كتابة الاستعلام؟

انقر على Fetch Schema بعد إدخال عنوان نقطة النهاية. يجلب Apidog المخطط ويتيح اقتراح الحقول والأنواع الصالحة في المحرر. أعد جلب المخطط بعد تغييره.

أين أكتب mutation؟

اكتبها في مربع Query نفسه. استبدل query بـmutation، ومرر البيانات عبر المتغيرات، ثم انقر على Send.

كيف أغيّر القيم دون إعادة كتابة الاستعلام؟

عرّف متغيرات GraphQL في توقيع العملية، ثم مرر قيمها ككائن JSON. استخدم صيغة متغيرات GraphQL القياسية، واربِطها بمتغيرات البيئة عند الحاجة.

خاتمة

لاختبار GraphQL عمليًا:

  1. أنشئ طلب POST واضبط الجسم على GraphQL.
  2. اكتب الاستعلام في مربع Query.
  3. استخدم Fetch Schema لتقليل أخطاء الحقول والأنواع.
  4. انقل القيم الثابتة إلى متغيرات.
  5. تحقق من errors ومن القيم داخل data.
  6. اختبر mutation في بيئة غير إنتاجية.
  7. اجمع الاستعلامات والتغييرات في سيناريو قابل لإعادة التشغيل.

ابدأ ببناء تدفق المستخدم والطلبات، ثم احفظه كسيناريو تراجعي تشغله كلما تغير مخطط GraphQL أو منطق API.

Top comments (0)