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

تُعد Hoppscotch CLI طريقة نظيفة ومجانية لتشغيل مجموعات واجهة برمجة التطبيقات (API collections) في الطرفية أو في مسار التكامل المستمر (CI pipeline). يقرأ الأمر hopp test ملف مجموعة، وينفذ كل طلب، ويشغل نصوص ما قبل الطلب والاختبار الخاصة بك، ويخرج بقيمة غير صفرية عندما يفشل تأكيد. بالنسبة للكثير من الفرق، هذا يكفي.

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

زر

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

كن صريحًا مع نفسك أولاً. إذا كان مطلبك الوحيد هو "تشغيل مجموعة في CI مجانًا، واستضافتها ذاتيًا إذا أردت"، فإن Hoppscotch CLI هي أداة جيدة حقًا. إنها مفتوحة المصدر، والمشغل سريع، و @hoppscotch/cli يأتي كحزمة npm عادية. لا عيب في البقاء عليها.

قم بالترحيل عندما يبدأ أحد هذه الأمور في التسبب بالمشاكل:

أنت تصمم واجهات برمجة التطبيقات (APIs) في أداة واحدة، وتحاكي في أخرى، وتكتب الوثائق في ثالثة، والحفاظ على تزامنها هو عمل يدوي.
تريد أن تتشارك عمليات تشغيل الاختبار، والخوادم الوهمية، والوثائق المنشورة تعريف مشروع واحد.
أنت بحاجة إلى تقارير أكثر ثراءً (تقارير HTML لأصحاب المصلحة، JSON للأنظمة الآلية) بالإضافة إلى سجل تشغيل مستضاف على السحابة.
تريد التعامل مع نقاط النهاية (endpoints)، والمخططات (schemas)، والبيئات (environments)، والفروع (branches) كتعليمات برمجية يمكن لواجهة سطر الأوامر (CLI) إدارتها، وليس مجرد تنفيذها.

إذا كانت هذه القائمة تصف أسبوع عملك، فإن المنصة هي السبب للتحرك، وليس المشغل. إليك كيفية القيام بذلك بشكل نظيف.

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

كل شيء في Hoppscotch هو JSON، مما يجعل عملية التصدير سهلة.

من تطبيق Hoppscotch (الويب أو سطح المكتب)، افتح المجموعة التي تشغلها في CI. استخدم قائمة المجموعة واختر تصدير، مما يمنحك ملف .json. افعل الشيء نفسه للبيئة التي تمررها باستخدام -e: افتح لوحة البيئات وصدّرها إلى ملف JSON الخاص بها.

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

npm i -g @hoppscotch/cli
hopp test ./collections/checkout-api.json -e ./environments/staging.json

احتفظ بالملفين. checkout-api.json هي مجموعتك، و staging.json هي بيئتك. هذان الاثنان هما الحمولة الكاملة التي تنقلها.

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

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

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

قم بربط بيئة Hoppscotch الخاصة بك ببيئة Apidog بنفس أسماء المتغيرات. إذا كان staging.json قد حدد base_url و api_token، فأعد إنشاء هذه المفاتيح تحت بيئة Apidog المطابقة. الحفاظ على الأسماء متطابقة يعني أن نصوص الاختبار وعناوين URL للطلبات لا تحتاج إلى تعديلات.

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

الخطوة 3: ربط `hopp test` بـ `apidog run`

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

# Hoppscotch
hopp test ./collections/checkout-api.json -e ./environments/staging.json

# Apidog
apidog run --access-token $APIDOG_TOKEN -e "Staging"

يقوم كلا الأمرين بتنفيذ كل طلب بالترتيب، وتشغيل نصوص ما قبل الطلب، وتشغيل تأكيدات الاختبار الخاصة بك، وإرجاع رمز خروج غير صفري إذا فشل أي شيء. عقد رمز الخروج هذا هو الجزء الذي يعتمد عليه CI، وقد تم الحفاظ عليه، لذا فإن منطق النجاح/الفشل لخط أنابيبك لا يتغير.

تختلف المصادقة بطريقة مفيدة. يمرر Hoppscotch رمز وصول شخصي باستخدام --token للمجموعات السحابية أو المستضافة ذاتيًا. يصادق Apidog باستخدام تسجيل الدخول أو رمز وصول، والذي يسمح لواجهة سطر الأوامر (CLI) بالوصول إلى الموارد في مشروعك بدلاً من ملف واحد تم تصديره. إذا واجهت صعوبات في التعامل مع الرموز المميزة من قبل، فإن دليل المصادقة التفصيلي يوضح الخيارات.

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

تقوم كلتا الأداتين بالاختبار القائم على البيانات، لذا فإن التكرار عبر ملف CSV من المدخلات يظل ساريًا بعد الترحيل.

في Hoppscotch تمرر بيانات التكرار وعددًا:

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

في Apidog، يأخذ المشغل مجموعة بيانات باستخدام -d. يقبل CSV و JSON، لذا فإن نفس ملف orders.csv يعمل بعد الاستيراد:

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

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

الخطوة 5: تحويل أدوات إعداد التقارير الخاصة بك

إعداد التقارير هو المجال الذي تتفوق فيه المنصة، والتحويل مباشر.

يصدر Hoppscotch ملف JUnit XML بعلامة واحدة، والذي تقوم معظم أنظمة CI بتحليله للوحات الاختبار:

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

يمنحك Apidog خيارًا من أدوات إعداد التقارير: ملخص CLI قابل للقراءة، وتقرير HTML يمكنك تقديمه لأصحاب المصلحة، وتقرير JSON للأنظمة الآلية. يمكنك أيضًا دفع النتائج إلى السحابة للحصول على سجل تشغيل قابل للمشاركة.

# تقرير HTML قابل للقراءة البشري
apidog run --access-token $APIDOG_TOKEN \
  -e "Staging" \
  -r html \
  --upload-report

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

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

المهمة	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`

انتبه إلى علامة -d في هذا الجدول. في Hoppscotch، تمثل -d التأخير بالملي ثانية؛ وفي Apidog، تمثل -d مجموعة البيانات للتشغيلات المعتمدة على البيانات. نفس الحرف، وظيفة مختلفة. هذا هو الخطأ الشائع الذي يربك الناس أثناء التحول من Hoppscotch إلى Apidog.

الخطوة 6: ربطها بـ GitHub Actions

الخطوة الأخيرة، والهدف هو بناء ناجح بالكامل (build green). قم بإعداد مهمة Apidog جنبًا إلى جنب مع مهمة Hoppscotch القديمة أولاً، وتأكد من نجاحها، ثم احذف الخطوة القديمة. لا تقم بالتحويل بشكل أعمى أبدًا.

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

قم بتخزين رمز الوصول الخاص بك كسر سري للمستودع، ولا تضعه أبدًا في ملف YAML. نظرًا لأن واجهة سطر الأوامر (CLI) تُرجع رمز خروج غير صفري عند أي تأكيد فاشل، فإن المهمة تفشل تمامًا عندما تفشل اختباراتك، وهو السلوك الذي يثق به فريقك بالفعل من Hoppscotch. يغطي دليل GitHub Actions التخزين المؤقت والتشغيلات المتعددة (matrix runs)، ويتعامل دليل مسار CI/CD الأوسع مع GitLab و Jenkins والبقية.

بمجرد أن تصبح مهمة Apidog ناجحة (green) لعدة تشغيلات، قم بإزالة خطوة Hoppscotch وتثبيت npm الخاص بها. الترحيل تم، والبناء لم يتحول إلى اللون الأحمر أبدًا.

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

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