DEV Community

Cover image for أداة اختبار API بدون واجهة رسومية: تشغيل اختبارات API في CI
Yusuf Khalidd
Yusuf Khalidd

Posted on • Originally published at apidog.com

أداة اختبار API بدون واجهة رسومية: تشغيل اختبارات API في CI

أداة اختبار واجهة برمجة التطبيقات (API) بلا واجهة مستخدم رسومية (headless) تشغّل اختباراتك من سطر الأوامر، بدون نافذة أو نقر يدوي. هذا يجعلها مناسبة للتكامل المستمر (CI): نفس الفحوصات تعمل محليًا، وعلى جهاز زميلك، وداخل pipeline عند كل push. إذا كنت تبني الاختبارات بصريًا ثم تحتاج تشغيلها على خادم بناء، فالأدوات headless تسد هذه الفجوة. في هذا الدليل سنوضح المفهوم، ونطبّق أمثلة باستخدام واجهة سطر أوامر Apidog، ونقارنها بأدوات مثل Newman وHurl.

جرّب Apidog اليوم

ماذا تعني "بلا واجهة مستخدم رسومية" في اختبار API؟

الأداة headless لا تحتاج إلى واجهة رسومية لكي تعمل. في اختبار API، هذا يعني أنها:

  • تعمل كأمر CLI يمكن تشغيله من سكربت أو pipeline.
  • لا تحتاج إلى شاشة، أو مستخدم مسجل الدخول، أو تفاعل يدوي.
  • تقرأ الاختبارات من ملف، مشروع، مجموعة، أو معرف.
  • ترجع exit code غير صفري عند فشل التأكيدات.
  • تصدر تقارير قابلة للقراءة آليًا مثل JSON وJUnit XML، أو قابلة للقراءة بشريًا مثل CLI وHTML.

الفرق العملي مهم: الواجهة الرسومية تخبر المطوّر بما نجح، أما الأداة headless فتخبر الـ pipeline. بذلك يمكنك إيقاف merge أو deployment عند فشل اختبار API. للمزيد حول ربط ذلك بعمليات CI/CD، راجع أفضل ممارسات CI/CD لاختبار واجهة برمجة التطبيقات (API).

لماذا تنقل الفرق اختبارات API بعيدًا عن GUI؟

العميل المرئي مفيد عند استكشاف endpoint، تعديل header، أو فحص response. لكنه ليس مناسبًا للتكرار الآلي.

بدلًا من تشغيل عشرات الطلبات يدويًا بعد كل commit، يمكنك تعريف السيناريو مرة واحدة وتشغيله بنفس الأمر في كل مكان:

api-test-runner run ./collection.json
Enter fullscreen mode Exit fullscreen mode

هذا يعطيك:

  • نتائج متكررة وقابلة للمقارنة.
  • تشغيلًا آليًا داخل CI.
  • تقارير يمكن حفظها كـ artifacts.
  • دعمًا لاختبارات تعتمد على البيانات لتغطية حالات متعددة من سيناريو واحد.

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

واجهة سطر أوامر Apidog: تشغيل اختبارات API بدون GUI

واجهة سطر أوامر Apidog هي طبقة التشغيل headless في Apidog. يمكنك بناء السيناريوهات وتصحيحها وتنظيمها داخل التطبيق، ثم تشغيلها من الطرفية باستخدام:

apidog run
Enter fullscreen mode Exit fullscreen mode

يدعم الأمر تشغيل سيناريوهات الاختبار، المجلدات، مجموعات الاختبار، أو ملف محلي مُصدّر. بعد التشغيل، يطبع تقريرًا ويرجع exit code يمكن للـ CI استخدامه لتحديد نجاح أو فشل البناء.

1. تشغيل اختبارات تعتمد على البيانات

إذا كان لديك نفس السيناريو مع مدخلات مختلفة، استخدم ملف CSV أو JSON:

