تشغيل الاختبار الذي لا يطبع أي شيء مفيد هو تشغيل اختبار لا يثق به أحد. عندما يتحول خط الأنابيب الخاص بك إلى اللون الأحمر، يفتح أحدهم سجل الإنشاء، وكل ما يجده هو جدار من الطوابع الزمنية ورمز خروج غير صفري. أي تأكيد تعطل؟ ضد أي بيئة؟ على أي صف من ملف البيانات؟ التشغيل عرف ذلك. لكنه لم يدونه أبدًا في مكان يمكنك قراءته لاحقًا.
هذه هي الفجوة التي يملؤها المُبلغ (reporter). عندما تقوم بتشغيل اختبارات API من سطر الأوامر، يكون التقرير هو الجزء الذي تتعايش معه بالفعل: القطعة الأثرية التي تقوم بأرشفتها، الملف الذي يحلله لوحة تحكم التكامل المستمر (CI) الخاصة بك، الشيء الذي تسلمه لزميل في الساعة 9 صباحًا لم يكن يراقب خط الأنابيب في الساعة 2 صباحًا. حكم الاختبار هو نصف المهمة فقط. النصف الآخر هو جعل هذا الحكم مقروءًا للإنسان وللآلة في نفس الوقت.
مشغل سطر أوامر Apidog يتعامل مع كليهما. Apidog يأتي مع واجهة سطر أوامر (CLI) تقوم بتشغيل سيناريوهات الاختبار التي بنيتها بصريًا في التطبيق، ويتحكم فيها علامة واحدة في كل تقرير تنتجه: -r, --reporters. تمرر إليها قائمة مفصولة بفواصل، يكتب المشغل كل تنسيق إلى القرص، وأنت تقرر من يقرأ ماذا. هذا الدليل يدور حول تلك العلامة والملفات التي تنتجها: ما هو الغرض من كل مُبلغ، وما الذي يهبط على القرص، وأين يهبط، وكيفية ربط كل واحد بسير عمل حقيقي. إذا كنت تريد جولة أوسع لكل علامة يقبلها المشغل، فإن مرجع أمر تشغيل Apidog يغطي السطح الكامل؛ هذه الصفحة تركز على التقارير.
لماذا التقرير أهم من التشغيل
قم بتشغيل سيناريو محليًا وشاهد ما يحدث. ترى كل طلب يتم إطلاقه، كل تأكيد يتحول إلى اللون الأخضر، الملخص في النهاية. حلقة التغذية الراجعة هي الطرفية أمامك، مباشرة.
في CI، تختفي هذه الحلقة. يتم التشغيل على جهاز لا تراه أبدًا، في وقت لم تكن تراقبه، والسجل الوحيد هو ما تم كتابته على القرص قبل خروج المشغل. إذا لم ينتج التشغيل أي تقرير، فإن الفشل يخبرك فقط أن شيئًا ما تعطل. تضطر إلى إعادة تشغيل كل شيء محليًا على أمل أن يتعطل بنفس الطريقة.
التقرير الجيد يغلق هذه المسافة. يلتقط أي سيناريو تم تشغيله، ضد أي بيئة، وعدد التكرارات، وأي التأكيدات نجحت، وأي منها فشل، وتفاصيل الطلب والاستجابة وراء كل فشل. الحصول على ذلك على القرص يجعل الفشل في الساعة 2 صباحًا قراءة مدتها خمس دقائق في صباح اليوم التالي بدلاً من البحث عن طريقة لإعادة إنتاجه. هذا هو السبب الوحيد لوجود علامة المُبلغ، ولهذا السبب يستحق اختيار التنسيق المناسب لكل جمهور بضع دقائق من التفكير.
العلامة الواحدة التي تتحكم في كل تقرير
واجهة سطر أوامر Apidog (CLI) هي حزمة npm تسمى apidog-cli. قم بتثبيتها مرة واحدة وستحصل على ملف تنفيذي واحد، apidog، والذي يكون أمره الفرعي الرئيسي هو run. قم بتثبيته عالميًا:
npm install -g apidog-cli
يأتي كل تقرير يمكن للمشغل إنتاجه من علامة واحدة في هذا الأمر: -r, --reporters. يأخذ قائمة مفصولة بفواصل، والقيم الأربع التي يقبلها هي cli، html، json، و junit. الافتراضي، إذا لم تمرر أي شيء، هو cli.
تشغيل كامل مع مُبلغين يبدو كالتالي:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r html,cli
يؤدي هذا إلى المصادقة باستخدام رمز مميز، وتشغيل سيناريو الاختبار 605067 مقابل البيئة 1629989 مرة واحدة، ويصدر ملف HTML وإخراج طرفي مقروء. المعرفات هي معرف السيناريو ومعرف البيئة؛ يمكنك نسخ كلاهما، جنبًا إلى جنب مع رمز الوصول، من علامة تبويب CI/CD للسيناريو في Apidog بدلاً من كتابتها يدويًا. إذا كان أي من هذا الإعداد غير مألوف، فإن دليل Apidog CLI الشامل يشرح التثبيت والرموز المميزة وتشغيلك الأول من البداية إلى النهاية.
الفكرة الرئيسية: تشغيل واحد يمكن أن ينتج عدة تقارير في وقت واحد. أنت لا تختار تنسيقًا واحدًا. أنت تختار جمهورًا لكل مخرج وتسردها معًا. يصدر سطر CI نموذجي ملف HTML سهل القراءة للإنسان وملف JUnit يمكن قراءته آليًا من نفس التنفيذ، لذلك يخدم نفس التشغيل شخصًا ولوحة تحكم.
cli: التقرير الذي تقرأه في سجل الإنشاء
يطبع مُبلغ cli ملخصًا مقروءًا مباشرة إلى الطرفية. إنه الافتراضي، وهو الذي يقوم الإنسان بمسحه أولاً.
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli
ما يوفره لك هو الحكم المباشر: كم عدد الطلبات التي تم تشغيلها، كم عدد التأكيدات التي نجحت وفشلت، وأي التأكيدات المحددة تعطلت. في سجل بناء CI، هذه هي الكتلة التي يقرأها أحدهم عندما ينقر على مهمة فاشلة. تخبرهم على الفور ما إذا كان الفشل هو تأكيد واحد معطل أم خمسين، وأي نقطة نهاية متورطة، قبل أن يكلفوا أنفسهم عناء تنزيل أي شيء.
ابقِ cli قيد التشغيل حتى عندما تكتب تنسيقات آلية. لا يكلف شيئًا ويحافظ على فائدة سجل البناء بحد ذاته. خط أنابيب يصدر فقط JUnit XML ينتج لوحة تحكم مثالية وسجل عديم الفائدة؛ أي شخص يقرأ الإخراج الخام لا يرى سوى بدء تشغيل المشغل وخروجه. إضافة cli إلى القائمة يصلح ذلك:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli,junit --out-dir ./apidog-reports
علامتان إضافيتان تحددان ما يطبعه cli. --verbose يوسعه ليشمل الطلب والاستجابة الكاملين لكل خطوة، وهي خطوتك الأولى عندما ينجح سيناريو على جهاز الكمبيوتر المحمول الخاص بك ولكنه يفشل في خط الأنابيب؛ تُظهر لك تفاصيل الاتصال بالضبط ما أرسله المشغل وتلقاه. --silent يفعل العكس ويكبت إخراج وحدة التحكم بالكامل، وهو ما يناسب مهمة مجدولة صاخبة حيث تهتم فقط برمز الخروج والملف المحفوظ.
html: التقرير الذي تسلمه للإنسان
يكتب مُبلغ html ملف HTML مستقل بذاته. افتحه في أي متصفح وستحصل على تشغيل كامل معروض بصريًا: كل طلب، التأكيدات عليه، حالة النجاح والفشل، وتفاصيل الطلب والاستجابة وراء كل خطوة. لا شيء للتثبيت، لا خادم للتشغيل؛ إنه ملف واحد تقوم بالنقر المزدوج عليه.
هذا هو التنسيق الذي تقوم بأرشفته ومشاركته. احفظه كقطعة أثرية للبناء وسيظل التقرير موجودًا بعد انتهاء تشغيل خط الأنابيب، لذلك بعد أسبوع لا يزال بإمكانك فتح التقرير المحدد من النشر الذي تعطل. هذا أيضًا ما ترسله للشخص الذي يسأل "ماذا فشل؟" دون جعله يثبت واجهة سطر الأوامر أو يعيد تشغيل أي شيء. يفتحون الملف، يرون الخطوة الحمراء، يقرأون جسم الاستجابة الذي أثار التأكيد، وينتهون.
يحتل HTML مكانه الأكثر أهمية في التشغيل المستند إلى البيانات. عندما يقوم سيناريو واحد بالتكرار على ملف CSV يحتوي على خمسين صفًا، يُظهر لك تقرير HTML النتيجة لكل تكرار، بحيث يمكنك رؤية أن الصفوف من 1 إلى 49 نجحت وفشل الصف 50 لأن حسابًا واحدًا كان لديه رمز مميز قديم. لا يمكن لعدد النجاح أو الفشل وحده أن يخبرك بذلك. إذا قمت بتشغيل سيناريوهات عبر ملفات البيانات، يتم تغطية النمط في اختبار API المستند إلى البيانات باستخدام CSV و JSON.
المفاضلة: HTML مخصص للعين البشرية، وليس للتحليل. لا تحاول استخراج حالة النجاح/الفشل منه في نص برمجي. هذا ما صمم JSON و JUnit من أجله.
junit: التقرير الذي تحلله لوحة تحكم CI الخاصة بك
يصدر مُبلغ junit ملف XML بتنسيق JUnit القياسي. هذا التنسيق مهم لأنه لغة مشتركة لتقارير اختبار التكامل المستمر (CI). جميع أنظمة CI تقريبًا، مثل GitHub Actions و GitLab CI و Jenkins و CircleCI و Azure Pipelines، تعرف كيفية قراءة JUnit XML وتحويله إلى شجرة نجاح/فشل، وإظهار الأعطال في أداة دمج الطلبات، وتتبع النتائج عبر البناءات بمرور الوقت.
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r junit --out-dir ./apidog-reports
إذا اخترت تنسيقًا آليًا واحدًا فقط لـ CI، فاختر هذا. المكافأة هي أن نتائج اختباراتك تتوقف عن العيش في ملف سجل فقط وتبدأ في العيش في لوحة التحكم التي ينظر إليها فريقك بالفعل. يفتح المراجع طلب سحب ويرى التأكيدات التي فشلت معروضة بشكل مباشر، دون الحاجة إلى البحث في السجل، ولا تنزيل القطع الأثرية.
يتطلب توصيلها خطوتين: إنتاج XML، ثم إخبار نظام CI الخاص بك بمكان العثور عليه. في GitLab CI، الخطوة الثانية هي كتلة reports: junit::
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
في Jenkins، المكافئ هو خطوة junit في كتلة post تشير إلى نفس الملفات. في GitHub Actions، تقوم بتحميل الدليل كقطعة أثرية وتترك إجراءً يدعم JUnit يعرضه. سير عمل GitHub الكامل، بما في ذلك تحميل القطع الأثرية الذي يعمل حتى عندما تفشل الاختبارات، موجود في تشغيل اختبارات Apidog CLI في GitHub Actions.
json: التقرير الذي تعالجه نصوصك البرمجية بعد المعالجة
ينتج مُبلغ json النتيجة الهيكلية الخام. بينما HTML للعين و JUnit للوحات المعلومات، فإن JSON هو للرمز الذي تكتبه بنفسك.
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r json --out-dir ./apidog-reports
استخدمه عندما لا تتناسب التنسيقات المضمنة مع ما تريد فعله بالنتيجة. ادفع مقاييس معدل النجاح إلى نظام مراقبة. أنشئ ملخص Slack مخصصًا. قم بتغذية النتيجة في نص برمجي يقرر ما إذا كان سيتم التراجع عن نشر. قارن تشغيل اليوم بتشغيل الأمس. يبدأ أي شيء برمجي من JSON، لأنه التنسيق الذي يمكنك تحليله دون التخمين حول الهيكل.
تم تصميم علامة تقرير واحدة خصيصًا لإخراج JSON. --out-json-failures-separated <value> يقسم الفشل إلى ملف JSON خاص به. يمنحك ذلك مستندًا للفشل فقط، وهو أسهل بكثير في القراءة والمقارنة من مسح نتيجة كاملة للخطوات القليلة التي تعطلت. في مسح انحدار كبير حيث تنجح معظم الخطوات، فإن ملف الفشل فقط هو الفرق بين نظرة سريعة وبحث شامل.
أين تهبط الملفات: --out-dir و --out-file والعناصر النائبة
اختيار التنسيقات هو نصف الصورة. النصف الآخر هو التحكم في مكان هبوط الملفات وما يتم تسميتها به، وهو أمر مهم في اللحظة التي تحتفظ فيها بأكثر من تقرير واحد للتشغيل.
--out-dir <dir> تحدد الدليل الذي تُكتب إليه التقارير. الافتراضي هو ./apidog-reports. في CI، وجهه إلى مكان يمكن لخطوة الأثر أن تجده، واجعله متسقًا حتى لا تضطر أبدًا إلى تغيير تكوين التحميل الخاص بك:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r html,junit --out-dir ./apidog-reports
--out-file <name> يحدد اسم ملف التقرير، وهذا هو المكان الذي يصبح فيه مفيدًا. بدون ذلك، يميل كل تشغيل إلى الكتابة فوق السابق، لذلك تحتفظ دائمًا بالتقرير الأحدث فقط. تقبل العلامة عناصر نائبة يملأها المشغل وقت الكتابة:
- يصبح
{SCENARIO_NAME}اسم السيناريو الذي تم تشغيله. - يصبح
{FOLDER_NAME}اسم المجلد عند تشغيل مجلد من السيناريوهات. - يصبح
{GENERATE_TIME}طابعًا زمنيًا.
اطبع اسم ملف باسم السيناريو وطابعًا زمنيًا، ويكتب كل تشغيل ملفًا مميزًا وواصفًا ذاتيًا بدلاً من طمس الملف السابق:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r html --out-file "{SCENARIO_NAME}-{GENERATE_TIME}"
الآن، يقرأ دليل تقاريرك كالتاريخ. يمكنك معرفة أي تقرير جاء من أي سيناريو ومتى تم تشغيله دون فتح ملف واحد، وهو بالضبط ما تريده عندما تقوم بمسح مجلد من عمليات التشغيل الليلية للعثور على العملية التي حدث فيها الخطأ أولاً.
علامة تقرير أخرى تكمل جانب السحابة. --upload-report [value] يقوم بتحميل نظرة عامة على التقرير إلى سحابة Apidog، لذلك يظهر التشغيل أيضًا في سجل مشروعك جنبًا إلى جنب مع الملفات المحلية. إنه الخيار الذي يجب الوصول إليه عندما تريد أن تكون النتيجة مرئية داخل Apidog نفسه، وليس فقط كملف على مشغل CI.
استراتيجية المُبلِّغ حسب الجمهور
أنظف طريقة للقرار هي ربط كل مُبلِّغ بمن يقرأه، ثم تمرير المُبلِّغين الذين تحتاجهم معًا.
- الشخص الذي يقوم بمسح سجل الإنشاء الآن يقرأ
cli. يجب تضمينه دائمًا. - الشخص الذي يفتح تقريرًا محفوظًا لاحقًا يقرأ
html. ارشفه كقطعة أثرية. - لوحة تحكم CI تقرأ
junit. إنه ما يعرض الإخفاقات في طلب الدمج ويتتبع النتائج عبر البناءات. - النص البرمجي الذي كتبته يقرأ
json. إنه التنسيق الوحيد المخصص للتحليل بواسطة التعليمات البرمجية الخاصة بك.
بالنسبة لمعظم خطوط أنابيب التكامل المستمر (CI)، فإن التركيبة الفعالة هي HTML للبشر بالإضافة إلى JUnit للوحة المعلومات، مع إبقاء CLI قيد التشغيل ليبقى السجل الخام قابلاً للقراءة:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli,html,junit --out-dir ./apidog-reports
يُنتج هذا التشغيل الواحد سجلًا قابلاً للقراءة، وقطعة أثرية قابلة للتصفح، وملف XML قابل للتحليل. ثلاثة جماهير، تنفيذ واحد، لا تكرار.
تنبيه واحد يستحق الذكر بوضوح: التقرير يخبرك بما حدث، ولكن رمز الخروج هو ما يجعل خط الأنابيب يتصرف بناءً عليه. يخرج Apidog CLI برمز غير صفري عندما يفشل أي تأكيد، ورمز الخروج هذا، وليس التقرير، هو ما يفشل البناء ويعوق الدمج. يشرح التقرير الفشل؛ رمز الخروج يفرضه. لا تقم بتغليف الأمر بأي شيء يبتلع هذا الرمز، مثل إضافة || true في shell، وإلا ستحصل على تقرير أحمر مثالي مرفق ببناء ظل أخضر. النسخة الأعمق من منطق بوابة الجودة هذا موجودة في دليل أتمتة اختبارات API في CI/CD.
تجميعها
قم بتشغيل سيناريو في CI وأصدر جميع القطع الأثرية الثلاث المفيدة لثلاثة جماهير:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r cli,html,junit --out-dir ./apidog-reports
قم بتشغيل مسح مجلد ليلي، واجمع كل الأعطال في تقرير واحد، وأعطِ كل ملف اسمًا يصف نفسه:
apidog run --access-token $APIDOG_ACCESS_TOKEN -f 88012 -r html,junit --on-error continue --out-dir ./nightly-reports --out-file "{FOLDER_NAME}-{GENERATE_TIME}"
قم بتشغيل سيناريو يعتمد على البيانات واحتفظ بملف JSON للأعطال فقط للمقارنات السريعة:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -d ./accounts.csv -r json --out-json-failures-separated true --out-dir ./apidog-reports
إذا كنت تفضل عدم تثبيت CLI عالميًا على مشغل عابر، فاستبدل التثبيت بـ npx واحتفظ بنفس علامات المُبلِّغ:
npx apidog-cli run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r html,junit --out-dir ./apidog-reports
سلوك المُبلِّغ متطابق في كلتا الحالتين؛ الاختيار بين التثبيت العالمي و npx يتعلق بنظافة المشغل، وليس بنوع التقارير التي تحصل عليها.
يمكن أن تتغير أسماء العلامات، والافتراضات، والمُبلِّغون بين إصدارات CLI، لذا فإن المشغل هو دائمًا مصدر الحقيقة الخاص به. قم بتشغيل apidog run --help على الإصدار الذي قمت بتثبيته وثق بذلك أكثر من أي مقال، بما في ذلك هذا المقال. لإعداد السيناريو الذي يقوم CLI بتشغيله في المقام الأول، قم بتنزيل Apidog، ثم أنشئ سيناريو واحدًا في التطبيق، ثم انسخ الأمر الذي تم إنشاؤه من علامة تبويب CI/CD الخاصة به وأضف المُبلِّغين الذين تحتاجهم.