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

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

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

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

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

يتغير شيئان. أولاً، الطلب هو مستند استعلام في الجسم، وليس عنوان URL تقوم بتغييره. يصبح GET /users/42 اختيارًا مثل user(id: 42) { ... } يتم إرساله عبر POST. ثانيًا، لا يعيد GraphQL تقريبًا أبدًا حالة غير 200 لخطأ تجاري. لا يزال الاستعلام الفاشل يعود بـ 200 OK مع مصفوفة errors في JSON. لذا، فإن التحقق من رمز الحالة لا يكفي. يجب عليك قراءة الجسم. هذه الحقيقة الوحيدة تشكل كيفية التحقق لاحقًا في هذا الدليل.

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

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

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

الخطوة 1: قم بإنشاء طلب جديد وقم بتحويل الجسم إلى GraphQL

انقر فوق الزر + واختر New Request (طلب جديد). سيؤدي هذا إلى فتح منشئ الطلبات القياسي، وهو نفسه الذي ستستخدمه لاستدعاء REST: الطريقة، عنوان URL، المعلمات، و Authorization (التخويل).

اضبط الطريقة على POST والصق نقطة نهاية GraphQL الخاصة بك في شريط عنوان URL. يبدو العنوان النموذجي كالتالي:

https://api.yourstore.com/graphql

الآن أخبر Apidog أن هذا طلب GraphQL. في منطقة جسم الطلب، انقر فوق Body (الجسم)، ثم حدد GraphQL. يتغير محرر الجسم إلى عرض يراعي GraphQL مع مربع Query (الاستعلام)، وهو المكان الذي توجد فيه لغة الاستعلام.

إذا كانت نقطة النهاية الخاصة بك تحتاج إلى رمز مميز، فافتح قسم Authorization (التخويل) وأضفه هناك، على سبيل المثال رمز Bearer. يعمل التخويل في طلب GraphQL بنفس طريقة أي طلب HTTP آخر في Apidog، لأنه في الأساس لا يزال طلب HTTP POST.

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

في علامة التبويب Run (تشغيل)، اكتب استعلامك في مربع Query (الاستعلام). ابدأ بشيء ملموس. هنا تريد مستخدمًا والطلبات المرتبطة به:

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

يطلب هذا استعلامًا عن مستخدم واحد وقائمة متداخلة من طلباته. يجب أن تتطابق أسماء الحقول مع مخطط الخادم الخاص بك تمامًا. إذا كان مخططك يسميها emailAddress بدلاً من email، فسيفشل هذا الاستعلام. هذه هي مهمة الخطوة التالية لمنع ذلك.

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

تخمين أسماء الحقول هو ما يجعل اختبار GraphQL بطيئًا. يمكن لـ Apidog قراءة مخططك بحيث يقترح المحرر حقولًا وأنواعًا صالحة أثناء الكتابة، بدلاً من التحقق المتقاطع من مستند في علامة تبويب أخرى.

هذا إجراء يدوي، عند الطلب. انقر فوق زر Fetch Schema (جلب المخطط) في مربع الإدخال. يقوم Apidog بتشغيل استعلام استكشافي (introspection query) مقابل نقطة النهاية الخاصة بك ويسحب نظام النوع. بمجرد نجاحه، يتم تشغيل إكمال التعليمات البرمجية: ابدأ بكتابة حقل داخل تحديد وستحصل على اقتراحات بأسلوب IntelliSense لما هو متاح بالفعل على هذا النوع.

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

الخطوة 4: قم بتشغيله واقرأ الاستجابة

انقر فوق Send (إرسال). تظهر الاستجابة في النصف السفلي من الواجهة. تبدو النتيجة الصحية كالتالي:

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

لاحظ المفتاح الأعلى مستوى data. كل استجابة GraphQL تضع نتيجتك تحت data، وتظهر أي مشاكل في مصفوفة errors المجاورة. ضع هذا الهيكل في الاعتبار، لأن تأكيداتك ستشير إلى data.user...، وليس إلى الجذر.

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