apidog run https://api.apidog.com/... \
  -d ./data/users.csv \
  -n 10
Enter fullscreen mode Exit fullscreen mode

الخيارات الأساسية:

  • -d, --iteration-data <path>: ملف CSV أو JSON.
  • -n, --iteration-count: عدد التكرارات.

بهذا يمكنك اختبار حالات مثل مستخدم صحيح، مستخدم غير موجود، صلاحيات مختلفة، أو مدخلات غير صالحة من نفس السيناريو. التفاصيل الكاملة موجودة في اختبار واجهة برمجة التطبيقات (API) المعتمد على البيانات باستخدام واجهة سطر أوامر Apidog.

2. إخراج تقارير مناسبة للبشر والآلات

استخدم الخيار -r, --reporters لتحديد صيغ التقارير:

apidog run https://api.apidog.com/... \
  -r cli,html,junit
Enter fullscreen mode Exit fullscreen mode

الصيغ الشائعة:

  • cli: عرض سريع داخل الطرفية.
  • html: تقرير يمكن مشاركته مع الفريق.
  • json: مناسب للمعالجة اللاحقة.
  • junit: مناسب للوحات CI مثل GitHub Actions وGitLab CI وJenkins.

افتراضيًا، يتم حفظ تقارير HTML وJUnit داخل مجلد:

apidog-reports/
Enter fullscreen mode Exit fullscreen mode

3. التحكم في البيئة والمتغيرات

لتشغيل نفس الاختبارات على بيئات مختلفة:

apidog run https://api.apidog.com/... \
  -e <environment-id>
Enter fullscreen mode Exit fullscreen mode

ولتمرير قيم أثناء التشغيل بدون تخزينها في الملفات:

apidog run https://api.apidog.com/... \
  --env-var baseUrl=https://staging.example.com \
  --env-var token=$API_TOKEN
Enter fullscreen mode Exit fullscreen mode

يمكنك أيضًا استخدام:

--global-var key=value
Enter fullscreen mode Exit fullscreen mode

هذا مفيد للحفاظ على الأسرار خارج المستودع.

مثال CI مبسط 

npm install -g apidog-cli

apidog run https://api.apidog.com/... \
  -e <environment-id> \
  -d ./data/users.csv \
  -r cli,html,junit
Enter fullscreen mode Exit fullscreen mode

يمكنك بعدها جعل نظام CI يجمع مجلد apidog-reports/ كـ artifact.

للبناء من الصفر، راجع الدليل الكامل لواجهة سطر أوامر Apidog، أو اتبع البرنامج التعليمي لسطر أوامر REST API. ولتفاصيل الخيارات، استخدم مرجع أمر apidog run.

استخدام headless مع وكلاء الذكاء الاصطناعي

هناك شكل آخر من التشغيل بلا واجهة رسومية في Apidog: خادم Apidog MCP. يسمح لوكيل ذكاء اصطناعي أو IDE مدعوم بالذكاء الاصطناعي مثل Cursor أو VS Code عبر Cline بقراءة مواصفات API مباشرة.

الفائدة العملية: المساعد يولّد كودًا واختبارات بناءً على عقد API الحقيقي بدل التخمين. هذا سير عمل مختلف عن CLI، لكنه يعتمد على نفس الفكرة: المواصفة تقود التنفيذ بدون واجهة رسومية. يمكنك قراءة التفاصيل في تصحيح الأخطاء المرئي باستخدام عميل Apidog MCP.

أدوات تشغيل أخرى بلا واجهة رسومية

Apidog ليس الخيار الوحيد. الاختيار يعتمد غالبًا على مكان وجود اختباراتك حاليًا.

Newman

Newman هو مشغل مجموعات سطر الأوامر الخاص بـ Postman. إذا كانت اختبارات فريقك موجودة في Postman Collections، فـ Newman هو المسار الطبيعي لتشغيلها داخل CI.

مثال تشغيل:

newman run collection.json \
  -e environment.json \
  -r cli,json,junit
