في الدرس الماضي كتبت API بديلًا (stub) باليد، مع عدّاد. نجح الأمر، واستغرق نحو خمسة عشر سطرًا. أدوات vi في Vitest تفعل الشيء نفسه في سطر واحد، وتضيف قوة كبيرة. وهذه القوة هي المشكلة: الـ mocking أسرع طريقة لكتابة اختبار ينجح بينما الكود الحقيقي معطّل. يغطّي هذا الدرس الأدوات، ويغطّي حسن التقدير في استخدامها.
كل هذه test doubles (بدائل الاختبار)، أي أشياء تقوم مقام متعاون حقيقي:
\nفي Vitest، يعطيك vi.fn() الـ stub والـ spy (الجاسوس) في كائن واحد، والناس يسمّون كل ذلك “mocks” (بدائل وهمية). الأسماء أقل أهمية من السؤال الذي يجيب عنه كل منها: ماذا يعيد هذا المتعاون؟ (stub)، وكيف استُدعي؟ (spy).
يرسل Splitwise-lite تذكيرًا إلى كل من عليه مال. دالة الإرسال تُمرَّر كمعامل، فيستطيع الاختبار استبدالها:
\nimport { test, expect, vi } from 'vitest';\nimport { remindDebtors } from './remind.js';\n\ntest('reminds people who owe money, with the amount', () => {\n const sendReminder = vi.fn();\n\n const sent = remindDebtors({ Ana: 1500, Ben: -500, Cai: 0 }, sendReminder);\n\n expect(sent).toBe(1);\n expect(sendReminder).toHaveBeenCalledTimes(1);\n expect(sendReminder).toHaveBeenCalledWith('Ben', 'You owe $5.00 to the group');\n});يعيد vi.fn() القيمة undefined افتراضيًا. أعطه سلوكًا حين يحتاج الكود الخاضع للاختبار إلى إجابة:
const post = vi.fn().mockResolvedValue({ id: 'e1' }); // async success\nconst failing = vi.fn().mockRejectedValue(new Error('Offline')); // async failure\nconst send = vi.fn().mockImplementation((name) => {\n if (name === 'Ben') throw new Error('Mailbox full');\n});يُسجَّل كل استدعاء في send.mock.calls، وهي مصفوفة من مصفوفات المعاملات، للحالات النادرة التي لا تغطّيها الـ matchers.
أحيانًا يكون المتعاون دالة على كائن موجود، مثل console.warn. يلفّها vi.spyOn: افتراضيًا تظلّ الدالة الحقيقية تعمل، ويسجّل الـ spy الاستدعاءات. أضف mockImplementation لإسكاتها أو استبدالها:
import { afterEach, test, expect, vi } from 'vitest';\n\nafterEach(() => {\n vi.restoreAllMocks(); // put console.warn back\n});\n\ntest('warns and carries on when one reminder fails', () => {\n const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});\n const send = vi.fn().mockImplementationOnce(() => { throw new Error('Mailbox full'); });\n\n const sent = remindDebtors({ Ben: -500, Dee: -300 }, send);\n\n expect(sent).toBe(1);\n expect(send).toHaveBeenCalledTimes(2);\n expect(warn).toHaveBeenCalledWith('Could not remind Ben: Mailbox full');\n});يستبدل الـ spy دالة على كائن مشترك. انسَ استعادتها، وسيعمل كل اختبار لاحق في الملف مع console.warn صامت. وجود vi.restoreAllMocks() داخل afterEach، أو restoreMocks: true في الإعدادات، يجعل التنظيف تلقائيًا.
الكود الذي ينتظر (الحفظ التلقائي المؤجَّل بـ debounce، والتباطؤ بين المحاولات، ورسائل “تراجع” المؤقّتة) اختباره بالوقت الحقيقي مؤلم. تستبدل المؤقّتات المزيّفة (fake timers) كلًّا من setTimeout وsetInterval وDate بساعة يتحكّم فيها الاختبار:
import { afterEach, test, expect, vi } from 'vitest';\n\nafterEach(() => vi.useRealTimers());\n\ntest('autosaves the draft 2 seconds after the last change', () => {\n vi.useFakeTimers();\n const save = vi.fn();\n const draft = createDraft({ save, delayMs: 2000 }); // debounced\n\n draft.update({ description: 'Din' });\n draft.update({ description: 'Dinner' });\n vi.advanceTimersByTime(1999);\n expect(save).not.toHaveBeenCalled();\n\n vi.advanceTimersByTime(1);\n expect(save).toHaveBeenCalledWith({ description: 'Dinner' });\n});يشغّل vi.advanceTimersByTime(ms) فورًا كل مؤقّت يحين موعده خلال تلك الفترة. ويثبّت vi.setSystemTime(date) قيمة new Date()، وهكذا تختبر أن “التذكيرات تُرسل في أول كل شهر”. وحين تجدول المؤقّتات promises، استخدم النسخ غير المتزامنة مثل vi.advanceTimersByTimeAsync. (ساحة التجربة لا تشغّل إلا المؤقّتات الحقيقية، لذا يبقى هذا المثال على الصفحة فقط.)
كل mock ادّعاء عن طريقة عمل الشيء الحقيقي. وحين يبتعد الواقع عن الادّعاء، يستمرّ الاختبار في النجاح. الأنماط التي تؤذي:
\nparseAmount داخل اختبار النموذج يعني أن النموذج والمحلّل لا يُختبران معًا أبدًا، وهذا كان الهدف من الاختبار. كودك الصافي سريع؛ استخدمه.remindDebtors وأنت تختبر remindDebtors، فأنت تختبر الـ spy.{ id }؛ والحقيقي يعيد { data: { id } }. الـ unit tests خضراء، والتطبيق معطّل. ومحاكاة الشبكة في القسم التالي واختبارات الـ end-to-end في القسم 4 موجودة لالتقاط هذا بالضبط.فحص سريع لأي mock تكتبه: احذف سطرًا واحدًا من الكود الحقيقي الذي يقوم مقامه. إن لم يفشل أي اختبار في أي مكان من المجموعة، فذلك الـ mock كان يُخفي السلوك بدل أن يختبر ما حوله، وتحتاج في مكان ما إلى اختبار يشغّل الشيء الحقيقي.
\nقاعدتي: استخدم الـ mocks عند حدود نظامك (الشبكة، والبريد، والدفع، والوقت، والعشوائية)، وشغّل الكود الحقيقي في كل ما بداخله.
\nفي التمرين، استخدم vi.fn وvi.spyOn لالتقاط أربعة أخطاء في remindDebtors. وينتقل القسم 3 من الدوال إلى الـ DOM.
vi.fn() دالة تسجّل كل استدعاء، وتستطيع أن تحدّد ما تعيده باستخدام mockReturnValue أو mockResolvedValue أو mockImplementation.","يراقب vi.spyOn(object, 'method') دالة حقيقية ويستطيع استبدالها؛ أعِد الـ spies دائمًا إلى أصلها، مثلًا بـ vi.restoreAllMocks() داخل afterEach.","استخدم الـ mocks عند حدود نظامك (الشبكة، والبريد، والوقت، والعشوائية)، واستخدم الكود الحقيقي لوحداتك أنت.","تسمح المؤقّتات المزيّفة (vi.useFakeTimers وvi.advanceTimersByTime) للاختبار بأن يقفز فوق فترات الانتظار بدل أن ينتظرها.","كل mock ادّعاء عن طريقة عمل الشيء الحقيقي؛ وحين يبتعد هذا الادّعاء عن الواقع، يبقى الاختبار أخضر بينما ينكسر الإنتاج."],"further":[{"title":"Vitest — Mocking guide","url":"https://vitest.dev/guide/mocking"},{"title":"Vitest — Mock functions API","url":"https://vitest.dev/api/mock"},{"title":"Vitest — Fake timers","url":"https://vitest.dev/guide/mocking/timers"}],"quiz":[{"q":"تريد التحقّق من أن remindDebtors تستدعي sendReminder('Ben', 'You owe $5.00 to the group'). أيّ assertion هو المناسب؟
expect(sendReminder).toHaveBeenCalledWith('Ben', 'You owe $5.00 to the group')","why":"صحيح. ينجح toHaveBeenCalledWith إن كان أيّ استدعاء مسجَّل قد استخدم هذه المعاملات بالضبط، وبهذا الترتيب."},{"text":"expect(sendReminder('Ben')).toBe('You owe $5.00 to the group')","why":"هذا يستدعي الـ mock بنفسك ويفحص قيمته المعادة؛ ولا يقول شيئًا عمّا فعلته remindDebtors."},{"text":"expect(sendReminder).toHaveBeenCalled()","why":"ينجح حتى لو كانت المعاملات خاطئة أو متبادلة الموقع، فيفوته معظم الأخطاء التي تهمّك."}],"answer":0},{"q":"اختبار لنموذج المصروفات يستخدم mock مكان الوحدة الداخلية parseAmount بحيث تعيد دائمًا 1250. ثم يظهر خطأ في parseAmount الحقيقية. ماذا يحدث لاختبار النموذج؟
vi.mock استبدال أي وحدة، بما فيها وحداتك، وهذا بالضبط مكمن الخطر هنا."},{"text":"يبقى أخضر، لأنه لا يشغّل المحلّل الحقيقي أبدًا؛ فلم يعد النموذج والمحلّل يُختبران معًا.","why":"صحيح. استخدام الـ mocks مكان وحداتك الصافية لا يوفّر سرعة تُذكر، ويُلغي التكامل الذي أردت فحصه."}],"answer":2},{"q":"تُحفظ المسوّدة تلقائيًا بعد ثانيتين من آخر ضغطة مفتاح. مع تفعيل vi.useFakeTimers()، كيف يجعل الاختبار الحفظ يحدث؟
await new Promise((r) => setTimeout(r, 2000)).","why":"مع المؤقّتات المزيّفة يكون setTimeout هذا مزيّفًا أيضًا، فلا يعمل من تلقاء نفسه أبدًا، ويعلق الاختبار حتى تنتهي مهلته."},{"text":"باستدعاء vi.advanceTimersByTime(2000) بعد آخر ضغطة مفتاح، ثم تأكيد أن الحفظ حدث.","why":"صحيح. تقديم الساعة المزيّفة يشغّل فورًا كل مؤقّت يحين موعده خلال تلك الفترة."},{"text":"بضبط مهلة الاختبار على 3 ثوانٍ كي يجد المؤقّت الحقيقي وقتًا ليعمل.","why":"مع تثبيت المؤقّتات المزيّفة لا يوجد مؤقّت حقيقي؛ والمهلة الأطول تؤخّر الفشل فقط."}],"answer":1},{"q":"لماذا تستدعي vi.restoreAllMocks() (أو تضبط restoreMocks) بعد الاختبارات التي تستخدم vi.spyOn؟
vi.fn() إلى الصفر.","why":"مسح سجلّ الاستدعاءات هو ما يفعله mockClear؛ أما الاستعادة فتتعلّق بإرجاع الدالة الأصلية."},{"text":"لإرجاع الدوال الأصلية كي لا يغيّر spy من اختبار ما السلوك في اختبار آخر.","why":"صحيح. يستبدل الـ spy دالة حقيقية على كائن مشترك مثل console؛ وبدون الاستعادة يتسرّب الاستبدال إلى الاختبارات اللاحقة."},{"text":"لأن Vitest ترفض تشغيل اختبار ثانٍ ما دام هناك spy موجود.","why":"تعمل Vitest بلا مشكلة مع spies متسرّبة، ولهذا بالضبط تسبّب التسرّبات حالات فشل مربكة في اختبارات لا علاقة لها."}],"answer":1}],"exercise":{"kind":"web","mode":"test","subject":"function formatMoney(cents) {\n const sign = cents < 0 ? '-' : '';\n const abs = Math.abs(cents);\n return `${sign}$${Math.floor(abs / 100)}.${String(abs % 100).padStart(2, '0')}`;\n}\n\n// Sends a reminder to everyone who owes money (a negative balance).\n// - Calls sendReminder(name, message) once per debtor, with a message\n// such as \"You owe $5.00 to the group\".\n// - Skips debts smaller than minimumCents (default 100, i.e. $1.00);\n// a debt of exactly minimumCents IS reminded.\n// - People who are owed money or are settled up get nothing.\n// - If sendReminder throws for someone, logs\n// console.warn(\"Could not remind تستدعي remindDebtors(balances, sendReminder) الدالة sendReminder(name, message) لكل شخص عليه $1.00 على الأقل، وتحذّر عبر console.warn حين يفشل تذكير، وتعيد عدد التذكيرات التي أرسلتها. الأرصدة الموجبة لأشخاص لهم مال؛ والسالبة لأشخاص عليهم مال. القواعد مذكورة في تعليق الـ subject.
يتجسّس الكود المبدئي على console.warn مسبقًا (ويستعيده بعد كل اختبار). استخدم vi.fn() مكان sendReminder وأضف اختبارات حتى تلتقط مجموعتك أربعة أخطاء مخفيّة: نسخة تذكّر من لهم مال، ونسخة تبادل موقعي المعاملين، ونسخة تتخطّى دينًا قيمته $1.00 بالضبط، ونسخة تتوقّف عند أول تذكير فاشل.
vi.fn() وافحصه بـ toHaveBeenCalledWith('Ben', 'You owe $5.00 to the group') وtoHaveBeenCalledTimes(1). ترتيب المعاملات بالضبط مهم.","الحدّ: الرصيد -100 يجب أن يُذكَّر صاحبه، و-99 يجب ألا يُذكَّر.","لحالة الفشل، اجعل الـ mock يرمي خطأً لاسم واحد: vi.fn().mockImplementation((name) => { if (name === 'Ben') throw new Error('Mailbox full'); })، ثم أكّد أن المدين التالي استُدعي رغم ذلك، وأن warn استُدعيت بالرسالة."],"explanation":"يفحص toHaveBeenCalledWith المعاملات بالترتيب، فيلتقط النسخة التي تبادل موقعيهما، وtoHaveBeenCalledTimes(1) مع وجود دائن في الأرصدة يلتقط النسخة التي تذكّر الجميع. اختبار الحدّ يستخدم -100 و-99، واحدًا على كل جهة من الحدّ؛ و-100، الواقع على الحدّ تمامًا، هو المدخل الذي يميّز < من <=. واختبار الفشل يجعل الـ mock يرمي خطأً لشخص واحد ويتحقّق من أن الشخص التالي ذُكِّر رغم ذلك؛ أما النسخة التي تعيد رمي الخطأ فلا تصل إليه أبدًا فيفشل الاختبار. والـ spy على console.warn يحوّل أثرًا جانبيًا كنت ستتجاهله عادةً إلى شيء تستطيع تأكيده، واستعادته في afterEach تمنعه من التسرّب إلى اختبارات أخرى.