لقد نسخت أمرًا من علامة تبويب CI/CD، ولصقته في مسار عمل، وقد نجح. ثم يسأل زميل في الفريق لماذا لا يزال البناء ناجحًا رغم فشل اختبار بشكل واضح، أو ما إذا كان بإمكانك توجيه نفس التشغيل إلى بيئة الاختبار (staging) بدلاً من بيئة الإنتاج (production)، أو كيف تحصل على تقرير سيفهمه لوحة تحكم CI الخاصة بك بالفعل. فجأة، لم يعد السطر الواحد كافيًا. أنت بحاجة إلى معرفة ما يفعله كل جزء منه.
apidog run هو الأمر الواحد الذي يمثل جوهر مشغل سطر الأوامر الخاص بـ Apidog. يقوم بتنفيذ سيناريوهات اختبار API التي أنشأتها في Apidog بدون واجهة رسومية، من طرفية، بدون واجهة مستخدم رسومية وبدون تدخل بشري بالنقر على زر. كل ما يمكن للمشغل فعله، يفعله من خلال العلامات على هذا الأمر الوحيد: أي سيناريو يتم تشغيله، أي بيئة يتم استهدافها، كم مرة يتم التكرار، ما هي التقارير التي يتم إصدارها، وما الذي يعتبر فشلاً. تعلم واجهة العلامات مرة واحدة وتتوقف عن النسخ واللصق بشكل أعمى.
ما هو apidog run
واجهة سطر الأوامر (CLI) الخاصة بـ Apidog تأتي كحزمة npm تسمى apidog-cli. تقوم بتثبيتها مرة واحدة وتحصل على ملف تنفيذي واحد، apidog، والذي يكون أمره الفرعي الأساسي هو run. يأخذ هذا الأمر الفرعي أحد سيناريوهات اختبار Apidog الخاصة بك ويشغله بالطريقة التي يعمل بها تطبيق سطح المكتب، ثم يقدم تقريرًا برمز خروج وأي ملفات تقرير طلبتها.
ثبته عالمياً:
npm install -g apidog-cli
تأكيد حل المشكلة:
apidog -v
الشيء الذي يجب فهمه قبل العلامات هو ما يعمل عليه apidog run. لا يحدد تنسيق الاختبار الخاص به. الاختبار هو السيناريو الذي قمت بتأليفه في تطبيق Apidog: طلبات متسلسلة، تأكيدات، قيم مستخرجة من استجابة إلى أخرى، تكرار اختياري يعتمد على البيانات. تدخل واجهة سطر الأوامر إلى مشروعك، وتجد السيناريو بواسطة المعرف، وتشغله. لذا فإن معظم العلامات تتعلق بإخبار المشغل بما يجب جلبه وكيف يتصرف أثناء التشغيل، وليس بكتابة الاختبارات مباشرة.
أمر حقيقي مصغر يبدو هكذا:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r html,cli
هذا يعني: المصادقة باستخدام هذا الرمز المميز، وتشغيل سيناريو الاختبار 605067، مقابل البيئة 1629989، مرة واحدة، وإنتاج تقرير HTML بالإضافة إلى مخرجات طرفية قابلة للقراءة. كل علامة في هذا السطر مشروحة أدناه، بالإضافة إلى تلك التي لا يتضمنها الأمر.
نظرة عامة على جميع خيارات السطح
إليك المجموعة الكاملة من الخيارات مجمعة حسب الوظيفة. استخدمها كجدول مرجعي؛ تشرح الأقسام التي تليها تلك التي تحتاج إلى أكثر من جملة.
| المجموعة | العلامة (Flag) | الوسيط (Argument) | ماذا تتحكم به |
|---|---|---|---|
| تحديد | -t, --test-scenario |
<testScenarioId> |
تشغيل سيناريو واحد بواسطة المعرف |
| تحديد | -f, --test-scenario-folder |
<folderId> |
تشغيل كل سيناريو في مجلد |
| تحديد | --test-suite |
<testSuiteId> |
تشغيل مجموعة اختبار بواسطة المعرف |
| تحديد | --project |
<projectId> |
المشروع الذي ينتمي إليه السيناريو |
| تحديد | --branch |
<branchName> |
التشغيل مقابل فرع (الافتراضي هو main) |
| المصادقة | --access-token |
<accessToken> |
مصادقة التشغيل؛ مطلوب عبر الإنترنت |
| البيئة | -e, --environment |
<environmentId> |
البيئة التي سيتم استهدافها |
| التكرار | -n, --iteration-count |
<n> |
تشغيل السيناريو n مرة |
| التكرار | -d, --iteration-data |
<path> |
توجيه التكرارات من ملف JSON أو CSV |
| التكرار | --variables |
<path> |
تحميل المتغيرات من ملف محلي |
| التكرار | --global-var |
<value> |
تعيين متغير عام مباشرة، key=value |
| التكرار | --env-var |
<value> |
تجاوز متغير بيئة مباشرة، key=value |
| التقرير | -r, --reporters |
[reporters] |
تنسيقات التقرير: cli، html، json، junit |
| التقرير | --out-dir |
<outDir> |
المكان الذي تُكتب فيه التقارير |
| التقرير | --out-file |
<outFile> |
اسم ملف التقرير، مع عناصر نائبة للاسم |
| التقرير | --out-json-failures-separated |
<value> |
كتابة الإخفاقات إلى ملف JSON منفصل |
| التقرير | --upload-report |
[value] |
تحميل نظرة عامة على التقرير إلى سحابة Apidog |
| الأخطاء | --on-error |
<behavior> |
ignore (تجاهل)، continue (استمرار)، أو end (إنهاء) عند الفشل |
| الأخطاء | --ignore-redirects |
عدم متابعة إعادة توجيه HTTP | |
| الأخطاء | --delay-request |
[n] |
انتظر n ملي ثانية بين الطلبات |
| الأخطاء | --timeout-request |
[n] |
مهلة كل طلب بالملي ثانية |
| الأخطاء | --timeout-script |
[n] |
مهلة تنفيذ السكريبت بالملي ثانية |
| TLS | -k, --insecure |
تعطيل التحقق من شهادة SSL | |
| TLS | --ssl-client-cert |
<path> |
شهادة العميل (PEM) |
| TLS | --ssl-client-key |
<path> |
المفتاح الخاص لشهادة العميل |
| TLS | --ssl-client-passphrase |
<passphrase> |
عبارة المرور لشهادة العميل |
| TLS | --ssl-client-cert-list |
<path> |
تعيين تكوين الشهادات للمضيفين |
| TLS | --ssl-extra-ca-certs |
<path> |
شهادات CA إضافية موثوقة |
| المخرجات | --verbose |
طباعة تفاصيل الطلب والاستجابة بالكامل | |
| المخرجات | --silent |
منع إخراج وحدة التحكم | |
| المخرجات | --color |
<value> |
فرض إخراج ملون (تشغيل/إيقاف) |
| المخرجات | --external-program-path |
<path> |
ملف البرامج الخارجية للمنطق المخصص |
| المخرجات | --database-connection |
<path> |
تكوين قاعدة البيانات للخطوات التي تستعلم قاعدة البيانات |
| المخرجات | --preferred-http-version |
<version> |
إصدار بروتوكول HTTP المفضل |
| المخرجات | -b, --bigint |
تفعيل BigInt للقيم الرقمية الكبيرة | |
| المخرجات | --lang |
<language> |
لغة واجهة سطر الأوامر (CLI) |
| المخرجات | -h, --help |
طباعة المساعدة |
قد تتغير أسماء العلامات والقيم الافتراضية بين إصدارات CLI. عند الشك، المشغل هو مصدر الحقيقة الخاص به: قم بتشغيل apidog run --help على الإصدار المثبت لديك وثق به أكثر من أي مقال، بما في ذلك هذا المقال.
اختيار ما سيتم تشغيله
تحدد ثلاث علامات نطاق التشغيل، وتختار واحدة منها فقط لكل أمر.
-t, --test-scenario <id> يشغل سيناريو واحد. هذه هي الحالة اليومية: اختبار دخاني مركّز واحد، سيناريو تراجع واحد، شيء واحد تريد حمايته على طلب سحب.
-f, --test-scenario-folder <id> يشغل كل سيناريو داخل مجلد. استخدم هذا عندما تكون قد نظمت منطقة ميزات في مجلد وتريد تشغيل المجموعة بأكملها كوظيفة واحدة، مثل مسح التراجع الليلي.
--test-suite <id> يشغل مجموعة اختبار منسقة، وهي مجموعة من السيناريوهات التي جمعتها لتشغيلها معًا كوحدة منطقية واحدة. المجموعة هي الأداة المناسبة عندما لا تكون السيناريوهات التي تريدها كلها في مجلد واحد ولكنها لا تزال تنتمي إلى نفس تمرير الاختبار.
يحدد محددان آخران المكان الذي يبحث فيه المشغل. --project <id> يحدد المشروع الذي يعيش فيه السيناريو، وهو مفيد عندما يكون لرمزك المميز صلاحية الوصول إلى أكثر من مشروع واحد. --branch <name> يشغل السيناريو كما هو موجود في فرع معين بدلاً من main، مما يتيح لك التحقق من تغييرات الاختبار في فرع ميزة قبل دمجها.
# سيناريو واحد
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli
# مجلد كامل
apidog run --access-token $APIDOG_ACCESS_TOKEN -f 88012 -r html,junit
# مجموعة منسقة
apidog run --access-token $APIDOG_ACCESS_TOKEN --test-suite 40231 -r junit
المصادقة على التشغيل
--access-token <token> هي العلامة الوحيدة التي يحتاجها كل تشغيل عبر الإنترنت. إنها تثبت أن التشغيل مسموح له بجلب سيناريو الخاص بك وتنفيذه. تقوم بإنشاء الرمز المميز داخل علامة تبويب CI/CD لسيناريو الاختبار في Apidog، حيث يقوم التطبيق أيضًا بإنشاء أمر apidog run الكامل لك مع معرف السيناريو ومعرف البيئة المملوئين بالفعل.
تعامل مع الرمز المميز ككلمة مرور. لا تلصقه في ملف مسار عمل تم الالتزام به أو في نص برمجي مشترك. قم بتخزينه كسر في نظام CI الخاص بك ومرره عبر متغير بيئة، ولهذا السبب تشير كل الأمثلة هنا إلى $APIDOG_ACCESS_TOKEN بدلاً من سلسلة حرفية. إذا تسرب الرمز المميز، قم بإعادة إنشائه من نفس علامة تبويب CI/CD وسيتوقف الرمز القديم عن العمل.
استهداف بيئة والتكرار
علامة البيئة هي ما يسمح لسيناريو واحد بخدمة أغراض متعددة. -e, --environment <id> توجه التشغيل إلى بيئة محددة، لذا يمكن لنفس السيناريو التحقق من بيئة الاختبار (staging) في بوابة طلب سحب وبيئة الإنتاج (production) في اختبار دخاني بعد النشر دون الحاجة إلى تكرار أي شيء. إذا كنت تدير القيم عبر البيئات، فإن الدليل حول إدارة البيئة والأسرار لعملاء API يغطي كيفية تدفق تلك القيم.
-n, --iteration-count <n> يشغل السيناريو n مرة متتالية. مفيد لإجراء فحص سريع للاستقرار أو لتكرار تدفق يجب أن يكون متطابقًا.
-d, --iteration-data <path> هي علامة البيانات المدفوعة. وجهها إلى ملف JSON أو CSV وسيقوم المشغل بتنفيذ السيناريو مرة واحدة لكل صف، مع التعامل مع كل صف على أنه تمرير خاص به بقيم إدخال خاصة به. هكذا تقوم بتشغيل سيناريو تسجيل دخول واحد عبر خمسين حسابًا، أو تدفق إنشاء طلب واحد عبر جدول من البيانات. النمط الأعمق موجود في اختبار API المدفوع بالبيانات باستخدام CSV و JSON.
تُدخل ثلاث علامات قيمًا دون تعديل السيناريو. --variables <path> يحمل المتغيرات من ملف محلي. --global-var key=value يعيّن متغيرًا عامًا مباشرة. --env-var key=value يتجاوز متغير بيئة واحدًا لهذا التشغيل فقط. هذه مفيدة في CI عندما تختلف قيمة (عنوان URL أساسي، علامة ميزة) لكل مسار عمل ولا تريد بيئة منفصلة لكل منها. إذا كانت المتغيرات في Apidog جديدة عليك، فإن إتقان المتغيرات في Apidog يشرح النطاقات.
# تشغيل سيناريو 50 مرة عبر ملف CSV من المدخلات
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -d ./accounts.csv -r junit
# تجاوز متغير بيئة واحد لهذا التشغيل فقط
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 --env-var baseUrl=https://staging.internal -r cli
المُبلغون: كل تنسيق إخراج يمكن أن ينتجه apidog run
هذه هي المجموعة التي يبحث عنها الناس أكثر من غيرها، لذا إليك كل مُبلغ وما هو غرضه. يمكنك تحديدها باستخدام -r, --reporters ويمكنك تمرير العديد منها في آن واحد، مفصولة بفاصلات. الافتراضي هو cli.
cli يطبع ملخصًا قابلاً للقراءة إلى الطرفية. إنه ما يقوم الإنسان بمسحه ضوئيًا في سجل البناء لرؤية عدد النجاحات/الإخفاقات وأي التأكيدات قد تعطلت. احتفظ به حتى جنبًا إلى جنب مع التنسيقات الآلية ليبقى السجل مفيدًا.
html يكتب تقرير HTML مكتمل بذاته. ارشفه كقطعة أثرية للبناء وافتحه في المتصفح لرؤية التشغيل الكامل مع تفاصيل الطلب والاستجابة. هذا هو التنسيق الذي تسلمه لشخص لم يكن يراقب مسار العمل.
junit يصدر XML بتنسيق JUnit القياسي. كل لوحة تحكم CI تقريبًا تعرف كيفية تحليل JUnit XML إلى شجرة نجاح/فشل، وإظهار الإخفاقات في واجهة مستخدم طلب الدمج، وتتبع النتائج بمرور الوقت. إذا اخترت تنسيقًا آليًا واحدًا فقط لـ CI، فاختر هذا.
json ينتج النتيجة المنظمة الخام. استخدمه عندما تريد معالجة النتائج بنفسك بعد ذلك: قم بتغذيته إلى نص برمجي، ادفع المقاييس إلى مكان ما، أو أنشئ ملخصًا مخصصًا.
مزيج CI الشائع هو HTML للبشر بالإضافة إلى JUnit للوحة التحكم:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -r html,junit --out-dir ./apidog-reports
تتحكم علامات التقرير المتبقية في مكان هبوط الإخراج وما هي الإضافات التي يتضمنها:
--out-dir <dir>يحدد الدليل الذي تُكتب فيه التقارير. الافتراضي هو./apidog-reports.--out-file <name>يحدد اسم ملف التقرير ويقبل العناصر النائبة{FOLDER_NAME}،{SCENARIO_NAME}، و{GENERATE_TIME}، بحيث يمكنك ختم الملفات باسم السيناريو وطابع زمني بدلاً من الكتابة فوق ملف واحد في كل تشغيل.--out-json-failures-separated <value>يقسم الإخفاقات إلى ملف JSON خاص بها، مما يجعل مقارنة الإخفاقات فقط سهلة القراءة.--upload-report [value]يحمل نظرة عامة على التقرير إلى سحابة Apidog بحيث يظهر التشغيل في سجل مشروعك جنبًا إلى جنب مع الملفات المحلية.
التحكم في الفشل: معالجة الأخطاء وأكواد الخروج
المشغل مفيد فقط في مسار العمل إذا أخبر مسار العمل ما إذا كانت الاختبارات قد نجحت. يقوم apidog run بذلك بالطريقة التي تعمل بها أدوات سطر الأوامر الجيدة: يخرج برمز 0 عندما تنجح جميع التأكيدات ورمز غير صفري عندما يفشل أي شيء. هذا السلوك الفردي هو البوابة الكاملة للجودة. يقرأ CI رمز الخروج، ويضع علامة على الخطوة بأنها فاشلة، ويمنع الدمج أو النشر. أنت لا تقوم بتكوين بوابة؛ رمز الخروج هو البوابة.
--on-error <behavior> يشكل ما يحدث عندما تفشل خطوة في منتصف السيناريو، وله ثلاث قيم:
endيوقف التشغيل عند أول خطوة فاشلة. استخدمه لاختبار دخاني سريع الفشل حيث تريد ردود الفعل لحظة حدوث أي عطل.continueيشغل كل خطوة متبقية حتى تجمع جميع الإخفاقات في تقرير واحد. استخدمه لمسح تراجع حيث رؤية كل عطل في وقت واحد يوفر جولة ذهاب وإياب.ignoreيسمح للتشغيل بالاستمرار بعد خطوة معروفة بأنها غير مستقرة دون التعامل معها على أنها قاتلة. استخدمه بحذر؛ يجب ألا تخفي خطوة تم تجاهلها تراجعًا حقيقيًا.
في كلتا الحالتين، إذا فشل أي تأكيد، فإن التشغيل لا يزال ينتهي برمز غير صفري، لذا فإن البوابة تحتفظ بقيمتها بغض النظر عن السلوك الذي اخترته. شيء واحد يعطل البوابة بصمت: تضمين الأمر في شيء يبتلع رمز الخروج الخاص به، مثل إضافة || true في شل. لا تفعل ذلك. الخروج غير الصفري هو الهدف بأكمله.
تعدل أربع علامات سلوك الطلب أثناء التشغيل:
--ignore-redirectsيوقف المشغل عن متابعة عمليات إعادة توجيه HTTP تلقائيًا، حتى تتمكن من التأكد من استجابة إعادة التوجيه نفسها.--delay-request [n]ينتظرnملي ثانية بين الطلبات، مما يساعد في مواجهة حدود المعدل أو نقاط النهاية الحساسة للحمل.--timeout-request [n]يحدد الحد الأقصى للوقت الذي يستغرقه طلب واحد، بالملي ثانية.--timeout-script [n]يحدد الحد الأقصى للوقت الذي يمكن أن يستغرقه نص برمجي قبل أو بعد الطلب، بالملي ثانية.
# اختبار دخاني: التوقف عند أول فشل
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli --on-error end
# التراجع: تشغيل كل شيء، جمع كل الفشل
apidog run --access-token $APIDOG_ACCESS_TOKEN -f 88012 -r html,junit --on-error continue --out-dir ./nightly-reports
TLS والشهادات
عندما تختبر نقاط النهاية خلف TLS متبادل أو سلطة شهادات داخلية، هذه المجموعة هي كيفية إجراء الاتصال.
-k, --insecure يعطل التحقق من شهادة SSL تمامًا. استخدمه فقط ضد مضيف داخلي موثوق به بشهادة موقعة ذاتيًا؛ لا توجهه أبدًا إلى أي شيء عام، لأنه يوقف الفحص الذي يحمي الاتصال.
للحصول على TLS متبادل صحيح، قم بتوفير بيانات اعتماد العميل بدلاً من ذلك: --ssl-client-cert <path> لشهادة PEM، --ssl-client-key <path> لمفتاحها الخاص، و --ssl-client-passphrase <passphrase> إذا كان المفتاح مشفرًا. عندما تحتاج المضيفات المختلفة إلى شهادات مختلفة، --ssl-client-cert-list <path> يشير إلى ملف تكوين يربطها. و --ssl-extra-ca-certs <path> يضيف شهادات CA موثوقة إضافية، وهو الحل النظيف لسلسلة CA داخلية لن يتعرف عليها المشغل بخلاف ذلك، وهو أفضل من استخدام -k.
المخرجات والتشخيص
تتحكم المجموعة الأخيرة في ما يطبعه المشغل وعدد قليل من تفاصيل التنفيذ.
--verbose يطبع الطلب والاستجابة الكاملة لكل خطوة. هذه هي خطوتك الأولى عندما ينجح سيناريو محليًا ولكنه يفشل في CI: إنه يظهر البايتات الدقيقة التي أرسلها المشغل واستقبلها، حتى تتمكن من مقارنتها بما ترسله يدويًا. --silent يفعل العكس، يمنع إخراج وحدة التحكم للوظائف المجدولة الصاخبة حيث تهتم فقط برمز الخروج والتقرير المحفوظ. --color <value> يفرض الإخراج الملون تشغيلًا أو إيقافًا، وهو مفيد عندما يقوم عارض سجل CI بتشويه رموز ANSI.
الباقي مخصص لميزات السيناريو المحددة:
--external-program-path <path>يشير إلى ملف البرامج الخارجية للمنطق المخصص الذي يستدعيه السيناريو.--database-connection <path>يوفر تكوين قاعدة بيانات للسيناريوهات ذات الخطوات التي تستعلم قاعدة بيانات مباشرة.--preferred-http-version <version>يحدد إصدار بروتوكول HTTP المفضل للمشغل.-b, --bigintيمكن التعامل مع BigInt بحيث لا تفقد القيم الرقمية الكبيرة الدقة.--lang <language>يحدد لغة عرض واجهة سطر الأوامر (CLI).-h, --helpيطبع نص المساعدة، وهو القائمة الموثوقة للإصدار المثبت لديك.
تجميعها: الأوامر التي ستشغلها بالفعل
اختبار دخاني مقابل بيئة الإنتاج مباشرة بعد النشر، بفشل سريع:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e $PROD_ENV_ID -r cli --on-error end
تراجع ليلي كامل على مجلد، كل فشل في تقرير HTML و JUnit واحد:
apidog run --access-token $APIDOG_ACCESS_TOKEN -f 88012 -r html,junit --on-error continue --out-dir ./nightly-reports
تشغيل يعتمد على البيانات عبر ملف CSV، مخرج قابل للقراءة آليًا لـ CI:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -d ./test-cases.csv -r junit
التحقق من تغييرات الاختبار على فرع ميزة قبل دمجها:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 --branch feature-payments -e 1629989 -r cli
تصحيح فشل يحدث في CI فقط عن طريق تفريغ التفاصيل السلكية:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli --verbose
إذا كنت تقوم بتشغيل CLI على مشغل CI مؤقت وتفضل عدم تثبيته عالميًا، فاستبدل التثبيت بـ npx:
npx apidog-cli run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r junit
هذا يغطي نفس السطح. الاختيار بين التثبيت العالمي و npx يتعلق بنظافة المشغل، وليس القدرة. لإعداد السيناريو الذي يشغله CLI، قم بتنزيل Apidog، أنشئ سيناريو واحدًا في التطبيق، ثم انسخ الأمر الذي تم إنشاؤه من علامة تبويب CI/CD الخاصة به وقم بتحديد المعلمات للرمز المميز.