تصحيح إخفاقات خط الأنابيب

لماذا يهم

خط الأنابيب الأحمر يوقف كل دمج وكل إصدار خلفه، والتصنيف الخاطئ يكلّف أكثر من التصحيح البطيء. فوصف عيب في المنتج بأنه «متذبذب» يتركه يصل إلى المستخدمين، ووصف مشكلة بيئة بأنها عيب في المنتج يرسل المطورين للبحث عن عيب ليس في الشيفرة. وإعادة التشغيل حتى يخضرّ تفعل الأمرين معاً: تُخفي الأدلة وتعلّم الفريق أن الأحمر لا يعني شيئاً.

وبالنسبة إلى المختبِر، هنا تُكتسب الثقة. فالتقرير الذي يسمّي الاختبار الفاشل والخطأ الأول والمخرجات وأمراً لإعادة الإنتاج وأول إيداع معيب يُصلَح سريعاً؛ أما «خط الأنابيب أحمر، هل يمكن لأحد أن ينظر فيه؟» فلا.

ابدأ بالسجل والمخرجات

كما في درس «تقارير الأتمتة وتصحيح الأخطاء»، ابدأ من الخطأ الأول وأدلته؛ وفي خط الأنابيب يعني ذلك أن تحدّد أولاً أول مهمة فاشلة وأول خطوة فاشلة داخلها. ابحث في السجل عن اسم الاختبار أو عن علامة الخطأ (##[error] في السجل الخام لـGitHub Actions) بدلاً من التمرير، وتذكّر أن الطوابع الزمنية في المشغّلات تكون عادةً بتوقيت UTC.

ثم نزّل مخرجات المهمة (artifacts) قبل انتهاء فترة الاحتفاظ بها، مثل تقرير JUnit XML وتتبّع Playwright (trace) وسجلات التطبيق، واقرأها كما بيّن ذلك الدرس. وقارنها بآخر تشغيل أخضر للمهمة: صورة مشغّل جديدة، أو اعتمادية متغيرة، أو عدد أقل من الاختبارات المنفّذة، كلها أدلة قبل أن تقرأ سطراً من الشيفرة.

# GitHub CLI: logs of the failed steps only, then the artifacts of one job
gh run view 9876543 --log-failed
gh run download 9876543 -n e2e-results-3

# open the trace recorded for the failing test
npx playwright show-trace test-results/invoice-order-date/trace.zip

جرّبها: منسّق XML جرّبها: مقارنة النصوص (Diff)

أعد إنتاج الإخفاق محلياً

الإخفاق الذي تستطيع إعادة إنتاجه على جهازك يمكن فحصه بمصحّح الأخطاء (debugger) وسجلات إضافية وبعدد التشغيلات الذي تحتاجه. وإعادة الإنتاج مسألة تطابق: طابِق مهمة CI في كل ما قد يغيّر النتيجة، ثم غيّر شيئاً واحداً في كل مرة. وإذا بقي الاختبار ناجحاً محلياً، فالفرق المتبقي هو أفضل دليل لديك.

• الإيداع: رمز SHA الدقيق من سجل المهمة. فتشغيل طلب الدمج في GitHub Actions يختبر دمجاً مؤقتاً في الفرع الهدف، لا آخر إيداع في فرعك؛ وهذا الإيداع لا ينتمي إلى أي فرع، فاجلبه بالأمر git fetch origin pull/<number>/merge وتأكد أن رمز SHA يطابق السجل.
• الصورة والإصدارات: صورة الحاوية (container image) التي تستخدمها المهمة إن وُجدت، والاعتماديات من ملف القفل (npm ci لا npm install)، وإصدارات المتصفحات التي يثبّتها إصدار Playwright لديك.
• متغيرات البيئة: القيم غير السرية التي تضبطها المهمة، ومنها CI=true الذي تقرؤه إعدادات اختبار كثيرة؛ وبيانات اعتماد اختبار خاصة بك، لا أسرار بيئة الإنتاج أبداً.
• المنطقة الزمنية واللغة والبذرة: تعمل المشغّلات غالباً بتوقيت UTC وبلغة إنجليزية، والاختبارات التي تولّد بيانات عشوائية يجب أن تطبع بذرتها (seed) ليمكن تكرار البيانات نفسها.
• المجموعة والترتيب: الجزء (shard) نفسه وعدد العمّال (workers) نفسه، ثم الاختبار الفاشل وحده ومكرراً، لتميّز «يفشل وحده» من «يفشل فقط بجوار اختبارات أخرى».

git checkout 9f8e7d6                     # the SHA the job tested
npm ci && npx playwright install --with-deps chromium
export CI=true TEST_SEED=48151           # non-secret values copied from the job
npx playwright test --shard=3/4 --workers=2
npx playwright test invoice.spec.ts --repeat-each=10

المهلات والإيقاف عند أول إخفاق وإعادة التشغيل

انتهاء المهلة (timeout) يعني أن شيئاً كان الاختبار ينتظره لم يحدث: عنصر، أو استجابة، أو خدمة. ونادراً ما يُصلحه رفع الحد؛ فسجل الاستدعاءات أو التتبّع يبيّن ما الذي كان منتظراً. ورتّب الحدود في طبقات: مهلة الاختبار (⁦30⁩ ثانية افتراضياً في Playwright) تُفشل اختباراً واحداً مسمّى ويُكتب التقرير مع ذلك، أما مهلة المهمة (timeout-minutes في GitHub Actions، و⁦360⁩ دقيقة إن لم تُضبط) فتلغي المهمة كلها وقد لا تترك تقريراً. لذا اجعل مهلات الاختبارات أقل بكثير من مهلة المهمة.

الإيقاف عند أول إخفاق (fail-fast) يتوقف عند الإخفاق الأول (في Playwright بالخيار -x، وهو اختصار --max-failures=1)، وتشغيل الكل (run-all) يجمع كل الإخفاقات. استخدم الأول في المراحل المبكرة الرخيصة مثل التدقيق الساكن (linting) واختبارات الوحدة. أما في المراحل المكلفة والتشغيلات الليلية فشغّل كل شيء: فاختبار واحد فاشل وأربعون اختباراً فاشلاً يرويان قصتين مختلفتين، والأربعون تشير عادةً إلى سبب مشترك كالبيئة. والمصفوفة (matrix) في GitHub Actions تلغي مهامها الأخرى عند فشل إحداها ما لم تضبط fail-fast: false.

أعد التشغيل بأضيق نطاق ممكن: المهام الفاشلة فقط (gh run rerun <run-id> --failed، ومعرّف التشغيل هو الرقم الطويل في رابط التشغيل لا رقمه المسبوق بـ#) أو الاختبار الفاشل فقط. وإعادة التشغيل في GitHub Actions تستخدم الإيداع نفسه، فالنجاح عندها يثبت اللاحتمية (non-determinism) لا الإصلاح؛ فسجّله دليلاً.

وخلاصة إعادة المحاولة والحجر: إعادة المحاولة الآلية (retry) تجعل التشغيل أخضر حين ينجح اختبار متذبذب في محاولة لاحقة، والحجر (quarantine) ينقل اختباراً معروف التذبذب إلى مهمة لا تمنع الدمج يستمر فيها بالعمل. وكلاهما احتواء لا علاج: اسمح بإعادة محاولة واحدة على الأكثر، وأبلغ عن «نجح عند إعادة المحاولة» على أنه تذبذب، وأعطِ كل اختبار محجور مالكاً وتذكرة وموعداً نهائياً. ويشرح دليل الاختبارات المتذبذبة هذه السياسة، ويبيّن مسار الفرز في دليل الاختبار في خطوط CI/CD موضع إعادة التشغيل.

jobs:
  e2e:
    runs-on: ubuntu-latest
    timeout-minutes: 30      # job limit: cuts off a hang
    strategy:
      fail-fast: false       # one failing shard does not cancel the others
      matrix:
        shard: [1, 2, 3, 4]
    steps:
      # checkout and install steps omitted
      - run: npx playwright test --shard=${{ matrix.shard }}/4

جرّبها: منسّق YAML

تنصيف الانحدار عبر تشغيلات خط الأنابيب

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

ويؤتمت git bisect run هذا البحث: ينتهي الأمر الذي تعطيه إياه بالرمز ⁦0⁩ للإيداع السليم، و⁦125⁩ لتخطّي إيداع لا يمكن اختباره، وبرمز آخر من ⁦1⁩ إلى ⁦127⁩ للإيداع المعيب. ولا تثق بالنتيجة إلا بشرطين: أن يفشل الاختبار في كل مرة على الإيداع المعيب، لذا كرّره في كل خطوة، وأن تبقى البيئة ثابتة. فإن فشل آخر إيداع أخضر الآن أيضاً، فالسبب خارج الشيفرة، كصورة المشغّل أو خدمة خارجية أو بيانات اختبار منتهية الصلاحية.

# last green nightly: a1b2c3d     first red nightly: 9f8e7d6
git bisect start 9f8e7d6 a1b2c3d
# TZ=UTC gives the browser the runner's time zone (Linux and macOS)
git bisect run sh -c 'npm ci || exit 125
  TZ=UTC npx playwright test -g "order date" --repeat-each=3'
# git prints "<sha> is the first bad commit"
git bisect reset

مثال تطبيقي: تشغيل ليلي أحمر

التشغيل الليلي ⁦412⁩ على الفرع الرئيسي أحمر، والتشغيل ⁦411⁩ كان أخضر، وبينهما تسعة إيداعات. الإيقاف عند أول إخفاق معطّل، فاكتملت الأجزاء الأربعة، وفي الجزء ⁦3⁩ إخفاق واحد في invoice.spec.ts، في الاختبار «invoice shows the order date»: المتوقع 1 Oct 2026 والمستلم 30 Sep 2026. وقد فشل في محاولته الأولى وفي إعادة المحاولة، فيعدّه التقرير فاشلاً لا متذبذباً. ويُظهر التتبّع أن الواجهة البرمجية أعادت createdAt بالقيمة 2026-09-30T22:40:00Z، أي الساعة ⁦01:40⁩ يوم ⁦1⁩ أكتوبر في الرياض، وهي المنطقة الزمنية للمتجر: البيانات صحيحة والعرض خاطئ.

وعلى حاسوب المختبِر في الرياض ينجح الاختبار. ومع الإيداع وملف القفل وإصدار المتصفح والبذرة نفسها التي استخدمتها المهمة، يبقى فرق واحد: متصفح المشغّل يعمل بتوقيت UTC. وعند ضبط خيار timezoneId في Playwright على UTC يفشل الاختبار ⁦10⁩ مرات من ⁦10⁩. ومع إضافة TZ=UTC إلى أمر التنصيف ليعمل كل إيداع بالمنطقة الزمنية للمشغّل، يحدد git bisect run الإيداعَ c41d9a0 بعنوان «Format dates with Intl.DateTimeFormat»، الذي حذف المنطقة الزمنية للمتجر. فيسجّل المختبِر عيباً في المنتج مع رابط التشغيل والاختبار والتتبّع وإعداد إعادة الإنتاج وأول إيداع معيب، ويقترح تثبيت timezoneId في إعدادات الاختبار ليتصرف التشغيل المحلي مثل CI.

جرّبها: محوّل المناطق الزمنية

أسئلة شائعة

المراجع

• ISTQB Certified Tester Foundation Level (CTFL) v4.0ISTQB · 2023المنهج التأسيسي لاختبار البرمجيات: مستويات الاختبار وأنواعه وتقنيات تصميم الاختبارات وإدارة الاختبار والأدوات.
• GitHub Actions documentationGitHubكيف تُعرَّف مسارات العمل والمهام والمشغّلات والمخرجات في GitHub Actions — حيث تعمل الاختبارات الآلية عند كل دفع أو طلب دمج.
• Reference — GitGit projectالمرجع الرسمي لكل أوامر Git وخياراتها، مجمّعةً حسب المهمة — الإعداد والتفريع والمشاركة وتطبيق الرقع والفحص وتتبّع الأخطاء.
• Playwright DocumentationMicrosoft (Playwright)التوثيق الرسمي لـ Playwright، إطار الاختبار الشامل الذي يشغّل Chromium وWebKit وFirefox.