DEV Community

Cover image for ما هو Hoppscotch CLI؟
Yusuf Khalidd
Yusuf Khalidd

Posted on • Originally published at apidog.com

ما هو Hoppscotch CLI؟

Hoppscotch هو نظام بيئي مفتوح المصدر لواجهات برمجة التطبيقات: تطبيق ويب، تطبيق سطح مكتب، واجهة سطر أوامر (CLI)، وخلفية قابلة للاستضافة الذاتية. غالبًا ما يُستخدم كبديل مفتوح المصدر لـ Postman وInsomnia. الجزء المهم لفرق CI/CD هو Hoppscotch CLI، لأنه يشغّل المجموعات من الطرفية ويُرجع رمز نجاح أو فشل يمكن لخط الأنابيب الاعتماد عليه.

جرّب Apidog اليوم

في هذا الدليل ستتعلم ما هي واجهة سطر أوامر Hoppscotch، كيف تثبّتها، كيف يعمل أمر hopp test، وما الأعلام المفيدة في CI مع مثال عملي على GitHub Actions. إذا كنت تقارنها بمنفذين آخرين، يمكنك الرجوع إلى أفضل بدائل Hoppscotch CLI وApidog CLI vs Hoppscotch CLI.

ما هي واجهة سطر أوامر Hoppscotch

تُوزَّع واجهة سطر أوامر Hoppscotch كحزمة npm باسم @hoppscotch/cli. وظيفتها الأساسية هي:

  1. قراءة مجموعة Hoppscotch.
  2. تشغيل الطلبات الموجودة داخلها.
  3. تنفيذ نصوص ما قبل الطلب ونصوص الاختبار.
  4. تقييم التأكيدات.
  5. الخروج برمز نجاح أو فشل مناسب لـ CI.

Hoppscotch CLI

فكّر فيها كمنفذ مجموعات، مثل Newman لمجموعات Postman أو inso لمجموعات Insomnia. هي لا تصمم APIs، ولا تنشئ mock servers، ولا تولّد وثائق. استخدامها العملي هو تشغيل اختبارات API آليًا.

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

تثبيت Hoppscotch CLI

ثبّت الحزمة عالميًا من npm:

npm i -g @hoppscotch/cli
Enter fullscreen mode Exit fullscreen mode

تحقق من الإصدارات بعد التثبيت:

node --version
hopp --version
Enter fullscreen mode Exit fullscreen mode

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

في CI، اجعل إصدار Node واضحًا بدل الاعتماد على الإعداد الافتراضي للمشغل.

تشغيل مجموعة محلية باستخدام hopp test

الأمر الأساسي هو:

hopp test ./my-collection.json
Enter fullscreen mode Exit fullscreen mode

إذا كانت لديك بيئة منفصلة، مرّرها باستخدام -e أو --env:

hopp test ./my-collection.json -e ./staging.env.json
Enter fullscreen mode Exit fullscreen mode

لإضافة تأخير بين الطلبات، استخدم -d أو --delay بالمللي ثانية:

hopp test ./my-collection.json -e ./staging.env.json -d 500
Enter fullscreen mode Exit fullscreen mode

هذا مفيد عندما تختبر API لديها rate limits أو عندما تحتاج إلى تقليل الضغط على بيئة staging.

تشغيل مجموعة من خادم Hoppscotch

إذا كانت المجموعة موجودة في Hoppscotch Cloud أو في مثيل مستضاف ذاتيًا، يمكنك تشغيلها باستخدام معرف المجموعة ورمز وصول شخصي:

hopp test <collection-id> --token <access_token>
Enter fullscreen mode Exit fullscreen mode

وللمثيل المستضاف ذاتيًا:

hopp test <collection-id> \
  --token <access_token> \
  --server https://hoppscotch.your-company.com
Enter fullscreen mode Exit fullscreen mode

استخدم --server فقط عندما تريد الاتصال بمثيل Hoppscotch خاص بك. إذا كنت تستخدم السحابة المستضافة، احذفه.

التشغيل المعتمد على البيانات

لاختبار نفس التدفق على بيانات مختلفة، استخدم ملف CSV مع --iteration-data:

hopp test ./my-collection.json \
  --iteration-data ./users.csv \
  --iteration-count 3
Enter fullscreen mode Exit fullscreen mode

مثال بسيط لملف users.csv:

email,password
user1@example.com,pass123
user2@example.com,pass456
user3@example.com,pass789
Enter fullscreen mode Exit fullscreen mode

تتحول أعمدة CSV إلى متغيرات يمكن استخدامها أثناء التشغيل. هذا النمط مناسب لحالات مثل:

  • اختبار تسجيل الدخول بعدة حسابات.
  • تشغيل نفس الطلب على عدة IDs.
  • التحقق من سلوك API مع مدخلات مختلفة.

يتحكم --iteration-count في عدد مرات تكرار تشغيل المجموعة.

إخراج تقارير JUnit للـ CI

لإنشاء تقرير JUnit XML:

hopp test ./my-collection.json --reporter-junit ./report.xml
Enter fullscreen mode Exit fullscreen mode

