مقارنة Apidog CLI بـ Newman: تشغيل اختبارات API في CI (2026)

تنجح اختبارات واجهة برمجة التطبيقات (API) الخاصة بك على جهاز الكمبيوتر المحمول الخاص بك. السؤال الأصعب هو ما إذا كانت تعمل مع كل طلب سحب (pull request)، وكل دمج (merge)، وكل بناء ليلي (nightly build) دون تدخل بشري. هذه المهمة تقع على عاتق أداة تشغيل سطر الأوامر (command-line runner). تأخذ هذه الأداة الاختبارات التي كتبتها بالفعل، وتنفذها بدون واجهة رسومية (headless) داخل مسار عملك (pipeline)، وتخرج برمز حالة (status code) يمكن لنظام التكامل المستمر (CI) الخاص بك قراءته، وتكتب تقريرًا يمكن للوحة التحكم الخاصة بك تحليله. لا واجهة رسومية، لا خطوة يدوية، ولا عذر لتجاوز عملية التشغيل.

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

باختصار (TL;DR)

• Newman (newman، يتم تثبيتها عبر npm install -g newman) تشغل ملف JSON لمجموعة Postman المصدرة. إنها مفتوحة المصدر، ومجانية، وتقرأ مجموعة بالإضافة إلى ملف بيئة من القرص أو عنوان URL. وهي تدعم البيئات، وملفات البيانات، وعدد التكرارات، وتقارير JUnit/JSON/HTML، وتخرج برمز غير صفري عندما يفشل الاختبار.
• Apidog CLI (apidog-cli، الثنائي apidog) تشغل سيناريوهات الاختبار التي تصممها في تطبيق Apidog، والتي يتم جلبها بواسطة المعرف (ID) باستخدام رمز الوصول (access token). لا تقوم بتصدير أي شيء أو صيانة ملف JSON يدويًا؛ السيناريو المرئي هو الاختبار، وتنفذه أداة CLI تمامًا كما يفعل التطبيق.
• كلاهما يتصل بـ GitHub Actions، GitLab CI، Jenkins، وأي شيء يعمل مع Node.js. كلاهما يفشل البناء عند فشل الاختبار. JUnit XML هو ما يتصل بلوحات تحكم CI على كلا الجانبين.
• اختر Newman عندما تكون اختباراتك موجودة بالفعل كمجموعات Postman وتريد أداة تشغيل مجانية وصديقة للمستودعات (repo-friendly) بدون حساب جديد.
• اختر Apidog CLI عندما تريد إنشاء مرئي (visual authoring)، وتسلسل الطلبات (request chaining)، وإدارة البيئة (environment management)، وتشغيلات تعتمد على البيانات (data-driven runs) تظل متزامنة مع نفس السيناريو الذي يقوم فريقك بتصحيحه يوميًا.

المشكلة الحقيقية: اختبارات موجودة ولكن لا تعمل أبدًا

الاختبار الذي تديره يدويًا هو اختبار يتلف. قام شخص ما ببنائه، واجتاز الاختبار مرة واحدة، ثم ظل دون تغيير بينما تغيرت واجهة برمجة التطبيقات (API) تحته. المزيد من الاختبارات لا تحل ذلك. الاختبارات التي تعمل تلقائيًا مع كل تغيير تفعل ذلك، لأنها تنتج إشارة نجاح أو فشل يمكن لمسار عملك (pipeline) أن يتصرف بناءً عليها.

أداة تشغيل سطر الأوامر (CLI runner) تسد هذه الفجوة. لكي تكون مفيدة في التكامل المستمر (CI)، يجب أن تقوم بثلاثة أشياء: العمل بدون واجهة رسومية، والخروج برمز غير صفري عندما يفشل شيء ما بحيث يصبح البناء أحمر، وكتابة تقرير يمكن قراءته آليًا حتى يتمكن المراجعون من رؤية ما تعطل. كل من Newman و Apidog CLI يتجاوزان هذا العائق بنجاح. يكمن الاختلاف بينهما في كيفية كتابة الاختبار ومكان وجوده، قبل أمر التشغيل. إذا كنت تقوم بإعداد CI من البداية، فإن الأنماط الأوسع في كيفية أتمتة اختبارات API في CI/CD تتوافق جيدًا مع هذه المقارنة. هنا، نركز على أداتي التشغيل.

