ما هو Hoppscotch CLI؟

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

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

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

يتم شحن واجهة سطر أوامر Hoppscotch كحزمة npm باسم @hoppscotch/cli. وظيفتها محددة ومفيدة: فهي تأخذ مجموعة Hoppscotch، وتشغل كل طلب فيها، وتنفذ نصوص الاختبار المرفقة بتلك الطلبات، ثم تخرج برمز نجاح/فشل يمكن لخط أنابيبك (pipeline) قراءته.

هذا يجعلها منفذاً للمجموعات، ضمن نفس الفئة التي ينتمي إليها Newman لـ Postman أو inso لـ Insomnia. إنها لا تصمم واجهات برمجة التطبيقات (APIs)، ولا تحاكي نقاط النهاية (endpoints)، ولا تنشئ وثائق. إنها تشغل الطلبات وتتحقق من التأكيدات. بالنسبة لأداة مجانية مفتوحة المصدر يمكنك استضافتها بنفسك، فإن هذا التركيز هو جوهر الموضوع.

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

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

قم بتثبيته عالميًا من npm:

npm i -g @hoppscotch/cli

أحد المتطلبات التي يجب الانتباه إليها: تتطلب واجهة سطر الأوامر الحالية Node.js v22 أو أحدث. إذا كنت لا تزال تستخدم Node 20، فيمكنك البقاء على CLI v0.26.0، لكن الإصدارات الأحدث تفترض v22 أو أحدث. تحقق من إصدارك قبل ربطه بعامل بناء (build agent):

node --version
hopp --version

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

أمر hopp test

يتم كل شيء عبر hopp test. يشير الشكل الأساسي إلى ملف مجموعة:

hopp test ./my-collection.json

يمكنك تمرير ملف بيئة وتأخير بين الطلبات:

hopp test ./my-collection.json -e ./staging.env.json -d 500

هنا، -e (أو --env) يوفر البيئة، و -d (أو --delay) ينتظر العدد المحدد من المللي ثانية بين الطلبات، مما يساعد عند التعامل مع واجهة برمجة تطبيقات (API) ذات معدل محدود.

إذا كانت مجموعاتك موجودة في مثيل Hoppscotch (سحابي أو مستضاف ذاتيًا) بدلاً من ملف محلي، يمكنك الإشارة إليها بواسطة المعرف (ID) والمصادقة باستخدام رمز وصول شخصي:

hopp test <collection-id> --token <access_token> --server https://hoppscotch.your-company.com

يحمل --token رمز الوصول الشخصي الخاص بك، ويشير --server إلى عنوان URL الخاص بك المستضاف ذاتيًا. احذف --server إذا كنت تستخدم سحابة Hoppscotch المستضافة.

التشغيل المعتمد على البيانات وإعداد التقارير

يحول علامان hopp test من تشغيل فردي إلى شيء متوافق مع CI.

للاختبار المعتمد على البيانات، قم بتغذية ملف CSV وحدد عدد التكرارات المراد تشغيلها:

hopp test ./my-collection.json --iteration-data ./users.csv --iteration-count 3

يأخذ --iteration-data ملف CSV تصبح أعمدته متغيرات في كل تشغيل، ويتحكم --iteration-count في عدد مرات تكرار المجموعة. هذه هي نفس فكرة -d في Newman، وهي تغطي الحالة الشائعة "تشغيل تدفق تسجيل الدخول هذا على 50 حسابًا".

لإعداد التقارير، تكتب واجهة سطر الأوامر (CLI) ملف JUnit XML، والذي يمكن لمعظم أنظمة CI استيعابه لعرض نتائج الاختبار بشكل أصلي:

hopp test ./my-collection.json --reporter-junit ./report.xml

JUnit هو تنسيق التقرير المهيكل الوحيد الذي تنتجه واجهة سطر الأوامر (CLI). إذا كنت بحاجة إلى عناصر HTML أو تقارير مستضافة قابلة للربط، فهذه ثغرة تستحق المعرفة قبل الالتزام. تُصدر أدوات مثل Apidog CLI تقارير CLI و HTML و JSON للمقارنة.

ما الذي يتم تنفيذه فعليًا أثناء التشغيل

عند تشغيل hopp test، تقوم واجهة سطر الأوامر (CLI) بالمرور على المجموعة بالترتيب، ولكل طلب:

• تقوم بتشغيل نص ما قبل الطلب،
• ترسل الطلب،
• تشغل نص الاختبار وتقيّم كل تأكيد.

تستخدم نصوص الاختبار واجهة برمجة تطبيقات Hoppscotch للبرمجة النصية: تحدد pw.test() كتلة اختبار وتجري pw.expect() تأكيدات بداخلها. مثال صغير مرفق بطلب يبدو كالتالي:

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

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

مثال على GitHub Actions

ربط hopp test بـ CI قصير ومباشر. يقوم سير العمل هذا بتثبيت واجهة سطر الأوامر على مشغل Node 22 ويشغل مجموعة في كل عملية دفع:

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

خطوة setup-node التي تثبت الإصدار 22 هي الجزء الذي ينساه الناس. بدونها، قد يكون إصدار Node الافتراضي للمشغل قديمًا جدًا لواجهة سطر الأوامر الحالية.

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

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

• إنها منفذ مجموعات، وليست منصة. لا يوجد تصميم، أو محاكاة، أو توثيق. أنت تجلب هذه الأشياء من مكان آخر.
• تقوم بتصدير أو استضافة المجموعات بنفسك. تشغل واجهة سطر الأوامر ملف مجموعة أو تسحبه من مثيل تشير إليه.
• JUnit هو التقرير المنظم الوحيد. لا يوجد تقرير HTML مدمج أو مستضاف.
• Node v22+. متطلب صارم في الإصدارات الحالية.

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

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

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

ما الفرق بين hopp test و Newman؟ كلاهما منفذان للمجموعات مع تكرارات تعتمد على البيانات. يشغل Newman مجموعات Postman؛ بينما يشغل hopp test مجموعات Hoppscotch. تتشابه المفاهيم إلى حد كبير، بما في ذلك بيانات تكرار CSV والنجاح/الفشل القائم على رمز الخروج.

هل يمكن لـ Hoppscotch CLI تشغيل المجموعات من خادم مستضاف ذاتيًا؟ نعم. استخدم hopp test <collection-id> --token <access_token> --server <your-url> لسحب وتشغيل مجموعة من مثيلك الخاص.

هل تنتج تقارير HTML؟ ليس مباشرة. إنها تكتب JUnit XML عبر --reporter-junit. للحصول على تقارير CLI و HTML و JSON معًا، قارنها بـ تقارير اختبار Apidog CLI.

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