يُقرأ الاختبار أكثر بكثير مما يُكتب. يُقرأ حين يفشل في لحظة سيئة، على يد شخص لم يكتبه، يريد إجابة واحدة: ما الذي انكسر؟ هذا الدرس عن كتابة اختبارات تجيب عن هذا السؤال في ثوانٍ، وعن قراءة الإجابة التي تعطيك إياها Vitest.
\nلكل اختبار جيد تقريبًا الأجزاء الثلاثة نفسها:
\nimport { test, expect } from 'vitest';\nimport { withTip } from './tip.js';\n\ntest('rounds a half-cent tip up to the next cent', () => {\n // Arrange: the inputs that matter for this behaviour\n const subtotalCents = 1980;\n const percent = 12.5;\n\n // Act: one call to the code under test\n const result = withTip(subtotalCents, percent);\n\n // Assert: the claims about the outcome\n expect(result).toEqual({ tipCents: 248, totalCents: 2228 });\n});Arrange (التهيئة) يبني العالم الذي يحتاجه الاختبار. Act (الفعل) يفعل شيئًا واحدًا فقط: السلوك الذي تختبره. Assert (التأكيد) يذكر ما يجب أن يكون صحيحًا الآن. لن تحتاج إلى التعليقات بعد أن يصبح هذا الشكل عادة؛ الأسطر الفارغة تكفي.
\nيحميك هذا الشكل من أشهر رائحة سيئة في الاختبارات: اختبار يفعل، ثم يؤكّد، ثم يفعل مرة أخرى، ثم يؤكّد مرة أخرى. حين يفشل، لا تستطيع أن تعرف أيّ خطوة انكسرت. قسّمه إلى اختبارين، لكل منهما اسم يقول ما الذي يثبته.
\nستسمع قاعدة “assertion واحد لكل اختبار”، وهي قاعدة صارمة أكثر من اللازم. القاعدة الحقيقية هي سلوك واحد لكل اختبار. فحص tipCents وtotalCents معًا بعد استدعاء واحد هو سلوك واحد له حقيقتان يمكن ملاحظتهما، فلا بأس بتأكيد الاثنتين، وtoEqual على الكائن كله يفعل ذلك في سطر واحد. ما تريد تجنّبه هو اختبار يفحص التقريب، ثم يستدعي الدالة مجددًا ليفحص حالة الخطأ، ثم مرة ثالثة ليفحص الصفر. حين يفشل الادّعاء الأول، توقف Vitest ذلك الاختبار، فلا تعرف أبدًا إن كان السلوكان الآخران ما زالا يعملان. ثلاثة اختبارات صغيرة تعطيك ثلاث إجابات منفصلة.
حين يفشل اختبار، يطبع التقرير مساره الكامل: withTip > rounds a half-cent tip up to the next cent. اكتب ذلك الاسم جملةً عن السلوك. “withTip works” لا تخبرك بشيء؛ أما “rejects a negative tip percent” فتخبرك بما تراجع قبل أن تفتح أي ملف. اجمع بـ describe حسب الوحدة، وسمِّ بـ test حسب القاعدة.
يقوم اثنان من الـ matchers (أدوات المطابقة) بمعظم العمل، ويقارن كلٌّ منهما بطريقة مختلفة:
\ntoBe يستخدم Object.is: القيمة البدائية نفسها، أو مرجع الكائن نفسه. استخدمه مع الأرقام والنصوص والقيم المنطقية.toEqual يقارن البنية بشكل متكرّر: المفاتيح نفسها، والقيم نفسها. استخدمه مع الكائنات والمصفوفات. (ويفحص toStrictEqual أيضًا تطابق الخصائص التي قيمتها undefined وأنواع الأصناف.)expect(withTip(2000, 15)).toBe({ tipCents: 300, totalCents: 2300 }) يفشل رغم تطابق القيم، لأن الدالة تعيد كائنًا جديدًا. هذا الفخ يقع فيه الجميع مرة واحدة على الأقل.
إليك نوعًا حقيقيًا من الأخطاء. النسخة الأولى من toCents، التي تحوّل مبلغًا بالدولار إلى سنتات، استخدمت Math.floor:
const toCents = (dollars) => Math.floor(dollars * 100);\nconsole.log(0.29 * 100); // what the computer actually computes\nconsole.log(toCents(0.29)); // one cent short\nconsole.log(Math.round(0.29 * 100));يفشل الاختبار expect(toCents(0.29)).toBe(29)، وتعرض Vitest شيئًا كهذا:
FAIL src/money.test.js > toCents > converts 0.29 dollars to 29 cents\nAssertionError: expected 28 to be 29 // Object.is equality\n\n- Expected\n+ Received\n\n- 29\n+ 28\n\n ❯ src/money.test.js:7:28اقرأها من الأعلى إلى الأسفل، على ثلاث مراحل:
\nmoney.test.js:7:28) يشير إلى سطر الـ assertion في الاختبار. والخطأ موجود في الكود الذي يستدعيه ذلك السطر.مع الكائنات، يعلّم الفرق (diff) الأسطر المختلفة فقط، فيبرز totalCents الخاطئ داخل كائن من عشرة مفاتيح فورًا.
أحيانًا يكون السلوك المطلوب هو “رفض المدخلات السيئة”. لفّ الاستدعاء داخل دالة كي يستطيع expect أن يستدعيها ويلتقط الخطأ:
test('rejects a negative tip percent', () => {\n expect(() => withTip(1000, -5)).toThrow(RangeError);\n});بدون الـ arrow function، ترمي withTip الخطأ أثناء حساب المعاملات، قبل أن يعمل expect، فينهار الاختبار بدل أن ينجح. ويقبل toThrow أيضًا نصًّا أو تعبيرًا نمطيًا (regex) لمطابقة رسالة الخطأ.
في التمرين تكتب اختبارات بنمط AAA لـ withTip، بما فيها الحدّ الذي يسهل نسيانه: بقشيش قيمته صفر. وينتقل القسم التالي من “كيف يبدو الاختبار” إلى “أيّ الاختبارات تستحق أن تُكتب”.
toBe باستخدام Object.is (القيمة نفسها أو المرجع نفسه)؛ أما toEqual فيقارن البنية، وهذا ما تريده مع الكائنات والمصفوفات.","يعطيك تقرير الفشل مسار الاختبار، والقيمتين المتوقّعة والمستلمة، والملف ورقم السطر؛ اقرأ الثلاثة قبل أن تلمس الكود."],"further":[{"title":"Vitest — expect API","url":"https://vitest.dev/api/expect"},{"title":"Vitest — Test API","url":"https://vitest.dev/api/test"},{"title":"MDN — Number.EPSILON and floating point","url":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/EPSILON"}],"quiz":[{"q":"ماذا يُظهر هذا الاختبار؟
\ntest('builds the tip summary', () => {\n expect(withTip(2000, 15)).toBe({ tipCents: 300, totalCents: 2300 });\n});toBe يفحص التطابق في الهوية باستخدام Object.is، وكائنان أُنشئ كلٌّ منهما على حدة لا يكونان المرجع نفسه أبدًا."},{"text":"يفشل، لأن toBe يقارن المراجع والدالة تعيد كائنًا جديدًا.","why":"صحيح. استخدم toEqual (أو toStrictEqual) لمقارنة الكائنات بمحتواها."},{"text":"يرمي خطأً في الصياغة لأن الكائنات لا يمكن تمريرها إلى toBe.","why":"يمكن تمرير أي قيمة إلى toBe؛ المشكلة في نوع المقارنة التي يجريها، لا في الصياغة."}],"answer":1},{"q":"يطبع اختبار فاشل expected 28 to be 29 للاستدعاء toCents(0.29). أين تنظر أولًا؟
0.29 * 100 يساوي 28.999999999999996 في كل مكان، فلا علاقة للإعدادات."},{"text":"إلى الطريقة التي تحوّل بها toCents العدد العشري إلى عدد صحيح، لأن 0.29 * 100 أقل من 29 بقليل.","why":"صحيح. القيمة المستلمة تخبرك أن الكود اقتطع قيمة كانت أقل من 29 بشعرة؛ Math.round يصلح ذلك، وMath.floor هو سببه."}],"answer":2},{"q":"أيّ اسم اختبار هو الأكثر فائدة حين يفشل في CI في الثانية فجرًا؟
","options":[{"text":"test('withTip works')","why":"يذكر الدالة لا السلوك؛ ما زال عليك فتح الملف لتعرف ما الذي انكسر."},{"text":"test('test 3')","why":"الرقم لا يحمل أي معلومة، ويصبح خاطئًا بمجرد إعادة ترتيب الاختبارات."},{"text":"test('rounds a half-cent tip up to the next cent')","why":"صحيح. الاسم يذكر القاعدة، فتقرير الفشل وحده يخبرك أيّ سلوك تراجع."},{"text":"test('withTip(1980, 12.5)')","why":"المدخل ظاهر لكن السلوك المتوقّع غير ظاهر؛ لا يستطيع القارئ أن يعرف ما الناتج الصحيح المقصود."}],"answer":2},{"q":"لماذا تظهر مراحل Arrange وAct وAssert عادةً بهذا الترتيب، يفصل بينها سطر فارغ؟
","options":[{"text":"تشترط Vitest المراحل الثلاث بهذا الترتيب وإلا تخطّت الاختبار.","why":"لا تعرف Vitest شيئًا عن المراحل؛ نمط AAA عُرف موجّه للبشر، لا قاعدة يفرضها المشغّل."},{"text":"يجعل التهيئة والفعل الوحيد الخاضع للاختبار والادّعاءات سهلة الرؤية بنظرة واحدة.","why":"صحيح. الشكل الثابت يعني أن القارئ يستطيع القفز مباشرة إلى الفعل والـ assertion في أي اختبار."},{"text":"يسمح لـ Vitest بتشغيل مرحلة Arrange مرة واحدة للملف كله.","why":"التهيئة المشتركة مكانها الـ hooks مثلbeforeEach؛ والأسطر الفارغة داخل الاختبار لا تغيّر شيئًا وقت التشغيل."}],"answer":1}],"exercise":{"kind":"web","mode":"test","subject":"// Adds a tip to a subtotal. Money is in integer cents; percent is a\n// number such as 15 or 12.5. The tip is rounded to the nearest cent\n// (a half cent rounds up). A zero tip is allowed; a negative one is not.\nfunction withTip(subtotalCents, percent) {\n if (percent < 0) throw new RangeError('Tip percent cannot be negative');\n const tipCents = Math.round((subtotalCents * percent) / 100);\n return { tipCents, totalCents: subtotalCents + tipCents };\n}\n","mutants":[{"id":"floors-tip","code":"// Adds a tip to a subtotal. Money is in integer cents; percent is a\n// number such as 15 or 12.5. The tip is rounded to the nearest cent\n// (a half cent rounds up). A zero tip is allowed; a negative one is not.\nfunction withTip(subtotalCents, percent) {\n if (percent < 0) throw new RangeError('Tip percent cannot be negative');\n const tipCents = Math.floor((subtotalCents * percent) / 100);\n return { tipCents, totalCents: subtotalCents + tipCents };\n}\n"},{"id":"allows-negative","code":"// Adds a tip to a subtotal. Money is in integer cents; percent is a\n// number such as 15 or 12.5. The tip is rounded to the nearest cent\n// (a half cent rounds up). A zero tip is allowed; a negative one is not.\nfunction withTip(subtotalCents, percent) {\n \n const tipCents = Math.round((subtotalCents * percent) / 100);\n return { tipCents, totalCents: subtotalCents + tipCents };\n}\n"},{"id":"rejects-zero","code":"// Adds a tip to a subtotal. Money is in integer cents; percent is a\n// number such as 15 or 12.5. The tip is rounded to the nearest cent\n// (a half cent rounds up). A zero tip is allowed; a negative one is not.\nfunction withTip(subtotalCents, percent) {\n if (percent <= 0) throw new RangeError('Tip percent cannot be negative');\n const tipCents = Math.round((subtotalCents * percent) / 100);\n return { tipCents, totalCents: subtotalCents + tipCents };\n}\n"}],"starter":{"js":"describe('withTip', () => {\n test('adds a 15% tip to the subtotal', () => {\n // Arrange\n const subtotalCents = 2000;\n\n // Act\n const result = withTip(subtotalCents, 15);\n\n // Assert\n expect(result).toEqual({ tipCents: 300, totalCents: 2300 });\n });\n\n // Add: a half-cent tip that must round up,\n // a zero tip, and a negative percent that must throw.\n});\n"},"solution":{"js":"describe('withTip', () => {\n test('adds a 15% tip to the subtotal', () => {\n const subtotalCents = 2000;\n\n const result = withTip(subtotalCents, 15);\n\n expect(result).toEqual({ tipCents: 300, totalCents: 2300 });\n });\n\n test('rounds a half-cent tip up to the next cent', () => {\n const result = withTip(1980, 12.5);\n\n expect(result).toEqual({ tipCents: 248, totalCents: 2228 });\n });\n\n test('allows a zero tip', () => {\n const result = withTip(2000, 0);\n\n expect(result).toEqual({ tipCents: 0, totalCents: 2000 });\n });\n\n test('rejects a negative tip percent', () => {\n expect(() => withTip(2000, -5)).toThrow(RangeError);\n });\n});\n"},"checks":[{"id":"passes","suite":"subject"},{"id":"catches-floors-tip","suite":"floors-tip"},{"id":"catches-allows-negative","suite":"allows-negative"},{"id":"catches-rejects-zero","suite":"rejects-zero"}],"title":"اختبارات AAA لـ withTip","prompt":"تعيد withTip(subtotalCents, percent) الكائن { tipCents, totalCents }. يُقرَّب البقشيش إلى أقرب سنت (ونصف السنت يُقرَّب إلى الأعلى)، والبقشيش بنسبة 0% صالح، والنسبة السالبة ترمي RangeError.
يفحص الاختبار المبدئي بقشيشًا بنسبة 15% على $20.00. أضف اختبارات بشكل Arrange وAct وAssert حتى تنجح مجموعتك على الكود الحقيقي وتلتقط ثلاثة أخطاء مخفيّة: نسخة تأخذ الجزء الصحيح من البقشيش بدل تقريبه، ونسخة تنسى رفض النسب السالبة، ونسخة ترفض البقشيش الصفري خطأً.
\n","hints":["بقشيش 15% على 2000 يساوي 300 بالضبط، فلا يؤثّر التقريب هناك أبدًا. تحتاج إلى مدخل ينتهي فيه البقشيش الدقيق بـ .5 أو أكثر.","1980 سنتًا بنسبة 12.5% تساوي 247.5 سنتًا، ويجب أن تُقرَّب إلى 248. قارن الكائن كله باستخدامtoEqual.","للخطأ، لفّ الاستدعاء: expect(() => withTip(2000, -5)).toThrow(RangeError). وللصفر، أكّد النتيجة نفسها، لا مجرّد أن الدالة لا ترمي خطأً."],"explanation":"كل اختبار مضاف يثبّت قاعدة واحدة من المواصفات بمدخل يفصل الصحيح عن الخاطئ. البقشيش الذي يقع على نصف سنت يميّز Math.round من Math.floor. والبقشيش الصفري يلتقط زلّة الحدود الكلاسيكية (<= بدل <)، التي كانت ستجعل Splitwise-lite يرفض فاتورة عادية تمامًا. وتحتاج الحالة السالبة إلى الـ arrow function كي يلتقط expect الخطأ المرمي. وتأكيد الكائن الكامل { tipCents, totalCents } باستخدام toEqual يحمي المجموع أيضًا، فيغطّي assertion واحد الحقلين معًا.