إعداد Vitest

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

التثبيت والتشغيل

في مشروع Vite (React أو Vue أو JavaScript صرف، لا فرق):

npm install --save-dev vitest

أضف سكربتين إلى package.json:

{
  "scripts": {
    "test": "vitest",
    "test:run": "vitest run"
  }
}

يبدأ 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) {
  const sign = cents < 0 ? '-' : '';
  const abs = Math.abs(cents);
  const dollars = Math.floor(abs / 100);
  const rest = String(abs % 100).padStart(2, '0');
  return `${sign}${dollars}.${rest}`;
}

ضع الاختبار بجوارها، باسم يجعل Vitest تجده:

import { describe, test, expect } from 'vitest';
import { formatMoney } from './money.js';

describe('formatMoney', () => {
  test('formats dollars and cents', () => {
    expect(formatMoney(1234)).toBe('$12.34');
  });

  test('pads single-digit cents', () => {
    expect(formatMoney(505)).toBe('$5.05');
  });
});

يجمع 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" />
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  test: {
    environment: 'node',
  },
});

سطر الشرطات المائلة الثلاث يعطي محرّرك الأنواع الخاصة بالمفتاح test. وenvironment: 'node' هو الافتراضي، كتبناه هنا صراحةً كي تعرف أن هذا المفتاح موجود. المنطق الصافي مثل تنسيق المبالغ يعمل في Node، وهو سريع. أما الاختبارات التي تحتاج إلى document (وستكتبها في القسم 3) فتستخدم jsdom أو happy-dom، وكلاهما يُثبَّت على حدة، ويُضبط إمّا هنا أو لكل ملف بتعليق // @vitest-environment jsdom في أعلاه.

سترى أيضًا globals: true في بعض المشاريع. هذا الخيار يجعل test وexpect متاحين دون استيراد، على طريقة Jest. لكن الاستيراد الصريح هو الافتراضي، ويتوافق بشكل أفضل مع المحرّرات وأدوات الـ lint، لذا تستوردهما هذه الدورة.

تشغيل جزء من مجموعة الاختبارات

كلما كبرت مجموعة الاختبارات، سترغب في تشغيل جزء أصغر منها:

npx vitest money            # only files whose path contains "money"
npx vitest -t "pads"        # only tests whose name matches "pads"
npx 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 الحقيقي ويجب أن تنجح، ثم على بضع نسخ معطوبة عمدًا ويجب أن تفشل على كل واحدة منها.

ينظر الدرس القادم عن قرب في ما يوضع داخل الاختبار، وفي كيفية قراءة المخرجات حين يفشل.