{"id":"l-tj-2-1","courseId":"testing-javascript","lang":"ar","kind":"lesson","summary":"تكتب اختبارات تثبّت عقد الدالة (المدخلات والمخرجات والثوابت) كي تصمد أمام إعادة الهيكلة ولا تفشل إلا حين يتغيّر السلوك فعلًا.","html":"

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

\n

السلوك مقابل التفاصيل الداخلية

\n

إليك splitEvenly في Splitwise-lite، التي تقسّم فاتورة بالسنتات بين الأشخاص. تذهب السنتات المتبقّية إلى أوائل الأشخاص في القائمة، فتكون النتيجة عادلة (لا تختلف الحصص بأكثر من سنت واحد) وحتمية:

\n
JavaScript
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\nconsole.log(splitEvenly(1000, 3)); // $10.00 three ways\nconsole.log(splitEvenly(1001, 4));\nconsole.log(splitEvenly(2, 3));
\n

سلوكها هو كل ما يستطيع المستدعي ملاحظته: المصفوفة التي تعيدها، والخطأ الذي ترميه حين يكون عدد الأشخاص صفرًا. أما تفاصيلها الداخلية فهي الطريقة: Math.floor، والعامل %، وArray.from، وأسماء المتغيّرات. تستطيع إعادة كتابة جسم الدالة بحلقة، أو بتوزيع السنتات واحدًا تلو الآخر، دون أن يلاحظ أيّ مستدعٍ شيئًا.

\n

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

\n
\n ترسل الاختبارات مدخلات إلى splitEvenly وتفحص المخرجات؛ والدوال المساعدة الداخلية داخل المربّع المتقطّع لا تلمسها الاختبارات.\n \n الاختبارات\n مدخلات، مخرجات\n \n \n \n splitEvenly(total, people)\n \n الداخل: floor و% وArray.from\n حرّ في التغيّر\n
الاختبارات تخاطب العقد العام، لا الأجزاء الداخلية
\n

كيف تبدو الاختبارات المرتبطة بالتفاصيل الداخلية

\n

هذه أنماط حقيقية حذفتها بنفسي من قواعد كود:

\n
JavaScript
// Spying on Math.floor: breaks if you switch to integer division another way\nconst floor = vi.spyOn(Math, 'floor');\nsplitEvenly(1000, 3);\nexpect(floor).toHaveBeenCalledWith(1000 / 3);\n\n// Testing an exported private helper: breaks when you inline or rename it\nexpect(_remainderFor(1000, 3)).toBe(1);\n\n// Snapshotting the source-shaped output of a debug helper nobody calls\nexpect(describeSplit(1000, 3)).toMatchSnapshot();
\n

كل واحد منها ينجح اليوم ولا يخبرك بشيء لا يخبرك به اختبار السلوك. وكل واحد منها سيفشل في اليوم الذي يحسّن فيه أحدهم الكود.

\n

اختبار العقد بدلًا من ذلك

\n

ابدأ مما يعتمد عليه المستدعي. بالنسبة إلى splitEvenly فهو:

\n
    \n
  1. حصة واحدة لكل شخص.
    2. \n
  2. مجموع الحصص يساوي الإجمالي. لا يضيع سنت، ولا يُختلَق سنت.
    3. \n
  3. لا تختلف الحصص بأكثر من سنت واحد.
    4. \n
  4. تذهب السنتات الإضافية إلى أوائل الأشخاص (وهذا موثّق، فقد يعتمد عليه المستدعون).
    5. \n
  5. عدد الأشخاص صفر خطأ.
    6. \n
\n

النقطتان 2 و3 ثوابت (invariants): تصحّ مع كل مدخل صالح، لذا تستطيع فحصها على عدة مدخلات دفعة واحدة:

\n
src/split.test.js
import { describe, test, expect } from 'vitest';\nimport { splitEvenly } from './split.js';\n\nconst sum = (xs) => xs.reduce((a, b) => a + b, 0);\n\ndescribe('splitEvenly', () => {\n  test('never loses or invents a cent', () => {\n    for (const [total, people] of [[1000, 3], [1001, 4], [2, 3], [0, 5]]) {\n      expect(sum(splitEvenly(total, people))).toBe(total);\n    }\n  });\n\n  test('gives the leftover cents to the first people', () => {\n    expect(splitEvenly(1001, 4)).toEqual([251, 250, 250, 250]);\n  });\n\n  test('refuses to split between zero people', () => {\n    expect(() => splitEvenly(1000, 0)).toThrow(RangeError);\n  });\n});
\n

ثابت المجموع هو أثمن سطر في الملف. النسخة التي تُسقط الباقي تفشل فيه. وكذلك الخطأ بفارق واحد (off-by-one) الذي يوزّع سنتًا زائدًا. لا يهمّه كيف تُحسب الحصص، بل يهمّه فقط أن المال محفوظ.

\n\n

ما مدى الدقّة المطلوبة في الـ assertions؟

\n

يمكن لاختبارات السلوك أن تبقى دقيقة. toEqual([251, 250, 250, 250]) يثبّت الترتيب الموثّق للسنتات الإضافية، وهذا سلوك لأن المستدعين يعتمدون عليه. السؤال ليس أبدًا “دقيق أم مرن؟” بل “هل سيلاحظ مستخدم أو مستدعٍ لو تغيّر هذا؟” إن كانت الإجابة نعم، فأكّده بدقّة. وإن كانت لا، فلا تؤكّده أصلًا.

\n

حين تكسر إعادة الهيكلة اختبارًا فعلًا

\n

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

\n

في التمرين، اكتب اختبارات سلوك لـ splitEvenly تلتقط أربعة أخطاء واقعية. والدرس القادم عن إيجاد المدخلات التي تكشف أخطاءً كهذه.

\n","toc":[{"id":"sec-1","text":"السلوك مقابل التفاصيل الداخلية","level":2},{"id":"sec-2","text":"كيف تبدو الاختبارات المرتبطة بالتفاصيل الداخلية","level":2},{"id":"sec-3","text":"اختبار العقد بدلًا من ذلك","level":2},{"id":"sec-4","text":"ما مدى الدقّة المطلوبة في الـ assertions؟","level":2},{"id":"sec-5","text":"حين تكسر إعادة الهيكلة اختبارًا فعلًا","level":2}],"takeaways":["السلوك هو ما يستطيع المستدعي ملاحظته (القيم المعادة، والأخطاء المرمية، والآثار الجانبية الظاهرة)؛ أما التفاصيل الداخلية (implementation) فهي الطريقة التي يصل بها الكود إلى ذلك.","الاختبار الذي ينكسر حين تعيد الهيكلة دون تغيير السلوك إنذار كاذب، والإنذارات الكاذبة تعلّم الفريق تجاهل البناء الأحمر.","الثوابت (invariants) مثل “مجموع الحصص يساوي الإجمالي” تلتقط عائلات كاملة من الأخطاء بـ assertion واحد.","لا تصدّر الدوال المساعدة الخاصة لمجرّد اختبارها؛ اختبرها من خلال الدالة العامة التي تستخدمها."],"further":[{"title":"Testing Library — Guiding principles","url":"https://testing-library.com/docs/guiding-principles"},{"title":"Vitest — expect API","url":"https://vitest.dev/api/expect"}],"quiz":[{"q":"

تعيد كتابة splitEvenly من Array.from إلى حلقة for عادية. مخرجاتها متطابقة مع كل مدخل. فيتحوّل اختباران إلى الأحمر. ماذا يخبرك ذلك عن هذين الاختبارين؟

","options":[{"text":"كانا يختبران التفاصيل الداخلية لا السلوك.","why":"صحيح. إن لم يتغيّر السلوك وفشلت الاختبارات، فالاختبارات كانت مرتبطة بطريقة عمل الكود، وهذا يجعل كل إعادة هيكلة مكلفة."},{"text":"أدخلت إعادة الهيكلة خطأً فاتَ بقية الاختبارات.","why":"الفرضية أن المخرجات متطابقة مع كل مدخل؛ والاختبار الذي يفشل رغم ذلك يبلّغ عن البنية، لا عن خطأ."},{"text":"الاختباران صحيحان ويجب التراجع عن الحلقة.","why":"التراجع عن إعادة هيكلة غير ضارّة إرضاءً لاختبار قلبٌ للأولويات، فالاختبار يخدم الكود لا العكس؛ أصلح الاختبارين كي يفحصا المخرجات بدلًا من ذلك."}],"answer":0},{"q":"

أيّ assertion واحد سيلتقط أكبر عدد من الأخطاء المختلفة في splitEvenly(totalCents, people)؟

","options":[{"text":"expect(shares).toHaveLength(people)","why":"مفيد، لكن النسخة التي تضيّع السنتات المتبقّية ما زالت تعيد العدد الصحيح من الحصص."},{"text":"expect(Math.max(...shares) - Math.min(...shares)).toBeLessThanOrEqual(1)","why":"يلتقط التقسيم غير العادل، لكن النسخة التي تُسقط الباقي تعطي الجميع الحصة نفسها فتنجح فيه."},{"text":"expect(shares.reduce((a, b) => a + b, 0)).toBe(totalCents)","why":"صحيح. ضياع سنت، واختلاق سنت، وسوء التعامل مع الباقي، كلها تكسر المجموع. هذا هو الثابت الذي لا يجوز لكود المال أن ينتهكه أبدًا."}],"answer":2},{"q":"

يصدّر زميلك _remainderFor(total, people) من split.js كي يختبرها كـ unit test مباشرة. ما الطريقة الأفضل؟

","options":[{"text":"أبقِ التصدير لكن ضع قبل الاسم شرطة سفلية كي يعرف الناس أنها خاصة.","why":"الشرطة السفلية لا تمنع الاستيراد؛ صارت الدالة المساعدة الآن جزءًا من الـ API العام سترتبط به الاختبارات (وأكواد أخرى)."},{"text":"اختبر سلوك الباقي من خلال splitEvenly، باستخدام مدخلات تترك باقيًا.","why":"صحيح. لا تهمّ الدالة المساعدة إلا بسبب ما تعيده splitEvenly، فالاختبار عبر الدالة العامة يغطّيها ويتركك حرًّا في حذفها أو إعادة تسميتها."},{"text":"انسخ الدالة المساعدة إلى ملف الاختبار واختبر النسخة.","why":"عندها يفحص الاختبار نسخة قد تبتعد عن الكود الحقيقي؛ وسيبقى أخضر بينما تنكسر الدالة الحقيقية."}],"answer":1}],"exercise":{"kind":"web","mode":"test","subject":"// Splits a bill in integer cents between people.\n// Contract:\n// - one share per person\n// - the shares add up exactly to totalCents\n// - shares differ by at most one cent\n// - leftover cents go to the FIRST people in the list\n// - fewer than one person throws a RangeError\nfunction 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","mutants":[{"id":"drops-remainder","code":"// Splits a bill in integer cents between people.\n// Contract:\n// - one share per person\n// - the shares add up exactly to totalCents\n// - shares differ by at most one cent\n// - leftover cents go to the FIRST people in the list\n// - fewer than one person throws a RangeError\nfunction 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) => (base));\n}\n"},{"id":"extra-cent","code":"// Splits a bill in integer cents between people.\n// Contract:\n// - one share per person\n// - the shares add up exactly to totalCents\n// - shares differ by at most one cent\n// - leftover cents go to the FIRST people in the list\n// - fewer than one person throws a RangeError\nfunction 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"},{"id":"remainder-last","code":"// Splits a bill in integer cents between people.\n// Contract:\n// - one share per person\n// - the shares add up exactly to totalCents\n// - shares differ by at most one cent\n// - leftover cents go to the FIRST people in the list\n// - fewer than one person throws a RangeError\nfunction 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 >= people - remainder ? base + 1 : base));\n}\n"},{"id":"zero-people","code":"// Splits a bill in integer cents between people.\n// Contract:\n// - one share per person\n// - the shares add up exactly to totalCents\n// - shares differ by at most one cent\n// - leftover cents go to the FIRST people in the list\n// - fewer than one person throws a RangeError\nfunction splitEvenly(totalCents, people) {\n if (!Number.isInteger(people) || people < 0) {\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"}],"starter":{"js":"const sum = (xs) => xs.reduce((a, b) => a + b, 0);\n\ndescribe('splitEvenly', () => {\n test('returns one share per person', () => {\n expect(splitEvenly(1000, 3)).toHaveLength(3);\n });\n\n // Test the rest of the contract in the subject's comment.\n});\n"},"solution":{"js":"const sum = (xs) => xs.reduce((a, b) => a + b, 0);\n\ndescribe('splitEvenly', () => {\n test('returns one share per person', () => {\n expect(splitEvenly(1000, 3)).toHaveLength(3);\n });\n\n test('never loses or invents a cent', () => {\n for (const [total, people] of [[1000, 3], [1001, 4], [2, 3], [900, 3], [0, 4]]) {\n expect(sum(splitEvenly(total, people))).toBe(total);\n }\n });\n\n test('keeps shares within one cent of each other', () => {\n const shares = splitEvenly(1001, 4);\n expect(Math.max(...shares) - Math.min(...shares)).toBeLessThanOrEqual(1);\n });\n\n test('gives the leftover cents to the first people', () => {\n expect(splitEvenly(1001, 4)).toEqual([251, 250, 250, 250]);\n expect(splitEvenly(1000, 3)).toEqual([334, 333, 333]);\n });\n\n test('refuses to split between zero people', () => {\n expect(() => splitEvenly(1000, 0)).toThrow(RangeError);\n });\n});\n"},"checks":[{"id":"passes","suite":"subject"},{"id":"catches-drops-remainder","suite":"drops-remainder"},{"id":"catches-extra-cent","suite":"extra-cent"},{"id":"catches-remainder-last","suite":"remainder-last"},{"id":"catches-zero-people","suite":"zero-people"}],"title":"اختبارات سلوك لـ splitEvenly","prompt":"

يسرد التعليق في الـ subject عقد splitEvenly. اكتب اختبارات لذلك العقد (لا لطريقة كتابة الدالة) حتى تنجح مجموعتك على الكود الحقيقي وتلتقط أربعة أخطاء مخفيّة:

\n\n

الدالة المساعدة sum موجودة مسبقًا في الكود المبدئي.

\n","hints":["المدخلات التي تنقسم بالتساوي (مثل 900 على 3) تُخفي كل أخطاء الباقي. استخدم إجماليات تترك باقيًا، مثل 1000 على 3 أو 1001 على 4.","ثابت المجموع يلتقط خطأين دفعة واحدة: expect(sum(splitEvenly(1000, 3))).toBe(1000).","لقاعدة الترتيب، قارن المصفوفة كلها: يجب أن تساوي splitEvenly(1001, 4) القيمة [251, 250, 250, 250]. ولعدد الأشخاص صفر، استخدم expect(() => splitEvenly(1000, 0)).toThrow(RangeError)."],"explanation":"

ثابت المجموع يحمل العبء الأكبر: إسقاط الباقي يجعل الإجمالي أصغر من اللازم، والخطأ بفارق واحد يجعله أكبر، فيقضي assertion واحد على الاثنين. قاعدة الترتيب جزء من العقد الموثّق، لذا فإن تأكيد المصفوفة بالضبط اختبار سلوك لا اختبار تفاصيل داخلية؛ وهو الطريقة الوحيدة لالتقاط النسخة التي تفضّل آخر الأشخاص، لأنها تحفظ المال وتبقى عادلة. أما حالة الصفر فهي حدّ كانت النسخة المعطوبة تعيد فيه [] بصمت، وكان المستدعي سيقسّم فاتورة على لا أحد. لا يذكر أيّ من هذه الاختبارات Math.floor أو % أو Array.from، فتستطيع إعادة كتابة الدالة بحرّية وتبقى الاختبارات خضراء.

\n","checkLabels":{"passes":"كل اختباراتك تنجح على splitEvenly الحقيقية","catches-drops-remainder":"تلتقط النسخة التي تُسقط السنتات المتبقّية","catches-extra-cent":"تلتقط النسخة التي توزّع سنتًا زائدًا","catches-remainder-last":"تلتقط النسخة التي تعطي السنتات المتبقّية لآخر الأشخاص","catches-zero-people":"تلتقط النسخة التي تقبل عدد أشخاص صفرًا"}},"words":562,"readMinutes":3}