Hoppscotch

نظام بيئي مفتوح المصدر لتطوير واجهات برمجة التطبيقات وبديل خفيف لـ Postman لاختبار واجهات REST و GraphQL و WebSocket والواجهات في الوقت الفعلي.

التثبيت

الويب وسطح المكتب

أمر	وصف
الانتقال إلى `hoppscotch.io`	فتح تطبيق Hoppscotch على الويب (بدون تثبيت)
التحميل من `hoppscotch.io/download`	تثبيت تطبيق سطح المكتب (macOS, Windows, Linux)
تسجيل الدخول بـ GitHub أو Google أو البريد الإلكتروني	إنشاء حساب لمزامنة الفريق
خيار تثبيت PWA في المتصفح	التثبيت كتطبيق ويب تقدمي

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

أمر	وصف
`npm install -g @hoppscotch/cli`	تثبيت CLI عالمياً مع npm
`npx @hoppscotch/cli`	تشغيل CLI بدون تثبيت
`hopp --version`	عرض إصدار CLI
`hopp --help`	عرض مساعدة CLI

التثبيت المستضاف ذاتياً

أمر	وصف
`docker pull hoppscotch/hoppscotch`	سحب صورة Docker
`docker compose up -d`	بدء النسخة المستضافة ذاتياً

Docker Compose المستضاف ذاتياً

# docker-compose.yml للاستضافة الذاتية لـ Hoppscotch
version: "3"
services:
  hoppscotch:
    image: hoppscotch/hoppscotch:latest
    ports:
      - "3000:3000"   # Web UI
      - "3100:3100"   # Admin dashboard
      - "3170:3170"   # Backend API
    environment:
      DATABASE_URL: postgresql://user:pass@db:5432/hoppscotch
      JWT_SECRET: your-jwt-secret-here
      TOKEN_SALT_COMPLEXITY: 10
      MAGIC_LINK_TOKEN_VALIDITY: 3
      REFRESH_TOKEN_VALIDITY: 604800000
      ACCESS_TOKEN_VALIDITY: 86400000
      VITE_ALLOWED_AUTH_PROVIDERS: GITHUB,GOOGLE,EMAIL
    depends_on:
      - db

  db:
    image: postgres:15
    volumes:
      - postgres_data:/var/lib/postgresql/data
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass
      POSTGRES_DB: hoppscotch

volumes:
  postgres_data:

طلبات HTTP

إرسال الطلبات

أمر	وصف
اختيار الطريقة (GET, POST, PUT, DELETE, PATCH)	اختيار طريقة HTTP من القائمة المنسدلة
إدخال URL في شريط العنوان	تعيين نقطة نهاية الطلب
النقر على “Send”	تنفيذ الطلب
`Ctrl + Enter`	إرسال الطلب (اختصار لوحة المفاتيح)
`Ctrl + G`	إرسال وتحميل الاستجابة
`Ctrl + K`	فتح لوحة الأوامر

جسم الطلب

أمر	وصف
النقر على تبويب “Body” → اختيار النوع	تعيين تنسيق جسم الطلب
اختيار “application/json”	جسم JSON (الأكثر شيوعاً)
اختيار “multipart/form-data”	رفع الملفات
اختيار “application/x-www-form-urlencoded”	بيانات النموذج
اختيار “text/plain”	جسم نص عادي
اختيار “application/xml”	جسم XML
اختيار “Binary”	بيانات ثنائية خام

الترويسات والمعاملات

أمر	وصف
النقر على تبويب “Headers” → إضافة ترويسة	إضافة ترويسات طلب مخصصة
النقر على تبويب “Parameters”	إضافة معاملات استعلام URL
وضع التحرير الجماعي للترويسات	لصق عدة ترويسات دفعة واحدة
تبديل الترويسة نشطة/غير نشطة	التعطيل بدون الحذف
استخدام `<<variable>>` في القيم	الإشارة إلى متغيرات البيئة

فحص الاستجابة

أمر	وصف
عرض جسم الاستجابة	JSON, HTML, XML, ثنائي, صورة
النقر على تبويب “Headers” في الاستجابة	فحص ترويسات الاستجابة
عرض رمز الحالة والوقت	حالة HTTP, زمن الاستجابة, الحجم
النقر على “Copy” في الاستجابة	نسخ الاستجابة إلى الحافظة
النقر على “Download”	تحميل الاستجابة كملف
الاستجابة JSON مُنسقة تلقائياً	عرض شجري قابل للطي
النقر على “Timeline”	عرض الجدول الزمني للطلب/الاستجابة

مثال على طلب

