تخطّى إلى المحتوى الرئيسي
وضع المتصفح في Vitest لاختبار مكونات React: لماذا تركنا jsdom، والمحاكاة التي تعطّلت

وضع المتصفح في Vitest لاختبار مكونات React: لماذا تركنا jsdom، والمحاكاة التي تعطّلت

November 16, 2026
اختبار البرمجيات
7 دقيقة قراءة

العنوان الرئيسي: يشغّل وضع المتصفح (Browser Mode) في Vitest اختبارات مكونات React داخل صفحة حقيقية في Chromium أو Firefox أو WebKit يقودها Playwright، فيتصرف التخطيط والتركيز (focus) وCSS والمراقِبات (observers) كما يراها المستخدم فعلاً، لا كما يقرّبها jsdom. أصبح وضع المتصفح مستقراً منذ Vitest 4.0، وتكلفة الانتقال تقع في المحاكاة (mocks) وتهيئة البيئة، لا في التأكيدات (assertions).

لسنوات كانت اختبارات مكونات React لدينا تعمل في jsdom، وكان بعضها ينجح بينما المكوّن معطّل: قائمة منسدلة تظهر خارج الشاشة على العروض الضيقة، وزر إرسال مختبئ تحت تذييل ثابت، ونافذة حوار تسمح للتركيز بالهروب إلى الصفحة خلفها. jsdom، وهو تطبيق بلغة JavaScript لمعايير DOM وHTML يعمل في Node.js، لا يملك محرك تخطيط، لذلك لم يكن ممكناً أن يظهر أي من هذه الأعطال في اختبار. في Devya نقلنا الاختبارات التي تعتمد على التخطيط والتركيز والإدخال الحقيقي إلى وضع المتصفح في Vitest، وأبقينا الباقي في Node.

أهم النقاط

• متصفح حقيقي بنفس أداة التشغيل: ينفّذ وضع المتصفح في Vitest ملفات الاختبار داخل صفحة متصفح حقيقية، ومع مزوّد @vitest/browser-playwright يشغّل Playwright متصفح Chromium أو Firefox أو WebKit ويتحكم فيه.

• jsdom لا يقيس شيئاً: لا يملك jsdom محرك تخطيط، لذا تُرجع getBoundingClientRect() أصفاراً، وأي اختبار يتعلق بالموضع أو الفيضان أو التداخل يختبر بديلاً وهمياً.

• النقرة يجب أن تكون ممكنة: مع مزوّد Playwright تمر نقرات الـ locator عبر فحوص قابلية التفاعل (actionability) في Playwright، فيفشل الاختبار عند النقر على زر يغطيه عنصر آخر تماماً كما يفشل المستخدم.

• التأكيدات تعيد المحاولة: تستطلع expect.element() الـ locator حتى ينجح التأكيد أو تنتهي المهلة، وهذا يغني عن معظم استدعاءات waitFor وfindBy.

• قسّم ولا تنقل كل شيء: يبقى المنطق الصافي في بيئة node، وتشغّل خاصية projects في Vitest المجموعتين بأمر vitest واحد.

ما الذي يخطئ فيه jsdom عند اختبار مكونات React؟

يخطئ jsdom في كل ما يعتمد على العرض الفعلي، لأنه يحلّل HTML وينفّذ واجهات DOM لكنه لا يحسب التخطيط ولا يرسم أي بكسل. هذه هي الفجوات التي واجهها فريقنا أكثر من غيرها:

• تُرجع getBoundingClientRect() وoffsetWidth وscrollHeight القيمة 0، فلا يمكن التحقق من منطق تموضع النوافذ المنبثقة والتلميحات والقوائم الافتراضية (virtualized lists).

• الواجهات IntersectionObserver وResizeObserver وmatchMedia غير مطبّقة، فتستبدلها ملفات التهيئة ببدائل وهمية، والبديل الوهمي يُرجع ما توقّعه كاتب الاختبار.

• استعلامات الوسائط (media queries) واستعلامات الحاويات (container queries) لا تُطبَّق أبداً، فتبقى النسخ المتجاوبة غير مرئية للاختبار.

• ترسل fireEvent.click() الحدث مباشرة إلى العنصر الهدف سواء استطاع المستخدم الوصول إليه أم لا، رغم وجود عناصر متداخلة أو pointer-events: none أو موضع خارج الشاشة.

كان ملف التهيئة الخاص بـ jsdom لدينا قد تضخّم بكتلة من الـ polyfills لهذه الواجهات تحديداً. كل polyfill كان موضعاً يتفق فيه المكوّن مع بديل وهمي كتبناه بأنفسنا، وهذا عكس الغرض من الاختبار. فأصبحت تلك الكتلة قائمتنا للاختبارات التي ننقلها أولاً.

