تبدأ معظم اختبارات واجهات برمجة التطبيقات (API) حياتها في واجهة المستخدم الرسومية (GUI). تقوم بالنقر هنا وهناك، وتضيف بعض التأكيدات، وتشغلها يدويًا. يعمل هذا جيدًا حتى تحتاج إلى تشغيل نفس الاختبارات مع كل دفعة (push)، كل ليلة، أو داخل مسار عمل (pipeline) لا يراقبه أحد. في هذه المرحلة، تحتاج إلى أمر واحد يمكنك كتابته وبرمجته وتمريره إلى التكامل المستمر (CI).
هذا الأمر هو Apidog CLI. يرشدك هذا الدليل التعليمي خلال اختبار واجهة برمجة تطبيقات REST حقيقية بالكامل من طرفية جهازك: تثبيت الأداة، استيراد واجهة برمجة تطبيقات، إعداد بيئة، بناء سيناريو اختبار، تشغيله مع التأكيدات، تغذيته بالبيانات، وجمع التقارير. كل أمر ومخرج أدناه يأتي من تشغيل حقيقي على Apidog CLI الإصدار 2.2.2 مقابل واجهة برمجة تطبيقات عامة حية، حتى تتمكن من المتابعة والحصول على نفس النتائج.
إذا كنت ترغب في الجانب المرئي لنفس المنصة، يمكنك تنزيل Apidog وتصميم الاختبارات في التطبيق أولاً. ولكن كل ما هنا يبقى على سطر الأوامر.
ماذا ستبني؟
ستقوم باختبار restful-api.dev، وهي واجهة برمجة تطبيقات REST عامة مجانية مع عمليات CRUD حقيقية على مورد /objects. بحلول النهاية، سيكون لديك:
- مشروع Apidog مُهيأ من ملف OpenAPI
- سيناريو اختبار من ثلاث خطوات يقوم بإنشاء كائن، وقراءته مرة أخرى، وحذفه، مع التأكيد في كل خطوة
- تشغيل قائم على البيانات يكرر طلبًا مرة واحدة لكل صف من بيانات الاختبار
- تقارير CLI وHTML وJSON وJUnit، بالإضافة إلى تقرير سحابي قابل للمشاركة
نفس سير العمل يتوسع ليشمل واجهة برمجة التطبيقات الخاصة بك، وهو الأساس لتشغيل اختبارات واجهة برمجة التطبيقات في CI/CD.
قبل أن تبدأ
تحتاج إلى Node.js 16 أو أحدث وحساب Apidog. إذا كنت تقارن بين أدوات التشغيل أولاً، فإن الملخص هو أن Apidog CLI يقوم بتشغيل سيناريوهات الاختبار الكاملة ويدير موارد واجهة برمجة التطبيقات كتعليمات برمجية، مما يميزه عن Newman وPostman CLI.
الخطوة 1: التثبيت وتسجيل الدخول
قم بتثبيت CLI عالميًا من npm:
npm install -g apidog-cli@latest
تأكد من وجوده:
apidog --version
# 2.2.2
الآن قم بالمصادقة. احصل على رمز مميز من تطبيق Apidog أسفل صورة ملفك الشخصي، إعدادات الحساب، رمز الوصول إلى API، ثم قم بالتشغيل:
apidog login --with-token <YOUR_TOKEN>
يتم حفظ الرمز المميز في ~/.apidog/config.toml، لذا تقوم بذلك مرة واحدة فقط لكل جهاز. تحقق من هويتك:
يعيد كل أمر JSON منظمًا مع علامة success وتلميحات agentHints مفيدة، مما يجعل المخرج سهل البرمجة أو التوجيه إلى jq.
الخطوة 2: إنشاء مشروع
اختر الفريق الذي سيُنشأ المشروع تحته، ثم أنشئه:
apidog team list
apidog project create --team 329562 --name "CLI Field Test"
ستستعيد معرف المشروع الجديد.
احفظه في متغير شل (shell variable) ليكون بقية هذا الدليل التعليمي قابلاً للنسخ واللصق:
PID=1314366 # replace with your project id
apidog project get $PID
الخطوة 3: استيراد واجهة برمجة تطبيقات REST الخاصة بك
يمكنك إنشاء نقاط النهاية يدويًا، لكن استيراد ملف OpenAPI أسرع ويعكس كيفية بدء المشاريع الحقيقية. إليك مواصفات صغيرة تصف نقاط نهاية CRUD الخاصة بـ /objects (احفظها باسم objects-api.openapi.json):
{
"openapi": "3.0.3",
"info": { "title": "Objects API", "version": "1.0.0" },
"servers": [{ "url": "https://api.restful-api.dev" }],
"paths": {
"/objects": {
"get": { "summary": "List objects" },
"post": { "summary": "Create object" }
},
"/objects/{id}": {
"get": { "summary": "Get object by id" },
"put": { "summary": "Update object" },
"delete": { "summary": "Delete object" }
}
}
}
قم باستيراده:
apidog import --project $PID --format openapi --file ./objects-api.openapi.json
# "createCount": 5 (5 endpoints created, 0 errors)
يقرأ المستورد أيضًا openapi وpostman وhar وinsomnia وjmeter والمزيد. قم بإدراج ما تم استيراده:
apidog endpoint list --project $PID
# 37921721 get /objects
# 37921722 post /objects
# 37921723 get /objects/{id}
# 37921724 put /objects/{id}
# 37921725 delete /objects/{id}
الخطوة 4: إعداد بيئة
تحتوي البيئة على عنوان URL الأساسي وأي متغيرات تعيد اختباراتك استخدامها. أنشئ واحدة واحفظ معرفها:
apidog environment create "Production" --project $PID --base-url "https://api.restful-api.dev"
apidog environment list --project $PID
# { "id": 6334917, "name": "Production", "baseUrls": { "default": "https://api.restful-api.dev" } }
ENV=6334917 # replace with your environment id
ستمرر -e $ENV إلى أمر التشغيل لاحقًا حتى يعرف الاختبار إلى أين يرسل الطلبات.
الخطوة 5: تجاوز بوابة كتابة الأتمتة
هذا هو أول شيء يربك الناس. سيناريوهات الاختبار وبيانات الاختبار هي موارد أتمتة، وكتابتها إلى فرعك الرئيسي من أداة خارجية محظورة افتراضيًا:
apidog test-scenario create --project $PID --name "x" --description "" --folder-id 0 --priority 1
# "error": { "code": "403075", "message": "Automation caller branch required" }
هذه وسيلة حماية، وليست خطأ. لديك طريقتان لتجاوزها:
- قم بتشغيل إذن التحرير المباشر في تطبيق Apidog لسطح المكتب ضمن إعدادات المشروع، إعدادات الميزات، إعدادات ميزات الذكاء الاصطناعي، أذونات تحرير الذكاء الاصطناعي الخارجية.
- العمل على فرع AI، والذي يحافظ على تغييرات الأتمتة معزولة حتى تختار الدمج. هذا المسار يبقى بالكامل على سطر الأوامر، لذا هذا ما سنستخدمه.
أنشئ الفرع من main:
apidog branch create --project $PID --type ai \
--name "ai/20260616-from-main-cli-field-test" --from main
BR="ai/20260616-from-main-cli-field-test"
نمط التسمية ai/YYYYMMDD-from-- هو الاصطلاح الذي يتوقعه CLI. لاحظ أن import وenvironment create وتعديلات نقطة النهاية ليست محصورة؛ فقط موارد الأتمتة هي التي تخضع لذلك.
الخطوة 6: بناء سيناريو اختبار
السيناريو هو تدفق مرتب للطلبات مع تأكيدات بينها. تقوم بإنشاء الهيكل الأساسي أولاً، ثم تضيف الخطوات. أنشئه على فرع AI الخاص بك:
apidog test-scenario create --project $PID --branch "$BR" \
--name "Object CRUD lifecycle" \
--description "Create, read, then delete an object and assert each step" \
--folder-id 0 --priority 1
SID=1836498 # the returned scenario id
تتم إضافة الخطوات من خلال update بملف JSON. القاعدة الذهبية عند أي كتابة JSON هي التحقق من الصحة قبل الإرسال، حتى لا تدفع أبدًا حمولة غير صالحة:
apidog cli-schema get test-scenario-update # see the exact shape
apidog cli-schema validate test-scenario-update --file ./steps-crud.json
# "data file is valid"
إليك شكل خطوة الإنشاء، التي تنشر كائنًا جديدًا وتحفظ معرفه (id) للخطوات اللاحقة:
{
"type": "customHttp",
"name": "Create object",
"customHttpRequest": {
"path": "https://api.restful-api.dev/objects",
"method": "post",
"requestBody": { "type": "json", "data": "{\"name\":\"Apidog CLI Field Test\",\"data\":{\"price\":42}}" },
"postProcessors": [{
"type": "customScript",
"data": "pm.test('create returns 200', function () { pm.response.to.have.status(200); });\nvar body = pm.response.json();\npm.globals.set('objId', body.id);",
"enable": true
}],
"projectId": 1314366
}
}
الخطوات التالية تعيد استخدام {{objId}} في عنوان URL لجلب ثم حذف نفس الكائن. طبق ملف الخطوات الثلاث الكامل:
apidog test-scenario update $SID --project $PID --branch "$BR" --file ./steps-crud.json
# "success": true
ليس عليك تأليف السيناريوهات كـ JSON. بناءها بصريًا في Apidog وتشغيلها من CLI صالح بنفس القدر. مسار JSON مهم عندما تريد أن تكون اختباراتك تحت التحكم في الإصدار ومراجعتها مثل أي تعليمات برمجية أخرى.
الخطوة 7: تشغيله من سطر الأوامر
هذه هي المكافأة. قم بتشغيل السيناريو باستخدام مُبلِّغ CLI:
apidog run -t $SID --project $PID --branch "$BR" -e $ENV -r cli
❏ Object CRUD lifecycle
↳ Create object POST .../objects [200 OK]
✓ create returns 200 ✓ response has an id ✓ name was echoed back
↳ Get the created object GET .../objects/ff80...3de [200 OK]
✓ get returns 200 ✓ id matches the created object ✓ price persisted in data
↳ Delete the object DELETE .../objects/ff80...3de [200 OK]
✓ delete returns 200
Http Requests 3 / 0 failed
Assertions 7 / 0 failed
ثلاثة طلبات، سبعة تأكيدات، صفر إخفاقات، وid الذي تم إنشاؤه تدفق من الخطوة الأولى إلى الخطوتين التاليتين. هذا هو اختبار API كامل يعمل دون نقرة واحدة.
هل تريد ملفات بدلاً من مخرج وحدة التحكم؟ اطلب عدة أدوات إبلاغ في وقت واحد ووجهها إلى مجلد:
apidog run -t $SID --project $PID --branch "$BR" -e $ENV \
-r cli,html,json,junit --out-dir ./reports --out-file "crud-report"
ls ./reports
# crud-report.html crud-report.json crud-report.xml
ملف JUnit XML هو ما يقرأه خادم CI الخاص بك لإظهار النجاح/الفشل لكل بناء. تقرير HTML هو الذي تشاركه مع زملائك في الفريق.
الخطوة 8: تشغيل نفس الاختبار مقابل العديد من المدخلات
تغطي مجموعات الاختبار الحقيقية أكثر من حالة واحدة. عمليات التشغيل القائمة على البيانات تكرر السيناريو مرة واحدة لكل صف من البيانات، لذا تختبر عشرة مدخلات دون كتابة عشرة سيناريوهات. هذه هي نفس فكرة الاختبار البارامتري من CSV وJSON.
ضع صفوفك في ملف:
[
{ "name": "Pixel 8 Pro", "price": 999 },
{ "name": "iPhone 15", "price": 899 },
{ "name": "Galaxy S24", "price": 799 }
]
ارجع إلى البيانات باستخدام -d، ودع السيناريو يقرأ {{name}} و{{price}} من كل صف:
apidog run -t $DID --project $PID --branch "$BR" -e $ENV -d ./objects-data.json -r cli
Iteration 1/3 … ✓ row created (200) ✓ name matches the data row
Iteration 2/3 … ✓ row created (200) ✓ name matches the data row
Iteration 3/3 … ✓ row created (200) ✓ name matches the data row
Iterations 3 / 0 failed Assertions 6 / 0 failed
ثلاثة صفوف مدخلة، ثلاث تكرارات مخرجة. استبدل الملف بـ CSV ولن يتغير أي شيء آخر.
الخطوة 9: جمع التقارير
تكتب عمليات التشغيل المحلية ملفات. للحصول على تقرير يمكن لفريقك بالكامل فتحه في متصفح، أضف --upload-report:
apidog run -t $SID --project $PID --branch "$BR" -e $ENV -r cli --upload-report
# Apidog CLI runs data uploaded to the cloud successfully.
# https://app.apidog.com/link/project/1314366/api-test/test-report/2605398
نقطة تستحق المعرفة: يتم وضع علامة على تقرير سحابي بالفرع الذي تم تشغيله عليه. نظرًا لأن هذا التشغيل حدث على فرع AI الخاص بك، فإن أمر apidog test-report list --project $PID العادي (الذي يستهدف main) لن يظهره. قم بجلبها بالمعرف من رابط التحميل بدلاً من ذلك:
apidog test-report get 2605398 --project $PID
apidog test-report download 2605398 --project $PID --format json --output ./cloud-report.json
الخطوة 10: تصدير واجهة برمجة التطبيقات الخاصة بك كوثائق أو مواصفات
يقوم CLI أيضًا بدفع البيانات. قم بتصدير المشروع كملف OpenAPI أو Markdown أو وثائق HTML:
apidog export --project $PID --format openapi --oas-version 3.0 --output ./openapi-export.json
apidog export --project $PID --format markdown --output ./api-docs.md
apidog export --project $PID --format html --output ./api-docs.html
هذا مفيد لالتزام مواصفات جديدة مع كل تغيير أو نشر وثائق ثابتة من مسار عمل.
الخطوة 11: ربطها في CI/CD
كل ما قمت بتشغيله يدويًا يصبح ثلاثة أسطر في مسار عمل. الأساس هو التثبيت، ثم التشغيل باستخدام مُبلِّغ JUnit حتى يتمكن خادم CI من قراءة النتائج:
- run: npm install -g apidog-cli@latest
- run: apidog login --with-token $APIDOG_TOKEN
- run: apidog run -t $SID --project $PID -e $ENV -r junit --out-dir ./reports
قم بتخزين الرمز المميز كسِر، واجعل البناء يفشل عندما يفشل اختبار (يعيد CLI رمز خروج غير صفري عند الفشل). لسير عمل كامل وقابل للنسخ واللصق، راجع الدليل الخاص بتشغيل اختبارات Apidog CLI في GitHub Actions، أو تصفح أدوات أتمتة اختبار API التي تناسب مسار عمل.
تلخيص
لقد انتقلت من طرفية فارغة إلى اختبار API ناجح وموجه بالبيانات مع تقارير قابلة للمشاركة، ولم تغادر سطر الأوامر أبدًا. النمط هو نفسه دائمًا: استيراد أو تصميم واجهة برمجة التطبيقات الخاصة بك، إنشاء بيئة، بناء سيناريو مع تأكيدات، ثم تشغيله باستخدام apidog run. بمجرد أن يعمل هذا الأمر محليًا، فإن إدراجه في CI هو تغيير من ثلاثة أسطر.
وجه نفس الخطوات إلى واجهة برمجة التطبيقات الخاصة بك، التزم بملفات السيناريو جنبًا إلى جنب مع التعليمات البرمجية الخاصة بك، وستعمل اختباراتك في أي مكان يعمل فيه الشل. قم بتنزيل Apidog للبدء، واحتفظ ببدائل curl لاختبار واجهة برمجة تطبيقات REST في متناول اليد لإجراء الفحوصات السريعة لمرة واحدة التي يكون CLI مبالغًا فيها بالنسبة لها.