Method:  POST
URL:     https://api.example.com/users
Headers:
  Content-Type: application/json
  Authorization: Bearer <<auth_token>>

Body (JSON):
{
  "name": "Alice Smith",
  "email": "alice@example.com",
  "role": "admin"
}

Response: 201 Created (145ms, 234 B)
{
  "id": 42,
  "name": "Alice Smith",
  "email": "alice@example.com",
  "role": "admin",
  "created_at": "2024-01-15T10:30:00Z"
}

المجموعات

إدارة المجموعات

أمر	وصف
النقر على ”+” في لوحة المجموعات	إنشاء مجموعة جديدة
النقر بالزر الأيمن على المجموعة → “New Request”	إضافة طلب إلى المجموعة
النقر بالزر الأيمن على المجموعة → “New Folder”	التنظيم بمجلدات فرعية
سحب الطلبات بين المجلدات	إعادة ترتيب عناصر المجموعة
النقر بالزر الأيمن → “Duplicate”	استنساخ مجموعة
النقر بالزر الأيمن → “Properties”	تحرير إعدادات المجموعة
النقر بالزر الأيمن → “Delete”	حذف المجموعة
`Ctrl + Shift + P`	البحث داخل المجموعات

الاستيراد والتصدير

أمر	وصف
النقر على “Import” → اختيار ملف	استيراد مجموعة
النقر بالزر الأيمن → “Export”	تصدير المجموعة كـ JSON
الاستيراد من Postman Collection v2	التوافق مع Postman
الاستيراد من مواصفات OpenAPI/Swagger	إنشاء الطلبات تلقائياً
الاستيراد من Insomnia	التوافق مع Insomnia
الاستيراد من cURL	لصق أمر cURL
الاستيراد من HAR	استيراد أرشيف HTTP

أمثلة الاستيراد

Supported import formats:
  - Hoppscotch Collection (native JSON)
  - Postman Collection v2
  - OpenAPI 3.0 / Swagger 2.0
  - Insomnia v4
  - cURL commands
  - HAR (HTTP Archive)

Import from cURL:
  Paste a cURL command directly into the URL bar
  Hoppscotch auto-parses method, headers, body, and URL

متغيرات البيئة

إدارة البيئات

أمر	وصف
النقر على “Environments” في الشريط الجانبي	فتح مدير البيئات
النقر على ”+” لإنشاء بيئة	إنشاء بيئة جديدة
إضافة أزواج `key: value`	تعريف المتغيرات
استخدام `<<variable_name>>` في الطلبات	الإشارة إلى المتغير في أي حقل
اختيار البيئة من القائمة المنسدلة	تنشيط بيئة
النقر على تبويب “Global”	تعيين متغيرات عامة (نشطة دائماً)
النقر بالزر الأيمن → “Export”	تصدير البيئة كـ JSON
النقر بالزر الأيمن → “Duplicate”	استنساخ البيئة

أنواع المتغيرات

النوع	وصف
متغير عادي	مرئي في الواجهة, يُصدَّر في المجموعات
متغير سري	مخفي في الواجهة, لا يُصدَّر
متغير عام	متاح في جميع البيئات
متغير بيئة	متاح فقط عندما تكون البيئة نشطة

مثال على بيئة

Environment: "Production"
┌───────────────┬──────────────────────────────┬──────────┐
│ Key           │ Value                        │ Type     │
├───────────────┼──────────────────────────────┼──────────┤
│ base_url      │ https://api.example.com      │ Regular  │
│ api_version   │ v2                           │ Regular  │
│ auth_token    │ eyJhbGciOiJIUzI1NiIsIn...    │ Secret   │
│ timeout       │ 30000                        │ Regular  │
└───────────────┴──────────────────────────────┴──────────┘

Usage in requests:
  URL:    <<base_url>>/<<api_version>>/users
  Header: Authorization: Bearer <<auth_token>>

المصادقة

أنواع المصادقة

أمر	وصف
اختيار “Bearer Token”	إضافة مصادقة Bearer token
اختيار “Basic Auth”	مصادقة اسم المستخدم/كلمة المرور
اختيار “OAuth 2.0”	تكوين تدفق OAuth 2.0
اختيار “API Key”	إضافة مفتاح API إلى الترويسة أو معامل الاستعلام
اختيار “AWS Signature”	مصادقة AWS Signature V4
اختيار “Inherit from parent”	وراثة المصادقة من المجموعة
اختيار “None”	إزالة المصادقة
حقول الرمز تدعم `<<variables>>`	استخدام متغيرات البيئة في رموز المصادقة

تكوين OAuth 2.0

