DEV Community

Cover image for كيفية الترحيل من Hoppscotch CLI إلى Apidog CLI
Yusuf Khalidd
Yusuf Khalidd

Posted on • Originally published at apidog.com

كيفية الترحيل من Hoppscotch CLI إلى Apidog CLI

تُعد Hoppscotch CLI خيارًا بسيطًا ومجانيًا لتشغيل مجموعات واجهات برمجة التطبيقات داخل الطرفية أو ضمن مسارات CI. يقرأ الأمر hopp test ملف المجموعة، ينفّذ الطلبات، يشغّل سكربتات ما قبل الطلب والاختبارات، ثم يُرجع رمز خروج غير صفري عند فشل أي تأكيد. إذا كان هذا هو كل ما تحتاجه، فقد تكون Hoppscotch كافية.

جرّب Apidog اليوم

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

متى يجب عليك الترحيل؟ ومتى لا يجب عليك؟

ابقَ على Hoppscotch CLI إذا كان احتياجك الوحيد هو:

  • تشغيل مجموعة API داخل CI.
  • استخدام أداة مجانية ومفتوحة المصدر.
  • استضافة الأداة ذاتيًا عند الحاجة.
  • التعامل مع ملفات JSON محلية فقط.

قم بالترحيل إلى Apidog عندما تصبح هذه النقاط جزءًا من عملك اليومي:

  • تصميم الـ APIs في أداة، والمحاكاة في أداة أخرى، والتوثيق في مكان ثالث.
  • الحاجة إلى توحيد الاختبارات، الخوادم الوهمية، والوثائق حول تعريف مشروع واحد.
  • الحاجة إلى تقارير HTML أو JSON وسجل تشغيل قابل للمشاركة.
  • إدارة الـ endpoints، schemas، environments، وbranches كجزء من مشروع API وليس كملفات منفصلة فقط.

الفكرة الأساسية: لا تنتقل لأن أمر التشغيل مختلف، بل لأنك تريد نقل دورة عمل الـ API بالكامل إلى مصدر حقيقة واحد.

الخطوة 1: تصدير مجموعة وبيئة Hoppscotch

كل شيء تقريبًا في Hoppscotch قابل للتصدير كـ JSON.

من تطبيق Hoppscotch:

  1. افتح المجموعة التي تشغلها حاليًا في CI.
  2. من قائمة المجموعة اختر Export.
  3. احفظ الملف مثلًا باسم: 
./collections/checkout-api.json
Enter fullscreen mode Exit fullscreen mode
  1. افتح لوحة البيئات.
  2. صدّر البيئة المستخدمة في CI، مثل: 
./environments/staging.json
Enter fullscreen mode Exit fullscreen mode

إذا كنت تستخدم Hoppscotch CLI بالفعل، فقد تكون الملفات موجودة لديك ضمن المستودع:

npm i -g @hoppscotch/cli

hopp test ./collections/checkout-api.json \
  -e ./environments/staging.json
Enter fullscreen mode Exit fullscreen mode

احتفظ بهذين الملفين:

  • checkout-api.json: مجموعة الطلبات.
  • staging.json: متغيرات البيئة.

ملاحظة: يتطلب Hoppscotch CLI الحالي Node.js v22 أو أحدث. إذا كان فريقك يستخدم Node 20، فقد تحتاج إلى البقاء على CLI v0.26.0. الترحيل إلى Apidog قد يكون فرصة لتقليل هذا القيد في بيئة CI.

الخطوة 2: استيراد المجموعة إلى Apidog

أنشئ مشروعًا في Apidog، أو افتح مشروعًا موجودًا، ثم استورد ملف Hoppscotch الذي صدّرته.

خطوات عملية:

  1. افتح مشروع Apidog.
  2. اختر خيار الاستيراد.
  3. ارفع ملف المجموعة: 
./collections/checkout-api.json
Enter fullscreen mode Exit fullscreen mode
  1. إذا كان لديك ملف OpenAPI منفصل، استورده أيضًا.
  2. أنشئ بيئة في Apidog باسم مطابق مثل Staging.
  3. أضف متغيرات البيئة بنفس الأسماء الموجودة في Hoppscotch.

مثال:

{
  "base_url": "https://api.example.com",
  "api_token": "xxx"
}
Enter fullscreen mode Exit fullscreen mode

