كل فريق يضيف اختبارات يسأل في النهاية “كم يكفي؟”، والـ coverage هي الرقم الذي يبدو أنه يجيب. لكنها تجيب عن سؤال أضيق مما يظنّه الناس. إن استُخدمت جيدًا، فهي طريقة سريعة لإيجاد كود لم يختبره أحد. وإن استُخدمت كدرجة تقييم، فهي تكافئ الاختبارات الخاطئة.
\nتدعم Vitest مزوّدَين للـ coverage. الافتراضي، v8، يستخدم التغطية المدمجة في محرّك JavaScript ولا يحتاج إلى خطوة تجهيز للكود (instrumentation)؛ أما istanbul فيجهّز الكود ويعمل في بيئات تشغيل أكثر. ثبّت المزوّد وشغّل مع --coverage:
npm install --save-dev @vitest/coverage-v8\nnpx vitest run --coverageاضبط ما تقيسه وطريقة الإبلاغ عنه:
\n/// <reference types=\"vitest/config\" />\nimport { defineConfig } from 'vite';\n\nexport default defineConfig({\n test: {\n coverage: {\n provider: 'v8',\n include: ['src/**/*.{js,jsx}'],\n exclude: ['src/**/*.test.{js,jsx}', 'src/main.jsx'],\n reporter: ['text', 'html'],\n thresholds: { lines: 80, branches: 75 },\n },\n },\n});include مهم: في Vitest 4، بدونه لا يسرد التقرير إلا الملفات التي صادف أن حمّلتها اختباراتك، فلا تظهر الوحدة غير المختبَرة كليًا أصلًا، وتبدو النسبة أفضل مما هي. ومع include، تظهر الملفات غير المختبَرة بنسبة 0%. ويكتب مُبلّغ html الملف coverage/index.html، الذي تفتحه في المتصفّح.
if/else، و? :، و&&، و||، و??، والمعاملات الافتراضية).تغطية الفروع هي ما أنظر إليه. const share = people > 0 ? total / people : 0; سطر واحد وفرعان. اختبار بثلاثة أشخاص يجعل السطر مغطّى بنسبة 100% والفروع بنسبة 50%، والفرع غير المختبَر هو بالضبط الحالة الحدّية من القسم 2.
يعلّم تقرير HTML الأسطر التي لم تعمل قط بالأحمر، والفروع التي سُلكت في اتجاه واحد فقط بالأصفر. وهذا هو الجزء الثمين: الكود الأحمر غير مختبَر، بكل تأكيد. لا يمكن لأي assertion في أي مكان أن يكون قد فحصه، لأنه لم يعمل قط. حين أنضمّ إلى مشروع، يكون تقرير الـ coverage أسرع خريطة لأماكن الخطر: معالجة الأخطاء غير المغطّاة في وحدة الدفع، وفرع else الذي لم يصل إليه أحد.
تسجّل الـ coverage التنفيذ. ولا تعرف شيئًا عمّا إذا كان أي شيء قد فحص النتيجة. هذا الاختبار يجعل computeBalances مغطّاة بنسبة 100%:
test('computes balances', () => {\n const balances = computeBalances([\n { paidBy: 'Ana', amountCents: 3000, splitAmong: ['Ana', 'Ben', 'Cai'] },\n ]);\n expect(Object.keys(balances)).toHaveLength(3);\n});عمل كل سطر. وسينجح الـ assertion حتى لو خُصم المبلغ من الدافع بدل أن يُضاف إليه، أو أُخذ الجزء الصحيح من الحصص فاختفى سنت، أو استبدل مصروف ثانٍ الأول. الـ coverage: 100%. الثقة: قريبة من الصفر. ويبدأ التمرين من هذا الاختبار بالضبط.
\n\nالسطر غير المغطّى سؤال، لا أمر. أحيانًا تكون الإجابة الصحيحة اختبارًا. وأحيانًا تكون حذف الكود: فرع لا يستطيع أحد الوصول إليه، أو بديل احتياطي لمتصفّح توقّفت عن دعمه، أو دالة مساعدة لم يعد شيء يستدعيها. والكود الميت “المغطّى” باختبار كُتب فقط لرفع الرقم هو أسوأ النتائج، لأنه يبدو الآن مهمًّا.
\nلا يوجد رقم عالمي. لكن هذه قواعد تقريبية مفيدة:
\nتخبرك الـ coverage أين تنقص الاختبارات. ولتعرف إن كانت الاختبارات الموجودة جيدة أصلًا، تحتاج إلى أداة مختلفة، وهي موضوع الدرس القادم. لكن أولًا، في التمرين، حوّل مجموعة تغطيتها 100% ولا تلتقط شيئًا إلى مجموعة تلتقط أخطاءً حقيقية.
\n","toc":[{"id":"sec-1","text":"تشغيلها","level":2},{"id":"sec-2","text":"الأرقام الأربعة","level":2},{"id":"sec-3","text":"قراءة التقرير","level":2},{"id":"sec-4","text":"ما لا تستطيع الـ coverage رؤيته","level":2},{"id":"sec-5","text":"كم يكفي؟","level":2}],"takeaways":["تقيس الـ coverage أيّ العبارات والفروع والدوال والأسطر عملت أثناء الاختبارات، لا إن كان شيء قد فحص النتائج.","أنفع ما في تقرير الـ coverage هو الأحمر والأصفر اللذان يُظهرهما لك؛ فالكود غير المغطّى كود غير مختبَر بكل تأكيد.","تغطية الفروع (branch coverage) أكثر صرامة وأنفع من تغطية الأسطر، لأن السطر الواحد قد يحمل عدة قرارات.","استخدم الحدود الدنيا (thresholds) كأرضية تمنع التغطية من الانزلاق، لا كهدف تسعى إليه؛ فالرقم الذي يصبح هدفًا يُتلاعب به."],"further":[{"title":"Vitest — Coverage guide","url":"https://vitest.dev/guide/coverage"},{"title":"Vitest — Coverage config","url":"https://vitest.dev/config/coverage"}],"quiz":[{"q":"يستدعي اختبار computeBalances(expenses) ولا يؤكّد إلا expect(result).toBeDefined(). الـ coverage للملف 100%. ماذا يخبرك ذلك؟
تغطية الأسطر 100% لكن تغطية الفروع 50% للسطر const share = people > 0 ? total / people : 0;. ما الناقص؟
people مساوية 0 (أو سالبة)، كي تعمل الجهة الأخرى من الشرط.","why":"صحيح. عمل السطر، لكن فرعًا واحدًا فقط من فرعيه عمل؛ تغطية الفروع تلاحظ ذلك، وتغطية الأسطر لا تستطيع."},{"text":"اختبار ثانٍ بقيمة total أكبر.","why":"المجموع المختلف يسلك الفرع نفسه، فتبقى تغطية الفروع عند 50%."},{"text":"لا شيء؛ تغطية الفروع دائمًا أقل من تغطية الأسطر.","why":"كثيرًا ما تكون أقل، لكنها هنا تشير إلى قرار محدّد غير مختبَر."}],"answer":0},{"q":"يضع فريقك حدًّا أدنى صارمًا للـ coverage قدره 90% ويجعله هدفًا ربع سنوي. ما الأثر الجانبي الأرجح؟
","options":[{"text":"أخطاء أقل، لأن 90% من الكود صار مُتحقَّقًا منه الآن.","why":"الـ coverage تعدّ التنفيذ لا التحقّق، فقد يرتفع الرقم دون أن تقلّ الأخطاء."},{"text":"CI أبطأ، لأن جمع الـ coverage مكلف.","why":"هناك عبء إضافي، لكنه ليس الخطر الأساسي في تحويل الرقم إلى هدف."},{"text":"يكتب الناس اختبارات تنفّذ الكود دون assertions ذات معنى، فيرتفع الرقم ولا ترتفع الثقة.","why":"صحيح. بمجرد أن يصبح المقياس هدفًا، يُحسَّن مباشرة؛ استخدم الحدود الدنيا كأرضية، واقرأ التقرير بحثًا عن الفجوات بدلًا من ذلك."}],"answer":2}],"exercise":{"kind":"web","mode":"test","subject":"function splitEvenly(totalCents, people) {\n if (!Number.isInteger(people) || people < 1) {\n throw new RangeError('people must be a positive integer');\n }\n const base = Math.floor(totalCents / people);\n const remainder = totalCents % people;\n return Array.from({ length: people }, (_, i) => (i < remainder ? base + 1 : base));\n}\n\n// Computes each person's balance in cents from a list of expenses.\n// Positive: the group owes them. Negative: they owe the group.\n// Each expense is { paidBy, amountCents, splitAmong: [names] }.\n// - The payer is credited the full amount.\n// - Each person in splitAmong is debited their share from splitEvenly\n// (leftover cents go to the first names in the list).\n// - Balances accumulate across expenses and always add up to zero.\nfunction computeBalances(expenses) {\n const balances = {};\n for (const { paidBy, amountCents, splitAmong } of expenses) {\n const shares = splitEvenly(amountCents, splitAmong.length);\n balances[paidBy] = (balances[paidBy] ?? 0) + amountCents;\n splitAmong.forEach((name, i) => {\n balances[name] = (balances[name] ?? 0) - shares[i];\n });\n }\n return balances;\n}\n","mutants":[{"id":"payer-debited","code":"function splitEvenly(totalCents, people) {\n if (!Number.isInteger(people) || people < 1) {\n throw new RangeError('people must be a positive integer');\n }\n const base = Math.floor(totalCents / people);\n const remainder = totalCents % people;\n return Array.from({ length: people }, (_, i) => (i < remainder ? base + 1 : base));\n}\n\n// Computes each person's balance in cents from a list of expenses.\n// Positive: the group owes them. Negative: they owe the group.\n// Each expense is { paidBy, amountCents, splitAmong: [names] }.\n// - The payer is credited the full amount.\n// - Each person in splitAmong is debited their share from splitEvenly\n// (leftover cents go to the first names in the list).\n// - Balances accumulate across expenses and always add up to zero.\nfunction computeBalances(expenses) {\n const balances = {};\n for (const { paidBy, amountCents, splitAmong } of expenses) {\n const shares = splitEvenly(amountCents, splitAmong.length);\n balances[paidBy] = (balances[paidBy] ?? 0) - amountCents;\n splitAmong.forEach((name, i) => {\n balances[name] = (balances[name] ?? 0) - shares[i];\n });\n }\n return balances;\n}\n"},{"id":"floored-shares","code":"function splitEvenly(totalCents, people) {\n if (!Number.isInteger(people) || people < 1) {\n throw new RangeError('people must be a positive integer');\n }\n const base = Math.floor(totalCents / people);\n const remainder = totalCents % people;\n return Array.from({ length: people }, (_, i) => (i < remainder ? base + 1 : base));\n}\n\n// Computes each person's balance in cents from a list of expenses.\n// Positive: the group owes them. Negative: they owe the group.\n// Each expense is { paidBy, amountCents, splitAmong: [names] }.\n// - The payer is credited the full amount.\n// - Each person in splitAmong is debited their share from splitEvenly\n// (leftover cents go to the first names in the list).\n// - Balances accumulate across expenses and always add up to zero.\nfunction computeBalances(expenses) {\n const balances = {};\n for (const { paidBy, amountCents, splitAmong } of expenses) {\n const shares = splitEvenly(amountCents, splitAmong.length);\n balances[paidBy] = (balances[paidBy] ?? 0) + amountCents;\n splitAmong.forEach((name, i) => {\n balances[name] = (balances[name] ?? 0) - Math.floor(amountCents / splitAmong.length);\n });\n }\n return balances;\n}\n"},{"id":"overwrites-payer","code":"function splitEvenly(totalCents, people) {\n if (!Number.isInteger(people) || people < 1) {\n throw new RangeError('people must be a positive integer');\n }\n const base = Math.floor(totalCents / people);\n const remainder = totalCents % people;\n return Array.from({ length: people }, (_, i) => (i < remainder ? base + 1 : base));\n}\n\n// Computes each person's balance in cents from a list of expenses.\n// Positive: the group owes them. Negative: they owe the group.\n// Each expense is { paidBy, amountCents, splitAmong: [names] }.\n// - The payer is credited the full amount.\n// - Each person in splitAmong is debited their share from splitEvenly\n// (leftover cents go to the first names in the list).\n// - Balances accumulate across expenses and always add up to zero.\nfunction computeBalances(expenses) {\n const balances = {};\n for (const { paidBy, amountCents, splitAmong } of expenses) {\n const shares = splitEvenly(amountCents, splitAmong.length);\n balances[paidBy] = amountCents;\n splitAmong.forEach((name, i) => {\n balances[name] = (balances[name] ?? 0) - shares[i];\n });\n }\n return balances;\n}\n"}],"starter":{"js":"// This suite gives computeBalances 100% line coverage.\n// It also catches almost nothing. Strengthen it.\ndescribe('computeBalances', () => {\n test('computes balances', () => {\n const balances = computeBalances([\n { paidBy: 'Ana', amountCents: 3000, splitAmong: ['Ana', 'Ben', 'Cai'] },\n ]);\n\n expect(Object.keys(balances)).toHaveLength(3);\n });\n});\n"},"solution":{"js":"const sum = (balances) => Object.values(balances).reduce((a, b) => a + b, 0);\n\ndescribe('computeBalances', () => {\n test('credits the payer and debits everyone their share', () => {\n const balances = computeBalances([\n { paidBy: 'Ana', amountCents: 3000, splitAmong: ['Ana', 'Ben', 'Cai'] },\n ]);\n\n expect(balances).toEqual({ Ana: 2000, Ben: -1000, Cai: -1000 });\n });\n\n test('balances add up to zero when the bill does not divide evenly', () => {\n const balances = computeBalances([\n { paidBy: 'Ana', amountCents: 1000, splitAmong: ['Ana', 'Ben', 'Cai'] },\n ]);\n\n expect(balances).toEqual({ Ana: 666, Ben: -333, Cai: -333 });\n expect(sum(balances)).toBe(0);\n });\n\n test('accumulates several expenses paid by the same person', () => {\n const balances = computeBalances([\n { paidBy: 'Ana', amountCents: 2000, splitAmong: ['Ana', 'Ben'] },\n { paidBy: 'Ana', amountCents: 1000, splitAmong: ['Ana', 'Ben'] },\n ]);\n\n expect(balances).toEqual({ Ana: 1500, Ben: -1500 });\n });\n});\n"},"checks":[{"id":"passes","suite":"subject"},{"id":"catches-payer-debited","suite":"payer-debited"},{"id":"catches-floored-shares","suite":"floored-shares"},{"id":"catches-overwrites-payer","suite":"overwrites-payer"}],"title":"من تغطية 100% إلى ثقة حقيقية","prompt":"يشغّل الاختبار المبدئي كل سطر في computeBalances (وsplitEvenly)، فسيُظهر تقرير الـ coverage نسبة 100%. ومع ذلك لا يفحص إلا أن ثلاثة أسماء عادت.
قوِّ المجموعة حتى تلتقط ثلاثة أخطاء مخفيّة تفوت مجموعة الـ 100%: نسخة تخصم من الدافع بدل أن تضيف إليه، ونسخة تأخذ الجزء الصحيح من كل حصة فتختفي السنتات المتبقّية (فلا يعود مجموع الأرصدة صفرًا)، ونسخة تستبدل رصيد الدافع بدل أن تضيف إليه حين يدفع مرتين. القواعد مذكورة في تعليق الـ subject.
\n","hints":["استبدل الـ assertion الذي يعدّ المفاتيح بالنتيجة الدقيقة: Ana تدفع 3000 مقسّمة على ثلاثة، إذن{ Ana: 2000, Ben: -1000, Cai: -1000 }.","استخدم فاتورة لا تنقسم بالتساوي، مثل 1000 على ثلاثة أشخاص، وأكّد أن مجموع الأرصدة يساوي 0.","أعطِ الدافع نفسه مصروفين وتحقّق من أن كليهما محسوب."],"explanation":"ظلّت الـ coverage عند 100% طوال الوقت: لم تشغّل اختباراتك الجديدة أي سطر لم يشغّله الاختبار القديم. ما تغيّر هو ما تفحصه الاختبارات. يلتقط toEqual الدقيق على المصروف الأول خطأ الإشارة. وفاتورة من 1000 سنت على ثلاثة أشخاص تترك سنتًا زائدًا، فتجعل الحصص المأخوذ جزؤها الصحيح مجموع الأرصدة +1 بدل 0؛ وثابت المجموع من القسم 2 يلتقط ذلك. ومصروفان من الدافع نفسه يشغّلان التراكم، وهو ما لا يستطيعه مصروف واحد أبدًا، مع أن سطر التراكم كان ‘مغطّى’ أصلًا. هذه هي الفجوة بين التنفيذ والتحقّق، وهي ما يقيسه الـ mutation testing مباشرة.