OAuth 2.0 Configuration:
  Grant Type:       Authorization Code
  Auth URL:         https://auth.example.com/authorize
  Token URL:        https://auth.example.com/token
  Client ID:        <<client_id>>
  Client Secret:    <<client_secret>>
  Scope:            read write
  Redirect URI:     Auto-configured

Supported grant types:
  - Authorization Code (+ PKCE)
  - Client Credentials
  - Implicit
  - Password Credentials

الاختبار في الوقت الفعلي

WebSocket

أمر	وصف
النقر على “Realtime” → “WebSocket”	فتح عميل WebSocket
إدخال عنوان `wss://`	تعيين نقطة نهاية WebSocket
النقر على “Connect”	إنشاء الاتصال
كتابة رسالة → النقر على “Send”	إرسال رسالة إلى الخادم
عرض الرسائل في لوحة السجل	مراقبة الوارد/الصادر
النقر على “Disconnect”	إغلاق الاتصال
إضافة بروتوكولات/ترويسات	تكوين معاملات الاتصال

أحداث الخادم المُرسلة (SSE)

أمر	وصف
النقر على “Realtime” → “SSE”	اختبار Server-Sent Events
إدخال عنوان URL لنقطة نهاية SSE	تعيين عنوان تدفق الأحداث
النقر على “Connect”	بدء استقبال الأحداث
تسجيل الأحداث في الوقت الفعلي	مراقبة تدفق الأحداث
النقر على “Disconnect”	إيقاف الاستقبال

MQTT

أمر	وصف
النقر على “Realtime” → “MQTT”	اختبار اتصالات MQTT
إدخال عنوان `mqtt://` أو `wss://`	تعيين عنوان وسيط MQTT
تعيين Client ID واسم المستخدم وكلمة المرور	تكوين بيانات الاعتماد
الاشتراك في المواضيع	الاستماع للرسائل
النشر في المواضيع	إرسال الرسائل

Socket.IO

أمر	وصف
النقر على “Realtime” → “Socket.IO”	اختبار اتصالات Socket.IO
إدخال عنوان الخادم	تعيين نقطة نهاية Socket.IO
الاستماع للأحداث	الاشتراك في أحداث مسماة
إرسال أحداث مع بيانات	إرسال أحداث مسماة
عرض حالة الاتصال	مراقبة الاتصال/قطع الاتصال

GraphQL

اختبار GraphQL

أمر	وصف
النقر على تبويب “GraphQL”	التبديل إلى وضع GraphQL
إدخال عنوان نقطة نهاية GraphQL	تعيين عنوان خادم GraphQL
كتابة الاستعلام في لوحة المحرر	تأليف استعلام GraphQL
النقر على “Schema” لجلب المخطط	تحميل مخطط الخادم للإكمال التلقائي
إضافة متغيرات في لوحة Variables	تعيين متغيرات الاستعلام كـ JSON
إضافة ترويسات للمصادقة	تعيين ترويسات المصادقة
النقر على “Run” أو `Ctrl + Enter`	تنفيذ الاستعلام
استخدام الإكمال التلقائي من المخطط	الحصول على اقتراحات الحقول

مثال GraphQL

Endpoint: https://api.example.com/graphql

Query:
  query GetUsers($limit: Int!) {
    users(limit: $limit) {
      id
      name
      email
      posts {
        title
        createdAt
      }
    }
  }

Variables:
  {
    "limit": 10
  }

Headers:
  Authorization: Bearer <<auth_token>>

استخدام واجهة سطر الأوامر

تشغيل المجموعات

أمر	وصف
`hopp test collection.json`	تشغيل اختبارات المجموعة
`hopp test collection.json -e environment.json`	التشغيل مع بيئة
`hopp test collection.json --delay 500`	التأخير بين الطلبات (مللي ثانية)
`hopp test collection.json --reporter junit`	إخراج تقرير اختبار JUnit
`hopp test collection.json --reporter json`	إخراج تقرير اختبار JSON
`hopp test collection.json --bail`	التوقف عند أول فشل
`hopp test collection.json --env-var KEY=VALUE`	تجاوز متغير البيئة

أمثلة CLI

# Run collection with environment
hopp test api-tests.json -e production.json

# Run with delay and stop on failure
hopp test api-tests.json --delay 1000 --bail

# Generate JUnit report for CI/CD
hopp test api-tests.json --reporter junit > results.xml

# Override specific variables
hopp test api-tests.json \
  --env-var "base_url=https://staging.example.com" \
  --env-var "auth_token=test-token-123"

# CI/CD pipeline example
hopp test api-tests.json -e staging.json --bail --reporter junit

نصوص ما قبل الطلب وما بعد الطلب

البرمجة النصية

