تهيئة وإعداد Vitest

أهلاً بك في مرحلة التطبيق العملي! 

بعد أن تعرفنا في الدرس السابق على الأسباب التي تجعل Vitest خيارًا ممتازًا لاختبارات الوحدات في مشاريع JavaScript الحديثة، حان الوقت الآن لنشمر عن سواعدنا ونقوم بإعداده وتثبيته في مشروعنا. في هذا الدرس، سنقوم معًا بتثبيت Vitest خطوة بخطوة، ونتعلم كيفية تكوينه، ونهيئ بنية المشروع لنكون على أتم الاستعداد لكتابة أول اختبار لنا في الدرس القادم.

قد تبدو عملية الإعداد مهمة شاقة في البداية، لكن من أجمل ميزات Vitest هي بساطة وسرعة إعداده. هيا بنا نبدأ!

المتطلبات الأساسية

قبل أن نبدأ، تأكد من أن لديك مشروع Node.js جاهز. كل ما تحتاجه هو مجلد يحتوي على ملف package.json. إذا كنت تتابع معنا منذ بداية الدورة، فيجب أن يكون لديك "المشروع الابتدائي" جاهزًا. إن لم يكن، يمكنك إنشاء واحد بسرعة عبر تنفيذ الأمر التالي في الطرفية (Terminal):

npm init -y

هذا الأمر سيقوم بإنشاء ملف package.json افتراضي لك. سنستخدم مدير الحزم npm في جميع أمثلتنا، ولكن يمكنك استخدام yarn أو pnpm إذا كنت تفضل ذلك.

الخطوة الأولى: تثبيت Vitest

أول خطوة هي تثبيت Vitest كـ "تبعية تطوير" (Development Dependency) في مشروعنا. هذا يعني أن الحزمة ضرورية فقط أثناء عملية التطوير والاختبار، ولن يتم تضمينها في الكود النهائي الذي سيصل للمستخدم (Production Build).

لتثبيت Vitest، افتح الطرفية في جذر مشروعك ونفّذ الأمر التالي:

npm install -D vitest

بعد اكتمال التثبيت، إذا فتحت ملف package.json، ستجد شيئًا مشابهًا لهذا:

{
  "name": "my-awesome-project",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "vitest": "^1.0.0" 
  }
}

لاحظ وجود vitest ضمن devDependencies. هذا يؤكد أن التثبيت تم بنجاح.

الخطوة الثانية: إعداد أوامر الاختبار (Test Scripts)

الطريقة المعتادة لتشغيل الاختبارات في أي مشروع JavaScript هي من خلال قسم scripts في ملف package.json. هذا يجعل عملية تشغيل الاختبارات موحدة وسهلة التذكر للجميع في الفريق. لنقم بتحديث هذا القسم.

استبدل السطر الافتراضي لـ test بالآتي:

"scripts": {
  "test": "vitest"
}

الآن، كلما قمت بتشغيل npm test في الطرفية، سيقوم npm بتنفيذ الأمر vitest، والذي بدوره سيبحث عن ملفات الاختبار في مشروعك ويشغلها.

وضع المراقبة في Vitest

من الميزات القوية في Vitest هي "وضع المراقبة" (Watch Mode)، والذي يعيد تشغيل الاختبارات تلقائيًا عند حفظ أي تغيير في ملفاتك. هذا يسرّع دورة التطوير بشكل كبير. يمكنك إضافة أمر خاص له:

"scripts": {
  "test": "vitest",
  "test:watch": "vitest --watch"
}

الآن يمكنك تشغيل npm run test:watch لبدء الاختبارات في وضع المراقبة.

الخطوة الثالثة: إنشاء ملف الإعدادات (Configuration File)

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

في جذر مشروعك، قم بإنشاء ملف جديد باسم vitest.config.js (أو vitest.config.ts إذا كنت تستخدم TypeScript).

# For macOS/Linux
touch vitest.config.js

# For Windows
echo. > vitest.config.js

داخل هذا الملف، سنضع الإعدادات الأساسية. يستخدم Vitest نفس صيغة الإعدادات الخاصة بـ Vite، مما يجعله مألوفًا لمطوري الواجهات الأمامية.