كيف نُعدّ وضع المتصفح في Vitest لمشروع React؟

يحتاج وضع المتصفح في Vitest إلى ثلاث إضافات غير Vitest نفسه: حزمة مزوّد (@vitest/browser-playwright)، ومُصيّر خاص بالإطار (vitest-browser-react)، وملف المتصفح التنفيذي الذي ينزّله Playwright بالأمر npx playwright install chromium. منذ Vitest 4 أصبح المزوّد دالة مصنعية هي playwright() تُستورد من حزمتها الخاصة، بدلاً من الخيار النصي القديم provider: 'playwright'.

نحتفظ باختبارات node واختبارات المتصفح في ملف vitest.config.ts واحد باستخدام projects في Vitest، وهو الخيار الذي حلّ محل ملف vitest.workspace المنفصل في Vitest 3.2. مشروع unit يشغّل كل ملف ينتهي بـ .test.ts داخل المجلد src مع ضبط environment على node. ومشروع browser يشغّل كل ملف ينتهي بـ .browser.test.tsx داخل المجلد src مع ضبط browser.enabled على true وprovider على playwright() وheadless على true وإدخال chromium واحد في browser.instances. ويضبط المشروعان extends: true ليرثا إضافات Vite الجذرية، ومنها @vitejs/plugin-react.

يستورد ملف التهيئة في مشروع المتصفح ورقة الأنماط العامة للتطبيق، لأن اختبار المتصفح على markup بلا أنماط يقيس تخطيطاً لا يصل إلى أي مستخدم. ومع Tailwind CSS v4 يعني ذلك أيضاً إضافة @tailwindcss/vite إلى إعدادات Vitest حتى تُبنى الأصناف المساعدة.

ما الذي يتغير في كود الاختبار نفسه؟

تتحول الاستعلامات إلى locators، ويصبح التفاعل إدخالاً حقيقياً ننتظره بـ await، وتعيد التأكيدات المحاولة تلقائياً. تقوم الدالة render() من vitest-browser-react بتركيب المكوّن في المستند الحقيقي وتُرجع locators بأسماء Testing Library المألوفة: getByRole وgetByLabelText وgetByText.

اختبار نموذجي يعرض combobox، وينقر على locator حقل الإدخال، ويرسل ArrowDown ثم ArrowDown ثم Enter عبر userEvent.keyboard()، ثم ينتظر expect.element(input).toHaveValue('Giza') وexpect.element(input).toHaveFocus(). واختبار ثانٍ يستدعي page.viewport(360, 640) ويفتح القائمة ويتحقق من أن قيمة getBoundingClientRect().right للقائمة لا تتجاوز 360 بكسل. الاختبار الثاني مستحيل في jsdom: لا توجد نافذة عرض لتغيير حجمها ولا مستطيل لقياسه.

• userEvent من vitest/browser ليس @testing-library/user-event. حزمة Testing Library تحاكي الأحداث بلغة JavaScript، أما استيراد Vitest فيرسل الإدخال عبر المزوّد، فيُنتج المتصفح أحداثاً موثوقة (trusted events) مع تركيز حقيقي وسلوك افتراضي حقيقي.

• كل تفاعل هو Promise. نسيان await قبل click() يجعله يتسابق مع التأكيد التالي، لذلك نفحص بأداة lint الوعود غير المنتظَرة في ملفات اختبارات المتصفح.

• تستطلع expect.element() باستمرار، فهي تعيد الاستعلام عن الـ locator حتى ينجح المطابِق أو تنتهي المهلة، فلا تحتاج التأكيدات على حالة تستقر بعد انتقال إلى انتظار يدوي.

ما الاختبارات التي يجب أن تبقى خارج المتصفح؟

لا ينتمي إلى وضع المتصفح في Vitest إلا الاختبارات التي تحتاج إلى العرض الفعلي، لأن كل مشروع متصفح يضيف زمن تشغيل المتصفح وملف Playwright التنفيذي إلى كل تشغيل في CI. هذا هو التقسيم الذي نعتمده:

• الدوال الصافية والـ reducers ومخططات Zod ودوال التنسيق: Vitest مع بيئة node. لا حاجة إلى DOM والتغذية الراجعة هي الأسرع.

• المكونات التي يهم فيها النص والأدوار وحالة ARIA فقط: jsdom أو وضع المتصفح. كلاهما دقيق هنا، لذا ننقلها عند سنوح الفرصة.

• التخطيط والتداخل وترتيب التركيز والمراقِبات واستعلامات الوسائط والحاويات: وضع المتصفح في Vitest، لأن jsdom لا يستطيع تمثيلها.