ماذا يفعل Newman بشكل جيد

لقد اكتسب Newman مكانته. إنه الرفيق الرسمي مفتوح المصدر لـ Postman، وبالنسبة للفرق التي توجد اختباراتها بالفعل كمجموعات Postman، فهو المسار الأكثر مباشرة من "الاختبارات على جهازي" إلى "الاختبارات في CI". يجدر بنا ذكر نقاط قوته بوضوح قبل أي مقارنة.

إنه مجاني ومفتوح المصدر. يمكنك تثبيته من npm وتشغيله في أي مكان يعمل فيه Node.js، بدون ترخيص منفصل لأداة التشغيل نفسها. مجموعتك هي ملف JSON قابل للنقل يمكنك إيداعه في مستودع، أو تخزينه كقطعة أثرية للبناء (build artifact)، أو جلبه من عنوان URL. هذه القابلية للنقل حقيقية، وهذا يعني أن Newman يندمج في أي مسار عمل تقريبًا دون عوائق.

إنه يعيد استخدام ما بنيته بالفعل. إذا كان فريقك يكتب الطلبات (requests) والبرامج النصية قبل الطلب (pre-request scripts) وتأكيدات الاختبار (test assertions) في Postman، فإن Newman يدير نفس المجموعات دون تغيير. لا توجد إعادة كتابة. البرامج النصية التي كتبتها في محرر Postman تعمل بنفس الطريقة في التشغيل بدون واجهة رسومية، مما يحافظ على منحنى التعلم مسطحًا لفرق Postman.

تثبيته هو أمر واحد:

npm install -g newman

البرنامج الثنائي هو newman. يمكنك تشغيل مجموعة مُصدَّرة عن طريق توجيهها إلى ملف JSON، عادةً مع ملف بيئة بجانبه:

newman run api-tests.postman_collection.json -e staging.postman_environment.json

هذه هي الحلقة الأساسية. قم بتصدير المجموعة من Postman، وأودع ملف JSON، وقم بتشغيله. يقرأ Newman الطلبات والتأكيدات من الملف وينفذها بالترتيب. للحصول على مسار الإعداد الكامل، يشرح دليل Apidog الخاص بـ كيفية تثبيت Newman وتشغيل مجموعات Postman عملية التصدير والتشغيل خطوة بخطوة.

يدعم Newman أيضًا أساسيات CI التي تتوقعها. تأتي التشغيلات المعتمدة على البيانات من ملف CSV أو JSON:

newman run api-tests.postman_collection.json \
  -e staging.postman_environment.json \
  -d users.csv \
  -n 5

هنا، -d يوفر ملف البيانات و -n يحدد عدد التكرارات، بحيث تعمل المجموعة مرة واحدة لكل صف أو عدد ثابت من المرات. هذه هي نفس البدائيات التي تحتاجها أي أداة تشغيل جادة، وقد امتلكها Newman لسنوات.

أين يبدأ Newman في تكليفك

نقاط القوة المذكورة أعلاه صادقة، وكذلك المقايضات، وتظهر في الصيانة اليومية بدلاً من أي أمر واحد.

أكبرها هي خطوة التصدير. مجموعة Postman في CI هي لقطة. تقوم بالإنشاء وتصحيح الأخطاء في تطبيق Postman، ثم تقوم بتصدير ملف JSON للتشغيل بدون واجهة رسومية (headless). في اللحظة التي يقوم فيها شخص ما بتحرير طلب في التطبيق وينسى إعادة التصدير، تنحرف مجموعتك الملتزم بها عن مصدر الحقيقة. يستمر تشغيل CI في النجاح مقابل تعريف قديم بينما واجهة برمجة التطبيقات (API) الحقيقية قد تطورت. لا يوجد شيء في الأدوات يجبر الاثنين على العودة إلى التزامن؛ الأمر متروك لمن يتذكر التصدير.

البرمجة النصية هي الأخرى. تعتمد منطق اختبار Postman على مقتطفات JavaScript المرفقة بكل طلب، وهذه البرامج النصية هي حيث تحدث التسلسل (chaining)، واستخراج المتغيرات، والتأكيدات (assertions). هذا مرن، ولكنه يعني أن مجموعة اختباراتك هي كومة من البرامج النصية الصغيرة لكتابتها وتصحيح أخطائها وصيانتها يدويًا. كلما زادت السيناريوهات، زادت مساحة البرنامج النصي التي تمتلكها. هذا جزء من نمط أوسع تواجهه الفرق مع توسع المجموعات، والذي نناقشه في قيود Postman Collection Runner وكيفية التغلب عليها.

