لقد كتبت اختبارات الواجهة البرمجية (API). وهي تعمل بنجاح على جهازك. وهذا هو بالضبط المكان الذي تبقى فيه، لأن تشغيلها يتطلب أن يتذكر أحدهم القيام بذلك. يقوم زميل في الفريق بنشر تغيير بعد ظهر يوم الجمعة، وتبدأ نقطة نهاية المصادقة (auth endpoint) بصمت في إرجاع رمز 500 في مسار كود معين، وأول من يكتشف ذلك هو مستخدم يوم الاثنين. كانت التغطية موجودة طوال الوقت. لم يقم أحد بتشغيلها في اللحظة التي كان من الممكن أن تكتشف فيها الانحدار.
الحل هو نقل الاختبارات من محرر الكود الخاص بك إلى مسار العمل (pipeline)، بحيث يتم تشغيلها في كل عملية دفع (push) دون تدخل بشري. هذا يعني أنك بحاجة إلى أمر يشغل اختبارات الواجهة البرمجية (API) الخاصة بك بشكل غير مرئي (headless)، ويعيد نتيجة نجاح أو فشل واضحة، ويتناسب مع أي نظام تكامل مستمر (CI) تستخدمه بالفعل. يقوم واجهة سطر الأوامر (CLI) الخاص بـ Apidog بذلك. يمكنك بناء سيناريوهات الاختبار الخاصة بك بصريًا في Apidog، ثم تشغيلها من أمر طرفي واحد يمكن لأي مشغل CI يعمل بنظام Node.js تنفيذه. لا توجد واجهة رسومية، لا إعادة كتابة للاختبارات ككود، ولا خدمة إضافية للاستضافة.
هذا دليل للنسخ واللصق. ستجد أدناه ملفات مسار عمل (pipeline files) جاهزة للاستخدام لـ GitHub Actions و GitLab CI و Jenkins و CircleCI و Azure Pipelines، بالإضافة إلى مجموعة من الأنماط التي تحافظ على سلامة البناء الأخضر. اختر الكتلة المناسبة لمنصتك، واستبدل المعرفات (IDs) الخاصة بك وسرًا، وستكون لديك اختبارات API تحمي كل عملية دمج (merge) بنهاية اليوم. إذا كنت تريد مرجعًا شاملاً للأعلام (flags) بدلاً من ذلك، فإن الموضوع الأوسع حول كيفية أتمتة اختبارات الواجهة البرمجية (API) في CI/CD يغطي الاستراتيجية؛ هذه الصفحة تدور حول كيفية لصق مسار عمل (pipeline) يعمل.
ما الذي تقوم بتوصيله
واجهة سطر الأوامر (CLI) لـ Apidog هي حزمة npm، apidog-cli. تقوم بتشغيل سيناريوهات الاختبار التي تقوم بإنشائها في تطبيق Apidog: طلبات متسلسلة، تأكيدات، قيم مستخرجة من استجابة إلى أخرى، تكرار مدفوع بالبيانات. لا تبتكر واجهة سطر الأوامر (CLI) صيغة اختبار خاصة بها. بل تصل إلى مشروعك، وتجد السيناريو بواسطة المعرف (ID)، وتشغله بنفس الطريقة التي يعمل بها التطبيق، وتقدم تقريرًا برمز خروج (exit code).
رمز الخروج هذا هو جوهر الأمر. عندما تنجح جميع التأكيدات، يخرج التشغيل بالرمز 0. وعندما يفشل أي شيء، يخرج برمز غير صفري. تقرأ أنظمة CI رمز الخروج هذا، وتضع علامة فشل على الخطوة، وتمنع الدمج أو النشر. أنت لا تقوم بتكوين بوابة؛ البوابة هي رمز الخروج. طالما أن خطوة apidog run موجودة في مسار عملك (pipeline)، فإن أي تأكيد خاطئ يوقف السير.
ثلاثة أمور تجعل التشغيل يعمل، وستراها في كل كتلة أدناه:
- رمز وصول (access token)، يثبت أن التشغيل مسموح له بتنفيذ السيناريو الخاص بك. عامله ككلمة مرور. قم بتخزينه كسر CI، وليس أبدًا في ملف ملتزم.
- معرف سيناريو (scenario ID) (أو معرف مجلد، أو معرف مجموعة اختبار)، والذي يحدد ما يجب تشغيله.
- معرف بيئة (environment ID)، والذي يحدد مكان تشغيله: بيئة التطوير (dev)، أو التجريبية (staging)، أو الإنتاج (production).
لا تكتب هذه المعرفات يدويًا. افتح سيناريو الاختبار في Apidog، انتقل إلى علامة التبويب CI/CD الخاصة به، اختر خيار سطر الأوامر، وقم بتوليد رمز وصول (access token). سيوفر لك Apidog الأمر الكامل apidog run مع معرف السيناريو ومعرف البيئة مملوءين مسبقًا. انسخه مرة واحدة، ثم انقل الرمز إلى سر (secret). إذا لم تكن قد أنشأت سيناريو بعد، فابدأ بـ كيفية كتابة سيناريوهات الاختبار باستخدام Apidog وعد عندما يكون لديك سيناريو يعمل بنجاح.
الأمر الوحيد الذي يبنى عليه كل شيء
هنا هو التشغيل الأساسي. كل ملف مسار عمل هو غلاف حول هذا السطر:
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t 605067 \
-e 1629989 \
-n 1 \
-r html,junit \
--out-dir ./apidog-reports
ما تفعله كل جزء:
--access-tokenيقوم بمصادقة التشغيل. يقرأ من متغير البيئة$APIDOG_ACCESS_TOKEN، الذي تقوم بتعبئته من سر (secret).-t 605067يشغل سيناريو الاختبار بهذا المعرف (ID). استبدل-tبـ-f <folderId>لتشغيل مجلد كامل، أو--test-suite <id>لتشغيل مجموعة اختبار منسقة.-e 1629989يستهدف بيئة. هذه هي الطريقة التي يضرب بها نفس السيناريو بيئة التجريب (staging) في فحص طلب السحب (PR check) وبيئة الإنتاج في اختبار دخان (smoke test) بعد النشر.-n 1يشغل السيناريو مرة واحدة. قم بزيادته للتكرار، أو قم بإقرانه بـ-d <file>لتوجيه التكرارات من ملف بيانات CSV أو JSON.-r html,junitيختار تنسيقات التقرير. يقومjunitبإصدار ملف XML الذي تقوم لوحة تحكم CI الخاصة بك بتحليله إلى شجرة نجاح/فشل؛htmlهو تقرير قابل للتصفح يمكنك حفظه كأثر بناء (build artifact). أضفcliإذا كنت تريد مخرجات قابلة للقراءة في السجل أيضًا.--out-dir ./apidog-reportsهو المكان الذي تهبط فيه التقارير.
المُبلغون (reporters) هم الفارق بين "فشل البناء (build went red)" و "هنا التأكيد الذي فشل والاستجابة التي تسببت في الفشل". JUnit XML هو التنسيق الذي تفهمه كل منصة تقريبًا بشكل أصلي، لذلك يظهر في جميع الكتل الخمسة أدناه.
إجراءات GitHub
ضع هذا في .github/workflows/api-tests.yml. يشغل سيناريوك في كل طلب سحب (pull request) مقابل main، ويحمل التقرير كأثر بناء (artifact)، ويفشل الفحص إذا فشل أي تأكيد.
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 \
-n 1 \
-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
تفصيلان مهمان. يعيش الرمز المميز في Settings → Secrets and variables → Actions تحت اسم APIDOG_ACCESS_TOKEN ويصل إلى الخطوة عبر env:. و if: always() في خطوة التحميل يعني أنك لا تزال تحصل على التقرير حتى عندما تفشل الاختبارات، وهي المرة الوحيدة التي تحتاج فيها بالفعل إلى قراءته. إذا تعطل سيناريو، تخرج خطوة apidog run برمز غير صفري، ويتحول العمل (job) إلى اللون الأحمر، ويظهر طلب السحب (PR) فحصًا فاشلاً. للحصول على شرح أعمق لهذه المنصة تحديدًا، راجع كيفية أتمتة اختبارات الواجهة البرمجية (API) في GitHub Actions.
تكامل GitLab المستمر (CI)
نفس الفكرة في .gitlab-ci.yml. تحتوي صورة node:20 بالفعل على بيئة التشغيل، لذا فإن الإعداد الوحيد هو التثبيت.
stages:
- test
api-tests:
stage: test
image: node:20
script:
- npm install -g apidog-cli
- >
apidog run
--access-token "$APIDOG_ACCESS_TOKEN"
-t 605067
-e 1629989
-r junit,cli
--out-dir ./apidog-reports
artifacts:
when: always
paths:
- apidog-reports/
reports:
junit: apidog-reports/*.xml
قم بتخزين APIDOG_ACCESS_TOKEN ضمن Settings → CI/CD → Variables كمتغير محمي ومخفي (masked, protected variable) حتى لا يظهر أبدًا في السجل. الكتلة reports: junit: هي الجزء الذي يميل مستخدمو GitLab إلى تفويته: فهي تخبر GitLab بتحليل XML وعرض النتائج مباشرة في أداة طلب الدمج (merge request widget). يرى المراجع أي تأكيدات فشلت دون الحاجة إلى تنزيل أي شيء.
جنكينز
بالنسبة لمسار العمل التصريحي (declarative pipeline)، قم بتخزين الرمز المميز كاعتماد Jenkins واسحبه إلى البيئة، ثم استدعِ واجهة سطر الأوامر (CLI) في مرحلة. تغذي الكتلة post ملف JUnit XML إلى رسوم بيانية اتجاه الاختبار في Jenkins وتحافظ على تقرير HTML على البناء.
pipeline {
agent any
environment {
APIDOG_ACCESS_TOKEN = credentials('apidog-access-token')
}
stages {
stage('API tests') {
steps {
sh 'npm install -g apidog-cli'
sh '''
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t 605067 \
-e 1629989 \
-n 1 \
-r html,junit \
--out-dir apidog-reports
'''
}
}
}
post {
always {
junit 'apidog-reports/*.xml'
archiveArtifacts artifacts: 'apidog-reports/**', allowEmptyArchive: true
}
}
}
إذا كان وكلاء البناء (build agents) لديك يمتلكون واجهة سطر الأوامر (CLI) مخزنة مؤقتًا بالفعل، قم بإزالة سطر npm install واستدعاء apidog run مباشرة. يقدم Apidog دليل تكامل خاص بـ Jenkins أيضًا إذا كنت تفضل مسار الملحقات (plugin route) بدلاً من خطوة shell: دمج اختبارات Apidog المؤتمتة مع Jenkins لتكامل CI/CD.
سيركل سي آي
في .circleci/config.yml، استخدم صورة Node المريحة وقم بتخزين الرمز المميز كمتغير بيئة مشروع ضمن Project Settings → Environment Variables.
version: 2.1
jobs:
api-tests:
docker:
- image: cimg/node:20.11
steps:
- checkout
- run:
name: Install Apidog CLI
command: npm install -g apidog-cli
- run:
name: Run API test scenario
command: |
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t 605067 \
-e 1629989 \
-r junit,cli \
--out-dir ./apidog-reports
- store_test_results:
path: ./apidog-reports
- store_artifacts:
path: ./apidog-reports
destination: apidog-reports
workflows:
test:
jobs:
- api-tests
store_test_results هو مكافئ CircleCI لكتلة JUnit في GitLab؛ وجهه إلى دليل التقارير وستعرض CircleCI التأكيدات الفاشلة في علامة تبويب الاختبارات (Tests tab) الخاصة بها. يحافظ store_artifacts على تقرير HTML مرفقًا بحيث يمكنك فتحه من صفحة البناء (build page).
خطوط أنابيب Azure
في azure-pipelines.yml، قم بتثبيت Node باستخدام المهمة، وقم بتشغيل واجهة سطر الأوامر (CLI)، وانشر نتائج JUnit. أضف APIDOG_ACCESS_TOKEN كمتغير سري في مسار العمل (أو اسحبه من مجموعة متغيرات Azure Key Vault)، ثم قم بتعيينه في env خطوة السكريبت.
trigger:
- main
pool:
vmImage: ubuntu-latest
steps:
- task: NodeTool@0
inputs:
versionSpec: '20.x'
displayName: 'Install Node.js'
- script: npm install -g apidog-cli
displayName: 'Install Apidog CLI'
- script: |
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t 605067 \
-e 1629989 \
-r junit,html \
--out-dir ./apidog-reports
displayName: 'Run API test scenario'
env:
APIDOG_ACCESS_TOKEN: $(APIDOG_ACCESS_TOKEN)
- task: PublishTestResults@2
condition: always()
inputs:
testResultsFormat: 'JUnit'
testResultsFiles: 'apidog-reports/*.xml'
testRunTitle: 'Apidog API tests'
يقرأ الماكرو $(APIDOG_ACCESS_TOKEN) متغير مسار العمل السري (secret pipeline variable)؛ ويحافظ تعيينه عبر env على إبقائه بعيدًا عن سطر الأوامر المرئي. تجعل PublishTestResults@2 مع condition: always() النتائج تظهر في علامة تبويب الاختبارات (Tests tab) سواء نجح التشغيل أو فشل. للحصول على معالجة أشمل لهذه المنصة، لدى Apidog دليل تفصيلي مخصص حول اختبار الواجهة البرمجية (API) لخط أنابيب Azure DevOps.
أنماط تحافظ على نزاهة البوابة
مسار عمل (pipeline) يشغل اختباراتك هو الأساس. هذه الوصفات هي ما يجعلها مفيدة يومًا بعد يوم.
اختبار الدخان (smoke test) مباشرة بعد النشر. قم بتشغيل سيناريو سريع واحد مقابل بيئة الإنتاج في اللحظة التي يتم فيها إطلاق الإصدار، موجهًا إلى بيئة الإنتاج، وتوقف عند الفشل الأول:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e <prodEnvId> -r cli --on-error end
اختبار الانحدار الكامل (full regression) خلال الليل. قم بتشغيل مجلد كامل من السيناريوهات وفق جدول زمني وجمع كل الأخطاء في تقرير واحد بدلاً من التوقف عند الأول:
apidog run --access-token $APIDOG_ACCESS_TOKEN -f <folderId> -r html,junit --on-error continue --out-dir ./nightly-reports
--on-error هو المفتاح هنا. end يفشل بسرعة، وهو ما تريده لبوابة النشر. continue يشغل كل خطوة بحيث يظهر التقرير الليلي جميع الأعطال دفعة واحدة. في كلتا الحالتين، لا يزال التشغيل يخرج برمز غير صفري إذا فشل أي شيء، لذلك تبقى البوابة صامدة.
قم بتشغيل سيناريو واحد على العديد من المدخلات. قم بتوجيه التكرارات من ملف بيانات وتعامل مع كل صف على أنه نجاح خاص به:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -d ./test-data.csv -r junit
اختبر فرع ميزة (feature branch)، وليس main. قم بتشغيل السيناريوهات تمامًا كما هي موجودة على الفرع:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 --branch feature-payments -e 1629989 -r cli
تصحيح خطأ (debug) يحدث في CI فقط. عندما ينجح سيناريو محليًا ولكنه يفشل في مسار العمل (pipeline)، أضف --verbose. يقوم بطباعة الطلب الدقيق الذي أرسله المشغل والاستجابة الدقيقة التي تلقاها، وهي تقريبًا دائمًا الطريقة التي تجد بها الاختلاف البيئي الذي يسبب الفجوة.
عندما يكذب عليك البناء
تظهر بعض أنماط الفشل بشكل متكرر بما يكفي للإشارة إليها، لأن كل واحد منها يهزم البوابة بهدوء.
يبقى البناء أخضر عندما يجب أن يفشل الاختبار. هذا هو الخطر. يعني ذلك دائمًا تقريبًا أن رمز الخروج يتم تجاهله. إذا قمت بتضمين الأمر في مسار shell، أو أضفت || true لـ "منعه من كسر البناء"، فقد أوقفته أيضًا عن اكتشاف أي شيء. قم بإزالة أي شيء يخفي رمز الخروج غير الصفري. يجب أن تكون خطوة apidog run هي الشيء الذي تقرأه خطوة CI.
أخطاء المصادقة. الرمز المميز خاطئ، أو منتهي الصلاحية، أو لم يصل إلى الأمر أبدًا. تأكد من أن سر CI قد تم ملؤه بالفعل (عرض مخفي لطوله، وليس قيمته أبدًا)، وأعد توليده من علامة تبويب CI/CD الخاصة بالسيناريو إذا لزم الأمر.
“السيناريو غير موجود.” معرف السيناريو، معرف المشروع، أو الفرع لا يتطابق. أعد نسخ الأمر من علامة تبويب CI/CD لضمان أن المعرفات محدثة، وتحقق مرة أخرى من أن --branch يشير إلى المكان الذي تعتقده.
ينجح محليًا، ويفشل في CI. غالبًا ما يكون ذلك بسبب اختلاف البيئة. قد يستهدف المشغل بيئة -e مختلفة، أو يكون خلف جدار حماية لا يمكنه الوصول إلى المضيف الخاص بك، أو يفتقر إلى متغير يحتاجه السيناريو. قم بالتشغيل باستخدام --verbose وقارن الطلب الذي أنتجه المشغل بالطلب الذي ترسله محليًا.
أخطاء TLS ضد المضيفين الداخليين. إذا كانت نقطة النهاية الخاصة بك تستخدم CA داخليًا، فقم بتمرير شهادة CA الإضافية بدلاً من تعطيل التحقق. استخدم -k (تخطي التحقق من SSL) فقط كحل أخير على مضيف داخلي موثوق به بشهادة موقعة ذاتيًا، وليس أبدًا ضد أي شيء عام.
لماذا البناء بصريًا والتشغيل بدون واجهة رسومية
هناك خيار تصميم حقيقي وراء كل هذا، ويستحق فقرة. مع المشغلات التي تعتمد على النصوص أولاً (script-first runners)، يكون الاختبار وتنفيذه في نفس الملف، لذا فإن النص الهش هو اختبارك وعنق الزجاجة لديك. مع Apidog، السيناريو في مشروعك هو الاختبار، وواجهة سطر الأوامر (CLI) تقوم بتشغيله حيث لا يمكن لشخص أن يكون. لا يوجد أحد يحافظ على تمثيلين لنفس الفحص. تقوم بإنشاء المحتوى بسرعة في الباني البصري، وتقوم بالتشغيل تلقائيًا في مسار العمل (pipeline)، ويبقى الاثنان متزامنين لأنهما نفس العنصر (artifact). هذا جزء كبير من سبب تعامل الفرق مع Apidog كـ بديل لـ Postman لاختبار الواجهة البرمجية (API) بمجرد دخول CI إلى الصورة، ولماذا تعتبر تأكيدات الواجهة البرمجية (API) القوية أكثر أهمية من المشغل الذي تقوم بتضمينها فيه.
الحلقة بسيطة بمجرد تشغيلها. قم بتصميم وتصحيح الطلبات في التطبيق. قم بربطها في سيناريو مع تأكيدات. ادفع الكود الخاص بك، وواجهة سطر الأوامر (CLI) تقوم بتشغيل هذا السيناريو في CI عند كل تغيير. عندما يتعطل شيء ما، يحدد التقرير التأكيد (assertion) ويوقف رمز الخروج النشر. تقوم بإصلاحه، تدفع مرة أخرى، وتؤكد نفس البوابة الإصلاح.
إذا كانت اختباراتك لا تزال موجودة في محرر أحدهم، فهذه هي الفجوة التي يجب إغلاقها هذا الأسبوع. قم بتنزيل Apidog، اجعل سيناريو واحد يعمل بنجاح، وانسخ الأمر apidog run من علامة التبويب CI/CD الخاصة به، والصق الكتلة أعلاه لمنصتك. سيكون لديك اختبارات API تحمي كل عملية دمج في نفس الظهيرة.
الأسئلة الشائعة
هل Apidog CLI مجاني للاستخدام في CI؟ واجهة سطر الأوامر (CLI) هي حزمة npm مجانية: npm install -g apidog-cli. تقوم بتشغيل السيناريوهات من مشروع Apidog الخاص بك، لذا ما يمكنك تشغيله يعتمد على خطة Apidog الخاصة بك، ولكن مشغل سطر الأوامر نفسه ليس منتجًا مدفوعًا منفصلاً.
هل يجب علي إعادة كتابة اختباراتي ككود؟ لا. يمكنك بناء السيناريوهات بصريًا في Apidog وتقوم واجهة سطر الأوامر (CLI) بتشغيلها بواسطة المعرف (ID). السيناريو هو الاختبار؛ واجهة سطر الأوامر (CLI) هي فقط المنفذ. هذا هو الشيء الرئيسي الذي يفصلها عن المشغلات التي تعتمد على النصوص أولاً (script-first runners).
كيف يؤدي الاختبار الفاشل إلى فشل البناء الخاص بي فعليًا؟ من خلال رمز الخروج. عندما يفشل أي تأكيد، يخرج apidog run برمز غير صفري. يقرأ نظام CI الخاص بك ذلك، ويضع علامة فشل على الخطوة، ويمنع الدمج أو النشر. لا تضيف أي تهيئة إضافية لكي تعمل البوابة.
ما هو تنسيق التقرير الذي يجب أن أستخدمه؟ استخدم junit لملف XML القابل للقراءة آليًا الذي تحلله لوحة تحكم CI الخاصة بك إلى نتائج نجاح/فشل، وأضف html إذا كنت تريد تقريرًا قابلاً للتصفح محفوظًا كأثر بناء (build artifact). الاقتران الشائع هو -r junit,html. احتفظ بـ cli أيضًا إذا كنت تريد إخراجًا قابلاً للقراءة في سجل البناء.
هل أحتاج إلى تثبيت Apidog على خادم CI؟ لا. يحتاج مشغل CI فقط إلى Node.js (الإصدار 16 أو أحدث) وحزمة apidog-cli. لا يوجد تطبيق سطح مكتب، ولا واجهة رسومية، ولا ملف ترخيص على الجهاز. الحزمة بالإضافة إلى رمز الوصول (access token) كافيان.
هل يمكنني تشغيله بدون تثبيت عام (global install)؟ نعم. استخدم npx apidog-cli run ... لتنفيذه بدون تثبيت عام دائم، وهو أنظف على المشغلات المؤقتة (ephemeral runners) التي يتم إزالتها بعد كل مهمة.
كيف يختلف هذا عن نيومان (Newman)؟ يقوم نيومان بتشغيل مجموعات Postman من سطر الأوامر. يقوم واجهة سطر الأوامر (CLI) لـ Apidog بتشغيل سيناريوهات اختبار Apidog. الأدوار متوازية، ولكن مشغل Apidog ينفذ السيناريوهات التي قمت بإنشائها في التطبيق ويأتي كحزمة apidog-cli واحدة. راجع Postman CLI مقابل Newman للجانب المتعلق بـ Postman من تلك المقارنة.
من أين أحصل على رمز الوصول (access token) والمعرفات (IDs)؟ كل ذلك من علامة تبويب CI/CD لسيناريو الاختبار في Apidog. اختر خيار سطر الأوامر، وقم بتوليد رمز وصول، وانسخ الأمر الكامل apidog run الذي يبنيه Apidog مع معرفات السيناريو والبيئة مملوءة مسبقًا. ثم انقل الرمز إلى سر CI وارجع إليه كـ $APIDOG_ACCESS_TOKEN.