يعمل تشفير `\"usr_1024\"` بشكل ثابت في الاستعلام لمرة واحدة. لطلب ستقوم بإعادة تشغيله عبر المستخدمين والبيئات، انقل تلك القيمة إلى متغير. يحتوي GraphQL على صيغة متغيرات من الدرجة الأولى لذلك، ويدعمها Apidog. الصيغة نفسها هي GraphQL قياسية وليست اختراعًا من Apidog، لذا فإن وثائق GraphQL الرسمية حول المتغيرات هي مصدر الحقيقة.

صرح بالمتغير في توقيع الاستعلام ببادئة $ ونوع، ثم استخدمه في الوسائط:

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

ثم قم بتزويد القيمة ككائن JSON صغير من المتغيرات:

{
  "userId": "usr_1024"
}

الآن يعمل نفس الاستعلام لأي مستخدم بتغيير قيمة JSON واحدة. قم بإقران هذا بمتغيرات بيئة Apidog ويمكنك توجيه الطلب المتطابق إلى بيئات الاختبار والإنتاج دون تعديل الاستعلام. هذا ما يحول استدعاء لمرة واحدة إلى شيء يمكنك حفظه ومشاركته وتشغيله في مجموعة.

كتابة تغيير (mutation) لإنشاء طلب

يغير التغيير (mutation) البيانات. في GraphQL لا يوجد بروتوكول أو واجهة مستخدم منفصلة لذلك؛ يتم كتابة التغيير كـ GraphQL في نفس مربع Query (الاستعلام)، مع الكلمة المفتاحية mutation بدلاً من query. لذلك فإن سير العمل الذي تعرفه بالفعل ينتقل مباشرة.

هنا تقوم بإنشاء طلب للمستخدم الذي استعلمت عنه سابقًا:

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

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

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

انقر فوق Send (إرسال). تستجيب الاستجابة الجيدة للطلب الذي تم إنشاؤه:

{
  "data": {
    "createOrder": {
      "id": "ord_5003",
      "total": 42.30,
      "status": "PENDING",
      "createdAt": "2026-07-15T10:22:11Z"
    }
  }
}

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

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

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

بالنسبة لـ GraphQL، تغطي ثلاث عمليات تحقق معظم الحالات:

• تأكيد أن حالة HTTP هي 200. ضروري ولكنه غير كافٍ، نظرًا لأن GraphQL يعيد 200 حتى في حالة أخطاء الأعمال.
• تأكيد أن حقل errors غائب. هذا هو البوابة الحقيقية لنجاح أو فشل GraphQL. إذا كان errors موجودًا، فقد فشلت العملية بغض النظر عما تقوله الحالة.
• تأكيد قيم محددة داخل data، باستخدام JSONPath مثل $.data.createOrder.status يساوي PENDING، أو $.data.user.orders يبلغ طوله أكبر من صفر.

تكتشف هذه المجموعة أنماط الفشل التي يفوتها فحص الحالة فقط: استعلام يعيد 200 مع مصفوفة errors، أو استعلام ينجح ولكنه يعيد شكلاً خاطئًا. وجه تأكيدات قيمك إلى المسار المتداخل تحت data، متطابقًا مع بنية الاستجابة التي رأيتها سابقًا.

احفظه في سيناريو اختبار

الطلب الوحيد المؤكد هو اختبار دخان جيد. العائد الحقيقي يكمن في ربط الطلبات في سيناريو: استعلام عن المستخدم، إنشاء طلب، ثم الاستعلام مرة أخرى لتأكيد استمراره. تتيح لك سيناريوهات اختبار Apidog تسلسل هذه الخطوات، وتمرير البيانات بينها (التقاط id من التغيير، وتزويده إلى الاستعلام التأكيدي)، وتشغيل التدفق بالكامل بنقرة واحدة. يتوفر الشرح الكامل في كيفية كتابة سيناريو اختبار باستخدام Apidog.