لا شيء من هذا يجعل Newman أداة سيئة. إنه يجعله أداة تشغيل تعتمد سهولة استخدامها (ergonomics) على نموذج تأليف Postman: البرامج النصية بالإضافة إلى خطوة التصدير. إذا كان هذا النموذج يناسب فريقك، فإن Newman جيد. إذا كانت عملية التصدير والمزامنة هي الجزء الذي يستمر في التعطل، فهذا هو بالضبط المكان الذي يمكن أن تساعد فيه أداة تشغيل مختلفة.

ما الذي تفعله Apidog CLI بشكل مختلف

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

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

التثبيت هو أمر npm واحد:

npm install -g apidog-cli

البرنامج الثنائي هو apidog. تشغيل نموذجي يحدد سيناريو بالمعرف (ID)، ويختار بيئة، ويصادق باستخدام رمز وصول (access token):

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r html,junit

لا تكتب هذه المعرفات (IDs) يدويًا. افتح سيناريو الاختبار في Apidog، وانتقل إلى علامة التبويب CI/CD الخاصة به، وقم بإنشاء رمز وصول، وسيقوم Apidog ببناء الأمر الكامل لك مع معرف السيناريو ومعرف البيئة مملوءين بالفعل. تقوم بنسخه مرة واحدة، ثم تنقل الرمز إلى سر CI وتشار إليه باسم $APIDOG_ACCESS_TOKEN. إذا لم تكن متأكدًا من العلامات التي يدعمها الإصدار المثبت لديك، قم بتشغيل apidog run --help وسيطبع الخيارات المتاحة بالضبط.

نموذج الجلب بالمعرف المعتمد على الرمز هو أوضح فرق عن Newman. يقرأ Newman ملف مجموعة من القرص؛ تصل Apidog CLI إلى مشروع عبر الشبكة، مصادقة، وتشغل السيناريو المخزن هناك. لا يوجد خطأ في أي منهما. إنهما يناسبان إعدادات فرق مختلفة، ويكمن الاختيار في الغالب في ما إذا كنت تريد أن يكون الاختبار كملف مُصدَّر أو كسيناريو حي في مساحة عمل مشتركة.

جنباً إلى جنب

يبرز أمران. أولاً، تغطي أداتا التشغيل نفس أساسيات CI: اختيار البيئة، والتكرار المعتمد على البيانات، وتنسيقات التقارير المهمة، والخروج برمز غير صفري عند الفشل. حتى أسماء العلامات قريبة بما يكفي لنقل الذاكرة العضلية (-e، -d، -n، -r). ثانيًا، الانقسام الحقيقي ليس في القدرة الخام. إنه في مكان وجود الاختبار وكيف كتبته. يشغل Newman مجموعة مُصدَّرة تم تأليفها باستخدام برامج نصية. يشغل Apidog سيناريو مرئي مباشر بالرجوع إليه. النسخة الأعمق من هذه المقارنة، التي تتمحور حول أداتي تشغيل Postman-world، موجودة في Postman CLI vs Newman إذا كنت تريد هذه الزاوية أيضًا.

المبلغون ورموز الخروج: الأجزاء التي يقرأها CI بالفعل

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

يحدد Newman التقارير باستخدام علامة -r وقائمة مفصولة بفاصلات. يتم شحن JUnit و JSON جاهزًا؛ يعتبر تقرير HTML هو الأكثر شيوعًا كإضافة:

newman run api-tests.postman_collection.json \
  -e staging.postman_environment.json \
  -r cli,junit \
  --reporter-junit-export ./results/junit.xml

ملف JUnit XML هو ما تقوم لوحة تحكم CI الخاصة بك بتحليله إلى شجرة نجاح أو فشل. علامة --bail في Newman توقف التشغيل بعد أول فشل، مما يحافظ على سرعة ردود الفعل في اختبار "الدخان" (smoke test). بدونها، يكتمل التشغيل ويبلغ عن كل فشل مرة واحدة.

تستخدم Apidog CLI نفس علامة -r المفصولة بفاصلات وتكتب كل شيء تحت دليل إخراج واحد:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 \
  -r html,junit --out-dir ./apidog-reports