// vitest.config.js
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    // Configuration options go here
  },
});

لنجعل حياتنا أسهل، دعنا نضف أحد أهم الإعدادات وهو globals. هذا الإعداد يسمح لنا باستخدام دوال Vitest الأساسية مثل test, describe, expect في ملفات الاختبار مباشرة دون الحاجة إلى استيرادها في كل مرة.

// vitest.config.js
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    globals: true,
  },
});

تفعيل هذا الخيار يجعل كتابة الاختبارات أسرع وأكثر شبهًا بأطر عمل أخرى مثل Jest.

الخطوة الرابعة: تنظيم بنية ملفات الاختبار

الآن بعد أن أصبح كل شيء جاهزًا، أين نضع ملفات الاختبار الخاصة بنا؟ Vitest ذكي بما يكفي للبحث عن الملفات التي تتبع أنماطًا شائعة. بشكل افتراضي، سيعتبر أي ملف ينتهي بـ:

• .test.js
• .spec.js
• (أو ما يقابلها في TypeScript مثل .test.ts و .spec.ts)

على أنه ملف اختبار.

هناك طريقتان شائعتان لتنظيم هذه الملفات:

1. مجلد __tests__: إنشاء مجلد خاص بالاختبارات على مستوى جذر المشروع أو داخل مجلد src ووضع كل ملفات الاختبار فيه.
2. الملفات المجاورة (Colocation): وضع ملف الاختبار بجوار الملف الذي يختبره مباشرة. على سبيل المثال، يكون ملف math.test.js بجوار math.js.

سنعتمد الطريقة الثانية في هذه الدورة لأنها تسهل العثور على الاختبارات المتعلقة بملف معين وتحافظ على تنظيم المشروع كلما كبر حجمه.

لنتخيل أن بنية مشروعنا تبدو هكذا:

my-awesome-project/
├── src/
│   └── utils/
│       └── math.js
├── node_modules/
├── package.json
└── vitest.config.js

لإضافة اختبار لملف math.js، سننشئ ملفًا جديدًا بجواره:

my-awesome-project/
├── src/
│   └── utils/
│       ├── math.js
│       └── math.test.js  <-- Here is our test file!
├── node_modules/
├── package.json
└── vitest.config.js

بهذه الطريقة، يكون كل شيء منظمًا وفي مكانه.

تشغيل Vitest لأول مرة

لقد قمنا بتثبيت الحزمة، وأعددنا الأوامر، وجهزنا ملف الإعدادات، وفهمنا أين سنضع ملفاتنا. حان وقت الاختبار الحقيقي! لنقم بتشغيل الأمر الذي أعددناه:

npm test

ماذا تتوقع أن تكون النتيجة؟ نظرًا لأننا لم نكتب أي اختبارات بعد (فقط أنشأنا ملفًا فارغًا ربما)، سيقوم Vitest بالبحث في المشروع ثم سيعرض رسالة تفيد بأنه لم يجد أي اختبارات لتشغيلها.

No test files found, exiting with code 0

إذا رأيت هذه الرسالة، فهذا خبر ممتاز! هذا يعني أن Vitest تم إعداده بنجاح وهو يعمل بشكل صحيح وينتظر منك أن تبدأ بكتابة الاختبارات. لقد نجحت في بناء الأساس.

خلاصة

تهانينا! لقد قمت بإعداد بيئة اختبار احترافية باستخدام Vitest. لنلخص ما أنجزناه:

1. ثبتنا Vitest كتبعية تطوير في مشروعنا.
2. أضفنا أوامر scripts في ملف package.json لتسهيل تشغيل الاختبارات.
3. أنشأنا ملف إعدادات vitest.config.js وقمنا بتفعيل خيار globals لتسهيل الكتابة.
4. تعلمنا أفضل الممارسات لتنظيم ملفات الاختبار داخل بنية المشروع.
5. تأكدنا من أن كل شيء يعمل بتشغيل Vitest لأول مرة.

أنت الآن جاهز تمامًا للخطوة التالية والأكثر إثارة: كتابة أول اختبار وحدة حقيقي. هذا ما سنفعله في الدرس القادم!