أمر	وصف
النقر على تبويب “Pre-request”	إضافة نص يُنفذ قبل الطلب
النقر على تبويب “Tests”	إضافة نص يُنفذ بعد الاستجابة
`pw.env.set("key", "value")`	تعيين متغير بيئة
`pw.env.get("key")`	الحصول على متغير بيئة
`pw.expect(response.status).toBe(200)`	التحقق من رمز الحالة
`pw.expect(response.body).toHaveProperty("id")`	التحقق من خاصية الجسم

أمثلة نصوص الاختبار

// Pre-request: Generate timestamp
pw.env.set("timestamp", Date.now().toString());

// Pre-request: Generate random ID
pw.env.set("random_id", Math.random().toString(36).slice(2));

// Test: Check status code
pw.test("Status is 200", () => {
  pw.expect(pw.response.status).toBe(200);
});

// Test: Check response body
pw.test("Response has user data", () => {
  const body = pw.response.body;
  pw.expect(body).toHaveProperty("id");
  pw.expect(body).toHaveProperty("name");
  pw.expect(body.name).toBe("Alice");
});

// Test: Check response time
pw.test("Response is fast", () => {
  pw.expect(pw.response.status).toBeLessThan(500);
});

// Test: Save token for next request
pw.test("Extract auth token", () => {
  const token = pw.response.body.access_token;
  pw.env.set("auth_token", token);
});

اختصارات لوحة المفاتيح

عامة

اختصار	وصف
`Ctrl + Enter`	إرسال الطلب
`Ctrl + K`	لوحة الأوامر
`Ctrl + S`	حفظ الطلب الحالي
`Ctrl + Shift + P`	البحث في المجموعات
`Ctrl + /`	تبديل الشريط الجانبي
`Alt + ↑`	الطلب السابق في السجل
`Alt + ↓`	الطلب التالي في السجل
`F11`	تبديل ملء الشاشة

الفرق والتعاون

أمر	وصف
إنشاء فريق من الشريط الجانبي	إعداد مساحة عمل الفريق
دعوة الأعضاء بالبريد الإلكتروني	إضافة المتعاونين
المجموعات المشتركة	مكتبات طلبات على مستوى الفريق
البيئات المشتركة	مجموعات متغيرات على مستوى الفريق
التعاون في الوقت الفعلي	رؤية تعديلات الفريق مباشرة
التحكم في الوصول القائم على الأدوار	أدوار المالك والمحرر والمشاهد

أفضل الممارسات

تنظيم المجموعات حسب مجال API — قم بتجميع نقاط النهاية المرتبطة في مجموعات واستخدم المجلدات لأنواع الموارد (users, orders, products) للحفاظ على سهولة البحث.
استخدام البيئات للتجهيز مقابل الإنتاج — أنشئ بيئات منفصلة للتطوير والتجهيز والإنتاج بنفس أسماء المتغيرات ولكن بقيم مختلفة. التبديل بنقرة واحدة.
تخزين الأسرار كمتغيرات سرية — قم بتعليم مفاتيح API والرموز كنوع “secret” بحيث تكون مخفية في الواجهة ومستبعدة من التصدير.
استخدام نصوص ما قبل الطلب للمصادقة — قم بإنشاء الطوابع الزمنية وحساب التوقيعات أو تحديث الرموز تلقائياً قبل كل طلب بدلاً من نسخها يدوياً.
كتابة اختبارات لنقاط النهاية الحرجة — أضف نصوص اختبار للتحقق من رموز الحالة وبنية الاستجابة والقيم الرئيسية. شغّلها عبر CLI في خطوط أنابيب CI/CD.
الاستيراد من مواصفات OpenAPI — عند العمل مع واجهات موثقة, استورد مواصفات OpenAPI/Swagger لإنشاء جميع نقاط النهاية تلقائياً مع المعاملات الصحيحة.
استخدام المصادقة على مستوى المجموعة — قم بتعيين المصادقة على مستوى المجموعة واستخدم “Inherit from parent” في الطلبات الفردية لتجنب تكرار تكوين المصادقة.
تصدير المجموعات إلى التحكم في الإصدار — صدّر المجموعات كـ JSON وأضفها إلى المستودع للتحكم في الإصدار والمشاركة مع الفريق.
استخدام CLI في CI/CD — أضف hopp test إلى خط الأنابيب لتشغيل اختبارات API في كل نشر, مما يضمن عمل نقاط النهاية قبل الإطلاق.
الاستضافة الذاتية للواجهات الحساسة — إذا كنت تختبر واجهات داخلية أو حساسة, انشر نسخة Docker المستضافة ذاتياً للحفاظ على جميع البيانات داخل بنيتك التحتية.