أسرع طريقة للتوقّف عن كتابة الاختبارات هي إعداد بطيء ومزعج. إن كان تشغيل اختبار واحد يستغرق 15 ثانية ويتطلّب ثلاثة ملفات إعدادات، فستتخطّاه “هذه المرة فقط” إلى أن لا يبقى أي اختبار. وُجدت Vitest في الأساس لحلّ هذه المشكلة: فهي تتّصل بإعداد Vite الموجود أصلًا في تطبيقك، فلا يستغرق أول اختبار أكثر من دقيقتين تقريبًا.
\nفي مشروع Vite (React أو Vue أو JavaScript صرف، لا فرق):
\nnpm install --save-dev vitestأضف سكربتين إلى package.json:
{\n \"scripts\": {\n \"test\": \"vitest\",\n \"test:run\": \"vitest run\"\n }\n}يبدأ npm test وضع المراقبة (watch mode): تشغّل Vitest مجموعة الاختبارات ثم تنتظر. وحين تحفظ ملفًا، تعيد تشغيل الاختبارات التي تستورده فقط، معتمدةً على مخطّط الوحدات (module graph) في Vite. على حاسوب محمول يستغرق ذلك عادةً أقل بكثير من ثانية، وهذا ما يجعل الاختبار جزءًا من البرمجة لا عبئًا تؤجّله إلى النهاية. أما npm run test:run فيشغّل كل شيء مرة واحدة ثم يخرج؛ وهذا هو الأمر المناسب لـ CI (كما تُطفئ Vitest وضع المراقبة تلقائيًا حين يكون متغيّر البيئة CI مضبوطًا).
إن كنت تفضّل مشغّلًا مرئيًا، فثبّت @vitest/ui وشغّل vitest --ui: سيفتح لوحة في المتصفّح تعرض كل ملف وكل اختبار، مع حالات الفشل ومخرجات الـ console ومخطّط الوحدات، ويعيد التشغيل عند الحفظ تمامًا كما تفعل الطرفية. وإضافة Vitest الرسمية لـ VS Code تعطيك أزرار التشغيل وتصحيح الأخطاء نفسها بجانب كل اختبار داخل المحرّر. اختر ما يُبقيك في حالة تركيز؛ فالاختبارات هي نفسها.
يحفظ Splitwise-lite المبالغ المالية كسنتات صحيحة (سنشرح السبب في الدرس القادم)، لذا يحتاج إلى دالة تحوّل 1234 إلى "$12.34":
export function formatMoney(cents) {\n const sign = cents < 0 ? '-' : '';\n const abs = Math.abs(cents);\n const dollars = Math.floor(abs / 100);\n const rest = String(abs % 100).padStart(2, '0');\n return `${sign}$${dollars}.${rest}`;\n}ضع الاختبار بجوارها، باسم يجعل Vitest تجده:
\nimport { describe, test, expect } from 'vitest';\nimport { formatMoney } from './money.js';\n\ndescribe('formatMoney', () => {\n test('formats dollars and cents', () => {\n expect(formatMoney(1234)).toBe('$12.34');\n });\n\n test('pads single-digit cents', () => {\n expect(formatMoney(505)).toBe('$5.05');\n });\n});يجمع describe الاختبارات المترابطة (ويظهر في التقرير بصيغة formatMoney > pads single-digit cents). ويعرّف test (واسمه البديل it) اختبارًا واحدًا. أما expect(value).toBe(expected) فهو الـ assertion (التأكيد): يرمي خطأً حين تختلف القيمتان، تمامًا مثل expectEqual التي كتبتها في الدرس السابق.
تقرأ Vitest ملف vite.config.js الموجود لديك، فتعمل الـ aliases والـ plugins في الاختبارات دون أي جهد. وتوضع خيارات الاختبار تحت المفتاح test:
/// <reference types=\"vitest/config\" />\nimport { defineConfig } from 'vite';\nimport react from '@vitejs/plugin-react';\n\nexport default defineConfig({\n plugins: [react()],\n test: {\n environment: 'node',\n },\n});سطر الشرطات المائلة الثلاث يعطي محرّرك الأنواع الخاصة بالمفتاح test. وenvironment: 'node' هو الافتراضي، كتبناه هنا صراحةً كي تعرف أن هذا المفتاح موجود. المنطق الصافي مثل تنسيق المبالغ يعمل في Node، وهو سريع. أما الاختبارات التي تحتاج إلى document (وستكتبها في القسم 3) فتستخدم jsdom أو happy-dom، وكلاهما يُثبَّت على حدة، ويُضبط إمّا هنا أو لكل ملف بتعليق // @vitest-environment jsdom في أعلاه.
سترى أيضًا globals: true في بعض المشاريع. هذا الخيار يجعل test وexpect متاحين دون استيراد، على طريقة Jest. لكن الاستيراد الصريح هو الافتراضي، ويتوافق بشكل أفضل مع المحرّرات وأدوات الـ lint، لذا تستوردهما هذه الدورة.
كلما كبرت مجموعة الاختبارات، سترغب في تشغيل جزء أصغر منها:
\nnpx vitest money # only files whose path contains \"money\"\nnpx vitest -t \"pads\" # only tests whose name matches \"pads\"\nnpx vitest run --reporter=verbose # one pass, every test name listedداخل الملف، يشغّل test.only(...) ذلك الاختبار وحده، ويركن test.skip(...) اختبارًا جانبًا. كلاهما مفيد أثناء تتبّع الأخطاء، وخطير إن دخل في commit، لأن .only منسيًّا يُطفئ بقية الملف بصمت. وتحمي Vitest من ذلك في CI: فحين يكون متغيّر البيئة CI مضبوطًا، يفشل أي اختبار عليه .only برسالة “Unexpected .only modifier” بدل أن يتخطّى جيرانه بهدوء.
تعمل التمارين التالية في بيئة معزولة داخل المتصفّح، فيها جزء متوافق مع Vitest: الدوال describe وtest وexpect وvi والـ hooks متاحة مباشرة، والكود الخاضع للاختبار (الـ subject) محمَّل لك، فلا حاجة إلى أي استيراد. حين تتحقّق من حلّك، تعمل اختباراتك على الـ subject الحقيقي ويجب أن تنجح، ثم على بضع نسخ معطوبة عمدًا ويجب أن تفشل على كل واحدة منها.
ينظر الدرس القادم عن قرب في ما يوضع داخل الاختبار، وفي كيفية قراءة المخرجات حين يفشل.
\n","toc":[{"id":"sec-1","text":"التثبيت والتشغيل","level":2},{"id":"sec-2","text":"أول ملف اختبار","level":2},{"id":"sec-3","text":"أين توجد الإعدادات","level":2},{"id":"sec-4","text":"تشغيل جزء من مجموعة الاختبارات","level":2},{"id":"sec-5","text":"في ساحة التجربة","level":2}],"takeaways":["تعيد Vitest استخدام إعدادات Vite لديك، فتنطبق الـ aliases والـ plugins والتحويلات نفسها على اختباراتك دون إعداد يُذكر.","الملفات المسمّاة*.test.js أو *.spec.js (ونظيراتها بامتدادات ts وjsx وtsx) تُلتقط تلقائيًا؛ ضع كل ملف منها بجوار الكود الذي يختبره.","شغّل vitest أثناء العمل (فوضع المراقبة يعيد تشغيل الاختبارات المتأثّرة عند الحفظ)، وvitest run في CI لتشغيلة واحدة.","البيئة الافتراضية هي Node؛ لا تنتقل إلى jsdom أو happy-dom إلا في الاختبارات التي تحتاج إلى DOM."],"further":[{"title":"Vitest — Getting Started","url":"https://vitest.dev/guide/"},{"title":"Vitest — Configuring Vitest","url":"https://vitest.dev/config/"},{"title":"Vitest — Test Environment","url":"https://vitest.dev/guide/environment"}],"quiz":[{"q":"تشغّل npx vitest على حاسوبك، ولا ينتهي الأمر بعد انتهاء الاختبارات. ما الذي يحدث؟
vitest افتراضيًا في وضع المراقبة؛ أما vitest run (أو CI=true) فيعمل مرة واحدة ثم يخرج."},{"text":"تحتاج Vitest إلى الخيار --exit على macOS وLinux.","why":"لا يوجد شرط كهذا؛ العملية تبقى حيّة عمدًا لأن وضع المراقبة هو الافتراضي محليًا."}],"answer":1},{"q":"أيّ ملف ستلتقطه Vitest كملف اختبار بالإعدادات الافتراضية؟
","options":[{"text":"src/money.tests.js","why":"النمط الافتراضي يطابق .test. أو .spec. قبل الامتداد؛ و.tests. بحرف s لا يطابقه."},{"text":"src/__tests__/money.js","why":"لا تعامل Vitest مجلدات __tests__ معاملة خاصة افتراضيًا؛ يجب أن يحتوي اسم الملف نفسه على .test. أو .spec.."},{"text":"src/money.spec.ts","why":"صحيح. نمط التضمين الافتراضي هو **/*.{test,spec}.?(c|m)[jt]s?(x)، وهو يشمل .spec.ts."},{"text":"test/money.js","why":"اسم مجلد test لا يكفي؛ فبدون .test. أو .spec. في اسم الملف يُتجاهَل افتراضيًا."}],"answer":2},{"q":"يفشل اختبار لـ formatMoney بالرسالة ReferenceError: document is not defined، مع أن formatMoney لا تلمس الـ DOM أبدًا. ما السبب الأرجح؟
document لحظة استيرادها، والبيئة هي Node.","why":"صحيح. البيئة الافتراضية لا تحتوي على DOM؛ وهناك شيء في سلسلة الاستيراد يقرأ document. إمّا أن تفصل تلك الوحدة، أو تضبط البيئة لذلك الملف."},{"text":"تحتاج Vitest إلى globals: true قبل أن تعمل الاختبارات.","why":"الـ globals تتحكّم فقط في إتاحة test وexpect دون استيرادهما؛ ولا علاقة لها بـ document."},{"text":"لا تستطيع Vitest اختبار إلا الكود الذي يعمل في المتصفّح.","why":"العكس تمامًا: تشغّل Vitest الاختبارات افتراضيًا في Node، ولهذا بالذات لا يوجد document."}],"answer":0}],"exercise":{"kind":"web","mode":"test","subject":"// Splitwise-lite stores money as integer cents.\n// formatMoney(1234) -> \"$12.34\", formatMoney(-505) -> \"-$5.05\"\nfunction formatMoney(cents) {\n const sign = cents < 0 ? '-' : '';\n const abs = Math.abs(cents);\n const dollars = Math.floor(abs / 100);\n const rest = String(abs % 100).padStart(2, '0');\n return `${sign}$${dollars}.${rest}`;\n}\n","mutants":[{"id":"no-padding","code":"// Splitwise-lite stores money as integer cents.\n// formatMoney(1234) -> \"$12.34\", formatMoney(-505) -> \"-$5.05\"\nfunction formatMoney(cents) {\n const sign = cents < 0 ? '-' : '';\n const abs = Math.abs(cents);\n const dollars = Math.floor(abs / 100);\n const rest = String(abs % 100);\n return `${sign}$${dollars}.${rest}`;\n}\n"},{"id":"sign-lost","code":"// Splitwise-lite stores money as integer cents.\n// formatMoney(1234) -> \"$12.34\", formatMoney(-505) -> \"-$5.05\"\nfunction formatMoney(cents) {\n const sign = '';\n const abs = Math.abs(cents);\n const dollars = Math.floor(abs / 100);\n const rest = String(abs % 100).padStart(2, '0');\n return `${sign}$${dollars}.${rest}`;\n}\n"},{"id":"rounds-dollars","code":"// Splitwise-lite stores money as integer cents.\n// formatMoney(1234) -> \"$12.34\", formatMoney(-505) -> \"-$5.05\"\nfunction formatMoney(cents) {\n const sign = cents < 0 ? '-' : '';\n const abs = Math.abs(cents);\n const dollars = Math.round(abs / 100);\n const rest = String(abs % 100).padStart(2, '0');\n return `${sign}$${dollars}.${rest}`;\n}\n"}],"starter":{"js":"describe('formatMoney', () => {\n test('formats dollars and cents', () => {\n expect(formatMoney(1234)).toBe('$12.34');\n });\n\n // Add tests for: single-digit cents, negative amounts,\n // and amounts where the cents are 50 or more.\n});\n"},"solution":{"js":"describe('formatMoney', () => {\n test('formats dollars and cents', () => {\n expect(formatMoney(1234)).toBe('$12.34');\n });\n\n test('pads single-digit cents with a zero', () => {\n expect(formatMoney(505)).toBe('$5.05');\n });\n\n test('puts the minus sign before the dollar sign', () => {\n expect(formatMoney(-505)).toBe('-$5.05');\n });\n\n test('keeps the dollars when the cents are 50 or more', () => {\n expect(formatMoney(199)).toBe('$1.99');\n });\n\n test('formats zero', () => {\n expect(formatMoney(0)).toBe('$0.00');\n });\n});\n"},"checks":[{"id":"passes","suite":"subject"},{"id":"catches-no-padding","suite":"no-padding"},{"id":"catches-sign-lost","suite":"sign-lost"},{"id":"catches-rounds-dollars","suite":"rounds-dollars"}],"title":"أول اختبارات لـ formatMoney","prompt":"في تبويب الـ subject توجد الدالة formatMoney(cents)، التي تحوّل السنتات الصحيحة إلى نص بالدولار: 1234 تصبح "$12.34" و-505 تصبح "-$5.05".
في الكود المبدئي اختبار واحد. أضف اختبارات حتى تنجح مجموعتك على الكود الحقيقي وتفشل على كل واحدة من ثلاث نسخ معطوبة أخفاها المدقّق: واحدة تنسى إكمال السنتات المكوّنة من رقم واحد بصفر، وواحدة تُسقط إشارة السالب، وواحدة تقرّب الدولارات بدل أن تأخذ الجزء الصحيح منها. استخدم describe وtest وexpect(...).toBe(...)؛ لا يوجد ما تستورده.
كل اختبار يستهدف قاعدة واحدة من قواعد التنسيق، ويختار مدخلًا يتغيّر فيه الناتج لو انكسرت تلك القاعدة. المدخل 1234 وحده لا يميّز بين وجود إكمال الصفر وغيابه (فـ 34 مكوّنة من رقمين)، ولا بين أخذ الجزء الصحيح والتقريب (فـ 34 تُقرَّب إلى الأسفل في الحالتين)، ولهذا مرّت كل الأخطاء من المجموعة المبدئية. الأمثلة الجيدة مميِّزة: اختر مدخلات يؤدّي فيها خطأ معقول إلى إجابة مختلفة. 505 تختبر إكمال الصفر، و-505 تختبر الإشارة، و199 تختبر أخذ الجزء الصحيح. والصفر إضافة رخيصة تحمي أكثر قيمة تُعرض في التطبيق.