Enter fullscreen mode Exit fullscreen mode

يدعم Newman مُصدّري تقارير مدمجين مثل:

  • cli
  • json
  • junit
  • progress
  • emojitrain

ويمكن إضافة تقرير HTML عبر حزمة npm منفصلة.

Hurl

Hurl يتبع أسلوبًا مختلفًا: تكتب اختباراتك في ملفات نصية بامتداد .hurl.

مثال مبسط:

GET https://api.example.com/users/1
HTTP 200
[Asserts]
jsonpath "$.id" == 1
Enter fullscreen mode Exit fullscreen mode

ثم تشغّلها:

hurl tests/users.hurl
Enter fullscreen mode Exit fullscreen mode

Hurl مناسب إذا كنت تفضل:

  • ملفات نصية عادية.
  • اختبارات يسهل مراجعتها في Git.
  • أداة صغيرة وسريعة مبنية بلغة Rust على libcurl.
  • سير عمل قريب من HTTP الخام.

Hoppscotch CLI

واجهة سطر أوامر Hoppscotch (hopp) تشغل مجموعات Hoppscotch ونصوص الاختبار داخل CI.

يمكنك تمرير collection وenvironment كملفات JSON مصدّرة، أو استخدام معرفات مع access token. كما تدعم بيانات التكرار CSV ومُصدر JUnit عبر:

--reporter-junit
Enter fullscreen mode Exit fullscreen mode

وتُرجع exit code غير صفري عند الفشل. إذا كنت تقيّمها، راجع أفضل بدائل واجهة سطر أوامر Hoppscotch.

مقارنة أدوات التشغيل بلا واجهة رسومية

الأداة مصدر الاختبار مدخلات تعتمد على البيانات مُصدّرو تقارير مدمجون الأفضل عندما
Apidog CLI مشروع Apidog، مجموعات، أو ملف مُصدّر CSV / JSON (-d) cli, html, json, junit تريد التصميم، المحاكاة، الاختبار، والتوثيق في مكان واحد
Newman مجموعات Postman CSV / JSON (-d) cli, json, junit, progress (HTML عبر إضافة) مجموعات Postman هي مصدر الحقيقة لديك
Hurl ملفات .hurl نصية عادية CSV عبر خيارات المشغل JUnit, TAP, JSON تفضل الاختبارات النصية الخاضعة للتحكم في الإصدار
Hoppscotch CLI مجموعات Hoppscotch (ملف أو معرف) CSV (--iteration-data) JUnit فريقك يستخدم Hoppscotch بالفعل

كل هذه الأدوات headless فعلًا: تعمل من أمر، لا تحتاج GUI، وترجع نجاحًا أو فشلًا عبر exit code.

ميزة Apidog ليست فقط تشغيل الاختبارات داخل CI؛ فالأدوات الأخرى تفعل ذلك أيضًا. الميزة أن نفس المشروع يمكن أن يحتوي على العقد، الاختبارات، المحاكاة، والوثائق، ما يقلل تباعد تعريفات الاختبار عن تعريفات API.

كيف تختار الأداة المناسبة؟

ابدأ من الوضع الحالي لفريقك:

  • تستخدم Postman؟ استخدم Newman.
  • تفضل ملفات نصية قابلة للمراجعة في Git؟ استخدم Hurl.
  • تستخدم Hoppscotch؟ استخدم Hoppscotch CLI.
  • تريد مشروعًا واحدًا للتصميم، الاختبار، المحاكاة، والتوثيق؟ استخدم Apidog.

إذا كنت تبدأ من الصفر، ركّز على هذه الأسئلة:

  1. أين ستعيش مواصفات API؟
  2. هل تحتاج تشغيل الاختبارات داخل CI؟
  3. هل تحتاج تقارير JUnit أو HTML؟
  4. هل ستستخدم بيانات CSV/JSON لتكرار الاختبارات؟
  5. هل تريد بناء التأكيدات بصريًا أم كتابتها يدويًا؟