حافظ على أسماء المتغيرات كما هي:

  • base_url
  • api_token
  • أي متغيرات مستخدمة داخل URLs أو headers أو test scripts.

بهذا تقلل الحاجة إلى تعديل الطلبات أو السكربتات بعد الاستيراد.

بعد الاستيراد، تصبح الـ endpoints جزءًا من مشروع Apidog. يمكنك ربطها بالمخططات، استخدامها في mock server، ونشر الوثائق من نفس التعريف الذي تختبره.

للمزيد بعد الإعداد، راجع دليل Apidog CLI الشامل ودليل التثبيت.

الخطوة 3: تحويل hopp test إلى apidog run

النموذج الذهني متشابه:

  • Hoppscotch يشغّل ملف مجموعة.
  • Apidog يشغّل سيناريو اختبار أو مجموعة من داخل المشروع.

قبل الترحيل:

hopp test ./collections/checkout-api.json \
  -e ./environments/staging.json
Enter fullscreen mode Exit fullscreen mode

بعد الترحيل:

apidog run \
  --access-token $APIDOG_TOKEN \
  -e "Staging"
Enter fullscreen mode Exit fullscreen mode

في الحالتين، يتوقع CI نفس السلوك المهم:

  • تنفيذ الطلبات.
  • تشغيل pre-request scripts.
  • تشغيل assertions.
  • إرجاع exit code غير صفري عند الفشل.

هذا يعني أن منطق نجاح أو فشل الـ pipeline لا يحتاج إلى إعادة تصميم.

المصادقة

في Hoppscotch قد تستخدم:

hopp test collection.json --token <pat>
Enter fullscreen mode Exit fullscreen mode

في Apidog استخدم access token:

apidog run --access-token $APIDOG_TOKEN
Enter fullscreen mode Exit fullscreen mode

احفظ الرمز في متغير بيئة أو secret داخل CI، ولا تضعه داخل السكربت مباشرة. إذا احتجت تفاصيل أكثر، راجع دليل المصادقة.

الخطوة 4: تحويل الاختبارات المعتمدة على البيانات

إذا كنت تستخدم CSV أو JSON لتشغيل نفس الاختبار بعدة مدخلات، يمكنك نقل هذا النمط أيضًا.

في Hoppscotch:

hopp test ./collections/checkout-api.json \
  -e ./environments/staging.json \
  --iteration-count 50 \
  --iteration-data ./data/orders.csv
Enter fullscreen mode Exit fullscreen mode

في Apidog:

apidog run \
  --access-token $APIDOG_TOKEN \
  -e "Staging" \
  -d ./data/orders.csv
Enter fullscreen mode Exit fullscreen mode

مثال لملف orders.csv:

order_id,amount,currency
1001,25,USD
1002,40,EUR
1003,15,USD
Enter fullscreen mode Exit fullscreen mode

تُستخدم أسماء الأعمدة كمتغيرات داخل الطلبات والاختبارات. لذلك إذا كانت سكربتاتك تعتمد على أسماء مثل order_id أو amount، حافظ على نفس أسماء الأعمدة.

انتبه: في Hoppscotch الخيار -d يعني delay بالميلي ثانية، أما في Apidog فيُستخدم -d لملف البيانات. هذا أحد أكثر أخطاء الترحيل شيوعًا.

راجع دليل الاختبار المعتمد على البيانات لتفاصيل ربط الأعمدة بالمتغيرات.

الخطوة 5: تحويل التقارير

في Hoppscotch، قد تعتمد على JUnit XML:

hopp test ./collections/checkout-api.json \
  -e ./environments/staging.json \
  --reporter-junit ./reports/results.xml
Enter fullscreen mode Exit fullscreen mode

في Apidog يمكنك استخدام تقارير CLI أو HTML أو JSON، مع إمكانية رفع التقرير لسجل تشغيل سحابي.

مثال لتقرير HTML:

apidog run \
  --access-token $APIDOG_TOKEN \
  -e "Staging" \
  -r html \
  --upload-report
Enter fullscreen mode Exit fullscreen mode

استخدم:

  • -r html عندما تريد تقريرًا قابلًا للمشاركة مع الفريق أو أصحاب المصلحة.
  • -r json عندما تريد استهلاك النتائج آليًا.
  • --upload-report عندما تريد سجل تشغيل قابلًا للرجوع إليه.