علامة --on-error الخاصة بها تشكل السلوك أثناء السيناريو: end يتوقف عند الفشل الأول وهو الافتراضي، continue يشغل كل خطوة لجمع جميع حالات الفشل في تقرير واحد، و ignore يتجاوز خطوة معروفة بأنها غير مستقرة. في كلتا الحالتين، ينتهي التشغيل برمز غير صفري إذا فشل أي شيء.

عقد رمز الخروج هو نفسه على كلا الجانبين، وهو الجزء الذي يتحمل الحمل. عندما يفشل تأكيد، تخرج أداة التشغيل برمز غير صفري. يقرأ CI هذا الرمز، ويضع علامة على الخطوة بأنها فشلت، ويفشل المهمة، ويمنع الدمج أو النشر. لا تقوم بتكوين أي شيء إضافي. المصيدة الوحيدة، المتطابقة لكلا الاثنين، هي ابتلاع رمز الخروج: قم بتغليف التشغيل في مسار عمل shell أو أضف || true وسيتم تجاهل الخروج غير الصفري، وبالتالي يتوقف البوابة عن العمل بصمت. لا تفعل ذلك. للسياق الأوسع حول تنسيقات التقارير، يوضح اختبار API المعتمد على البيانات باستخدام CSV أو JSON كيف يرتبط التقرير ببيانات التكرار.

Newman في GitHub Actions

نظرًا لأن المجموعة عبارة عن ملف مُصدَّر في المستودع (repo)، فإن سير العمل قصير. قم بسحب الكود (Checkout)، وتثبيت Newman، وتشغيل المجموعة، وتحميل التقرير حتى في حالة الفشل.

name: API tests

on:
  pull_request:
    branches: [main]

jobs:
  api-tests:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Newman
        run: npm install -g newman

      - name: Run API tests
        run: |
          newman run ./tests/api-tests.postman_collection.json \
            -e ./tests/staging.postman_environment.json \
            -r cli,junit \
            --reporter-junit-export ./results/junit.xml

      - name: Upload report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: newman-report
          path: ./results

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

Apidog CLI في GitHub Actions

سير عمل Apidog له نفس الشكل، مع تغيير واحد: يأتي رمز الوصول من أسرار المستودع، وتختار السيناريو بالمعرف (ID) بدلاً من الإشارة إلى ملف.

name: API tests

on:
  pull_request:
    branches: [main]

jobs:
  api-tests:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

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

      - name: Run API test scenario
        run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t 605067 \
            -e 1629989 \
            -r html,junit \
            --out-dir ./apidog-reports
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

      - name: Upload report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: apidog-report
          path: ./apidog-reports

لاحظ التماثل. نفس عملية سحب الكود، نفس إعداد Node، نفس شكل التثبيت ثم التشغيل، نفس عملية التحميل دائمًا. الفروقات الحقيقية الوحيدة هي رمز الوصول الموصول كسر، والسيناريو الذي يتم تحديده بواسطة المعرف (ID) بدلاً من مسار الملف. نظرًا لأنه يتم جلب السيناريو بشكل مباشر، فلا يوجد ملف JSON للحفاظ على تحديثه. بالنسبة لنفس النمط في الأنظمة الأخرى، يوضح كيفية أتمتة اختبارات API في GitHub Actions بنية مماثلة عبر GitLab CI و Jenkins.

كيف تختار

نادرًا ما يعود القرار إلى أي أداة تشغيل أفضل بشكل موضوعي. بل يعود إلى مكان وجود اختباراتك بالفعل وكيف يريد فريقك صيانتها.

اختر Newman عندما تكون اختباراتك بالفعل مجموعات Postman. إذا كانت مجموعتك تعيش في Postman، ويكتب فريقك برامج نصية للاختبار في المحرر، وتريد أداة تشغيل مجانية ومفتوحة المصدر تندرج في أي مسار عمل بدون حساب جديد، فإن Newman هو الخيار المباشر. إنه الخيار الطبيعي لفرق Postman التي تشعر بالراحة عند تصدير مجموعة وإيداع ملف JSON، والتي لا تمانع في امتلاك البرامج النصية للاختبار يدويًا. يمكنك قراءة المزيد حول الاختلافات داخل نظام Postman البيئي في ما الفرق بين Newman و Postman.

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

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

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