مع بيئة وبيانات تكرار:

hopp test ./my-collection.json \
  -e ./ci.env.json \
  --iteration-data ./users.csv \
  --iteration-count 3 \
  --reporter-junit ./report.xml
Enter fullscreen mode Exit fullscreen mode

تنسيق JUnit مناسب لأن معظم منصات CI يمكنها قراءته وعرض نتائج الاختبارات داخل الواجهة.

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

ما الذي يحدث عند تشغيل hopp test

عند تنفيذ الأمر، تمر CLI على الطلبات داخل المجموعة بالترتيب. لكل طلب، تنفّذ الخطوات التالية:

  1. تشغيل نص ما قبل الطلب.
  2. إرسال الطلب.
  3. تشغيل نص الاختبار.
  4. تقييم التأكيدات.
  5. تحديد نجاح أو فشل الطلب.

تستخدم نصوص الاختبار واجهة Hoppscotch البرمجية للسكريبتات. مثال بسيط:

pw.test("Status is 200", () => {
  pw.expect(pw.response.status).toBe(200);
});
Enter fullscreen mode Exit fullscreen mode

إذا فشل أي تأكيد، يخرج الأمر برمز غير صفري. إذا نجحت كل الاختبارات، يخرج برمز 0.

هذا هو الجزء المهم في CI:

  • exit code 0 يعني نجاح البناء.
  • exit code غير صفري يعني فشل البناء.

مثال GitHub Actions

هذا workflow يثبّت Node 22، يثبّت Hoppscotch CLI، ثم يشغّل مجموعة API مع تقرير JUnit:

name: API tests

on: [push]

jobs:
  hopp:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - run: npm i -g @hoppscotch/cli

      - run: |
          hopp test ./collection.json \
            -e ./ci.env.json \
            --reporter-junit ./report.xml
Enter fullscreen mode Exit fullscreen mode

إذا أردت رفع تقرير JUnit كـ artifact:

      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: hopp-junit-report
          path: ./report.xml
Enter fullscreen mode Exit fullscreen mode

استخدم if: always() حتى يتم رفع التقرير حتى عند فشل الاختبارات.

مثال كامل مع بيانات CSV

هيكل ملفات بسيط:

.
├── collection.json
├── ci.env.json
└── users.csv
Enter fullscreen mode Exit fullscreen mode

أمر التشغيل:

hopp test ./collection.json \
  -e ./ci.env.json \
  --iteration-data ./users.csv \
  --iteration-count 3 \
  --delay 500 \
  --reporter-junit ./report.xml
Enter fullscreen mode Exit fullscreen mode

هذا مناسب كخطوة smoke test أو regression test بسيطة داخل pipeline.

قيود يجب معرفتها

واجهة سطر أوامر Hoppscotch مفيدة عندما يكون المطلوب هو تشغيل مجموعات API فقط، لكن نطاقها محدود:

  • هي منفذ مجموعات وليست منصة كاملة. لا توفر تصميم API أو mock أو توثيق.
  • تحتاج إلى ملف مجموعة أو مثيل Hoppscotch. إما تصدّر المجموعة محليًا أو تسحبها من خادم.
  • تقارير JUnit فقط بشكل مدمج. لا يوجد HTML report مدمج.
  • تتطلب Node v22+ في الإصدارات الحالية.
  • إدارة البنية حولها مسؤوليتك. خصوصًا عند الاستضافة الذاتية.

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

يغطي Apidog دورة حياة API بالكامل، ويوضح الدليل الكامل لـ Apidog CLI كيفية تشغيل الاختبارات من الطرفية. يمكنك أيضًا تنزيل Apidog واستيراد مجموعة Hoppscotch للمقارنة عمليًا، أو قراءة دليل الترحيل.

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

هل Hoppscotch CLI مجاني؟

نعم. هو مفتوح المصدر ضمن مشروع Hoppscotch، ويمكنك استضافة النظام البيئي بالكامل بنفسك. راجع وثائق CLI الرسمية ومستودع GitHub.

ما الفرق بين hopp test وNewman؟

كلاهما منفذ مجموعات مناسب لـ CI. Newman يشغّل مجموعات Postman، بينما hopp test يشغّل مجموعات Hoppscotch. المفاهيم متشابهة: بيئات، بيانات تكرار، تأكيدات، ورمز خروج يحدد نجاح أو فشل البناء.

هل يمكن تشغيل مجموعات من خادم Hoppscotch مستضاف ذاتيًا؟

نعم. استخدم:

hopp test <collection-id> --token <access_token> --server <your-url>
Enter fullscreen mode Exit fullscreen mode

هل تنتج Hoppscotch CLI تقارير HTML؟

ليس مباشرة. يمكنها إخراج JUnit XML عبر:

hopp test ./my-collection.json --reporter-junit ./report.xml
Enter fullscreen mode Exit fullscreen mode

إذا كنت تحتاج إلى تقارير CLI وHTML وJSON، قارنها مع تقارير اختبار Apidog CLI.

الخلاصة

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

Top comments (0)