مثال عملي: تشغيل اختبار API داخل GitHub Actions

مثال مبسط لخطوة CI باستخدام Apidog CLI:

name: API Tests

on:
  push:
    branches:
      - main
  pull_request:

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

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Install Apidog CLI
        run: npm install -g apidog-cli

      - name: Run API tests
        run: |
          apidog run https://api.apidog.com/... \
            -e ${{ secrets.APIDOG_ENV_ID }} \
            -d ./data/users.csv \
            -r cli,html,junit
Enter fullscreen mode Exit fullscreen mode

الفكرة نفسها تنطبق على GitLab CI أو Jenkins: ثبّت CLI، شغّل الأمر، اجمع التقارير، واترك exit code يحدد نجاح أو فشل الـ pipeline.

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

هل أداة اختبار API بلا واجهة رسومية هي نفسها أداة CLI؟

في الاستخدام اليومي، نعم تقريبًا.

"بلا واجهة رسومية" تصف السلوك: لا تحتاج GUI.

"CLI" تصف طريقة التشغيل: من سطر الأوامر.

الأهم أنها تعمل بدون مراقبة بشرية وترجع حالة نجاح أو فشل يمكن للـ pipeline قراءتها.

هل يمكن تشغيل هذه الأدوات بدون كتابة نصوص اختبار؟

يعتمد على الأداة.

في Apidog، يمكنك بناء التأكيدات بصريًا ثم تشغيل نفس السيناريوهات من CLI، بدون كتابة إطار اختبار يدوي. Newman وHoppscotch CLI يشغلان مجموعات قد تحتوي على سكربتات اختبار مكتوبة داخل تطبيقاتهما. أما Hurl فيعتمد على ملفات نصية تكتبها بنفسك.

إذا كنت تفضل المسار المرئي ثم التشغيل headless، راجع الدليل الكامل لواجهة سطر أوامر Apidog.

هل تحتاج اختبارات API بلا واجهة رسومية إلى Backend حقيقي؟

ليس دائمًا. يمكنك توجيه الاختبارات إلى:

  • خدمة حقيقية قيد التشغيل.
  • بيئة staging.
  • عنوان URL تجريبي.
  • mock server.

تشغيل mock server داخل CI يسمح باختبار أشكال الطلبات والاستجابات قبل اكتمال الواجهة الخلفية، ويساعد فرق الواجهة الأمامية والتكامل على العمل مبكرًا. يعمل خادم Apidog الوهمي في CI لهذا الغرض.

ما أفضل أداة headless لاختبارات API داخل CI/CD؟

لا توجد إجابة واحدة. الأفضل هو ما يشغل اختباراتك الحالية بأقل إعداد.

  • Newman إذا كانت Postman Collections هي مصدر الحقيقة.
  • Hurl إذا كنت تريد اختبارات نصية بسيطة.
  • Hoppscotch CLI إذا كان فريقك يستخدم Hoppscotch.
  • Apidog CLI إذا كنت تريد توحيد التصميم، المحاكاة، الاختبار، والتوثيق في مشروع واحد.

للمقارنة التفصيلية، راجع Apidog CLI وNewman وApidog CLI وPostman CLI.

الخلاصة

أداة اختبار API بلا واجهة رسومية هي مشغل يمكن برمجته: أمر CLI يقرأ اختباراتك، يستخدم بياناتك، ينتج تقارير، ويرجع exit code مناسبًا للـ CI.

Newman وHurl وHoppscotch CLI خيارات قوية ضمن أنظمتها. Apidog CLI يقدم نفس نمط التشغيل headless، مع ميزة أن الاختبارات، العقود، المحاكاة، والوثائق يمكن أن تعيش في مشروع واحد. إذا أردت تصميم السيناريو مرة وتشغيله في كل مكان، يمكنك تنزيل Apidog.

Top comments (0)