• مكونات الخادم (Server Components) وServer Actions والتوجيه والـ middleware: اختبارات Playwright الشاملة (end-to-end) على next start، لأن Vite لا يشغّل مترجم Next.js ولا بيئة خادمه.

القاعدة الأخيرة مهمة لمشاريع Next.js. يقدّم وضع المتصفح في Vitest الملفات عبر Vite، فهو يختبر مكونات العميل بمعزل عن غيرها، لا الـ App Router. وكل ما يحتاج إلى خادم Next.js مكانه الاختبارات الشاملة.

ما الذي تعطّل عندما نقلنا الاختبارات إلى المتصفح؟

تعطّلت المحاكاة لا التأكيدات، وأربعة إصلاحات غطّت كل شيء تقريباً:

• vi.spyOn على صادرات الوحدات: كائنات namespace الخاصة بوحدات ES الأصلية في المتصفح غير قابلة للكتابة، لذا يفشل vi.spyOn(api, 'fetchCities'). الحل هو vi.mock('./api', { spy: true }) الذي يُبقي التنفيذ الحقيقي لكنه يلفّ كل تصدير بـ spy يمكن تجاوزه عبر vi.mocked(fetchCities).mockResolvedValue().

• وحدات خاصة بـ Next.js: ترمي useRouter() من next/navigation خطأً خارج شجرة App Router، وتعتمد next/font على مترجم Next.js. نحاكي next/navigation في كل ملف اختبار، ونُبقي المكونات التي تستورد next/font خارج اختبارات المتصفح.

• process.env غير موجود في المتصفح: الكود الذي يقرأ process.env.NEXT_PUBLIC_API_URL ينهار في صفحة يقدّمها Vite. وإدخال define في مشروع المتصفح يستبدل هذه المراجع وقت التحويل.

• الحالة تبقى بين الاختبارات في الملف الواحد: يزيل vitest-browser-react المكونات المعروضة بين الاختبارات، لكن localStorage والكوكيز والذواكر المؤقتة على مستوى الوحدة تبقى، لذا نمسحها في beforeEach.

في CI نثبّت المتصفح الذي تستخدمه الحزمة فقط بالأمر npx playwright install --with-deps chromium. يستطيع وضع المتصفح في Vitest حفظ لقطة شاشة للصفحة الفاشلة عبر الخيار browser.screenshotFailures، وأضاف Vitest 4 الخيار browser.trace لتسجيل آثار Playwright، فيصل البناء الفاشل ومعه دليل لا مجرد stack trace.

الأسئلة الشائعة

س: هل وضع المتصفح في Vitest مستقر بما يكفي لحزم اختبارات الإنتاج؟

ج: نعم. خرج وضع المتصفح في Vitest من الحالة التجريبية في Vitest 4.0 الصادر في أكتوبر 2025، وتصدر حزم المزوّدين مثل @vitest/browser-playwright بأرقام إصدارات Vitest نفسها.

س: هل يحل وضع المتصفح في Vitest محل اختبارات Playwright الشاملة؟

ج: لا. يركّب وضع المتصفح في Vitest مكوّناً واحداً في صفحة يقدّمها Vite، بينما تقود اختبارات Playwright الشاملة التطبيق بأكمله، بما في ذلك العرض على الخادم والتوجيه والواجهة الخلفية.

س: هل يمكننا الإبقاء على استعلامات React Testing Library؟

ج: في الغالب نعم. توفّر vitest-browser-react الاستعلامات getByRole وgetByLabelText وgetByText وما شابهها على شكل locators، فتنتقل أسطر الاستعلام تقريباً دون تغيير، لكن التفاعلات والتأكيدات يجب أن تصبح منتظَرة بـ await.

س: ما المتصفحات التي يدعمها وضع المتصفح في Vitest؟

ج: مع @vitest/browser-playwright يعمل على Chromium وFirefox وWebKit، وكل إدخال في browser.instances يعيد تشغيل الاختبارات نفسها في ذلك المتصفح. المزوّدان الآخران هما @vitest/browser-webdriverio و@vitest/browser-preview، ويستخدم مزوّد preview متصفحك الشخصي وهو مخصص للتصحيح المحلي لا لـ CI.

س: هل يستطيع وضع المتصفح في Vitest اختبار مكونات الخادم في Next.js؟

ج: لا. يقدّم وضع المتصفح في Vitest الكود عبر Vite داخل صفحة متصفح، بينما تحتاج مكونات الخادم غير المتزامنة إلى بيئة خادم Next.js، لذلك نغطيها باختبارات Playwright الشاملة على نسخة إنتاج مبنية.