على مستوى عالٍ: أنشئ سيناريو اختبار جديدًا، أضف استعلام GraphQL والتغيير (mutation) الخاصين بك كخطوات بالترتيب، استخرج id الطلب من استجابة التغيير إلى متغير، وارجع إلى هذا المتغير في خطوة الاستعلام النهائية. أرفق التأكيدات من القسم السابق بكل خطوة. الآن لديك اختبار تراجعي قابل للتكرار لواجهة برمجة تطبيقات GraphQL الخاصة بك يمكن أن يقوم به إنسان أو جدول زمني أو خط أنابيب.

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

أتمتة سير العمل باستخدام سطر أوامر Apidog (CLI)

بمجرد أن توجد سيناريوهات GraphQL الخاصة بك في المشروع، يمكنك تشغيل سيناريوهات الاختبار المحفوظة للمشروع من طرفية أو مشغل تكامل مستمر (CI) باستخدام Apidog CLI. قم بتثبيته وتسجيل الدخول:

npm install -g apidog-cli
apidog login --with-token <your-token>

ثم قم بتشغيل سيناريو محفوظ حسب المعرف، موجهًا إلى بيئة:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli

هنا -t هو معرف سيناريو الاختبار، -e هو معرف البيئة، و -r هو المُبلغ (cli أو html أو junit؛ افصل بينها بفاصلة، مثل -r html,cli، لأكثر من واحد). يشغل سطر الأوامر (CLI) السيناريوهات المحفوظة وحزم الاختبار من مشروعك السحابي ويبلغ عن النجاح أو الفشل، وهو ما يربط Apidog بعملية البناء. تحذير صادق واحد: تؤكد وثائق CLI تنفيذ سيناريو HTTP، ولا تذكر ما إذا كانت السيناريوهات التي تحتوي على خطوات GraphQL تعمل بدون واجهة رسومية. عامل CLI كمحرك لتشغيل اختبارات الانحدار لـ HTTP وللحفاظ على المواصفات متزامنة عبر أمر import الخاص به (OpenAPI، HAR، Postman، والمزيد)، وقم بأعمال استعلام GraphQL، والتغيير، والتحقق في التطبيق. راجع دليل تثبيت Apidog CLI لإعداد الرمز المميز وApidog CLI في خط أنابيب GitHub Actions لربطه بالتكامل المستمر (CI).

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

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

لماذا يعيد طلب GraphQL الخاص بي 200 ولكنه لا يزال يفشل؟ هذا سلوك GraphQL طبيعي. نجح النقل، لذا حالة HTTP هي 200، ولكن العملية واجهت خطأ تجاريًا أو خطأ تحقق يقع في مصفوفة errors في جسم JSON. تأكد دائمًا من أن errors غائب بالإضافة إلى التحقق من الحالة، كما هو موضح في تأكيدات API.

كيف أحصل على اقتراحات الحقول أثناء كتابة الاستعلام؟ انقر فوق زر Fetch Schema (جلب المخطط) في مربع الإدخال. يقوم Apidog بفحص نقطة النهاية الخاصة بك ويمكّن إكمال التعليمات البرمجية بحيث يقترح المحرر حقولًا وأنواعًا صالحة. إنها خطوة يدوية وليست تلقائية، لذا انقر عليها بمجرد تعيين عنوان URL لنقطة النهاية الخاصة بك، وأعد جلبها بعد أي تغيير في المخطط.

أين تذهب التغييرات (mutations)؟ لا أرى علامة تبويب منفصلة للتغيير. لا توجد واحدة. يتم كتابة التغيير (mutation) كـ GraphQL في نفس مربع Query (الاستعلام)، باستخدام الكلمة المفتاحية mutation بدلاً من query. قم بتمرير حمولتها عبر المتغيرات، ثم انقر فوق Send (إرسال)، تمامًا مثل الاستعلام.

كيف أقوم بتمرير قيم مختلفة دون إعادة كتابة الاستعلام؟ استخدم متغيرات GraphQL. صرح بها في توقيع العملية ببادئة $ وقدم كائن JSON من القيم. تتبع الصيغة مواصفات GraphQL القياسية، ويدعم Apidog المتغيرات بالاقتران مع متغيرات البيئة بحيث يتم تشغيل طلب واحد عبر بيئات الاختبار والإنتاج.

خاتمة

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