إذا كان نظام CI لديك يعتمد تحديدًا على JUnit XML، ضع هذا في خطة الترحيل لأن Apidog يعتمد على تقارير CLI/HTML/JSON والتقارير السحابية بدلًا من نفس علم JUnit المستخدم في Hoppscotch.

راجع دليل تقارير الاختبار لاختيار التنسيق المناسب.

قبل وبعد: ربط الأوامر

المهمة Hoppscotch CLI Apidog CLI
التثبيت npm i -g @hoppscotch/cli وفقًا لـ دليل التثبيت
تشغيل مجموعة hopp test collection.json apidog run
تحديد البيئة -e env.json -e "Staging"
رمز المصادقة --token <pat> login / --access-token
الهدف المستضاف ذاتيًا / السحابي --server <url> project + access token
مدخلات قائمة على البيانات --iteration-data orders.csv -d orders.csv
تشغيل متكرر --iteration-count 50 مجموعة بيانات التكرار
إضافة تأخير بين الطلبات -d <ms> إعدادات كل سيناريو
تقرير JUnit --reporter-junit results.xml -r json أو CLI / HTML
سجل تشغيل السحابة غير مدمج --upload-report

الخطوة 6: تشغيل Apidog داخل GitHub Actions

لا تحذف خطوة Hoppscotch مباشرة. أضف Apidog بجانبها أولًا، تأكد من أن النتائج ناجحة، ثم احذف الخطوة القديمة.

مثال عملي:

name: API tests

on: [push, pull_request]

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

    steps:
      - uses: actions/checkout@v4

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

      - name: Run API tests
        env:
          APIDOG_TOKEN: ${{ secrets.APIDOG_TOKEN }}
        run: |
          apidog run \
            --access-token "$APIDOG_TOKEN" \
            -e "Staging" \
            -d ./data/orders.csv \
            -r html \
            --upload-report
Enter fullscreen mode Exit fullscreen mode

نفّذ الترحيل بهذا الترتيب:

  1. أضف APIDOG_TOKEN إلى GitHub Secrets.
  2. أضف job أو step جديدة لـ Apidog.
  3. شغّلها بجانب Hoppscotch لعدة مرات.
  4. قارن النتائج.
  5. بعد استقرارها، احذف خطوة Hoppscotch وتثبيت @hoppscotch/cli.

بما أن apidog run يُرجع exit code غير صفري عند فشل أي assertion، سيظل سلوك فشل الـ build واضحًا ومتوافقًا مع ما يعتمد عليه فريقك.

راجع دليل GitHub Actions ودليل CI/CD إذا كنت تستخدم GitLab أو Jenkins أو إعدادات أكثر تعقيدًا.

قائمة تحقق سريعة للترحيل

استخدم هذه القائمة قبل حذف Hoppscotch من CI:

  • [ ] تم تصدير مجموعة Hoppscotch.
  • [ ] تم تصدير البيئة المستخدمة في CI.
  • [ ] تم استيراد المجموعة إلى Apidog.
  • [ ] تم إنشاء بيئة Apidog بنفس أسماء المتغيرات.
  • [ ] تم إعداد APIDOG_TOKEN كـ secret.
  • [ ] تم تشغيل apidog run محليًا أو داخل CI.
  • [ ] تم اختبار ملفات CSV/JSON إن وجدت.
  • [ ] تم إعداد التقرير المناسب: HTML أو JSON.
  • [ ] تم تشغيل Apidog بجانب Hoppscotch عدة مرات.
  • [ ] تم حذف خطوة Hoppscotch بعد نجاح التحقق.

كلمة منصفة عن Hoppscotch

Hoppscotch CLI أداة جيدة إذا كنت تريد مشغّلًا خفيفًا ومجانيًا ومفتوح المصدر لتشغيل collections فقط. لا يوجد سبب لإزالتها إذا كانت تلبي احتياجك بالكامل.

سبب الترحيل إلى Apidog ليس أن أمر التشغيل وحده أفضل، بل أن نطاق العمل أوسع: عندما تحتاج إلى ربط التصميم، المحاكاة، التوثيق، والاختبارات بتعريف واحد، تصبح المنصة المتكاملة أكثر عملية من مشغّل مستقل.

للمقارنة المباشرة، راجع مقارنة Apidog CLI بـ Hoppscotch CLI. وإذا كنت تقارن الأدوات ككل، فراجع أيضًا Postman مقابل Hoppscotch وبدائل Hoppscotch.

Top comments (0)