نموذج المصروفات هو المكان الذي يلتقي فيه Splitwise-lite بالناس الحقيقيين، والناس الحقيقيون يفعلون أشياء فوضوية: يتنقّلون بين الحقول بمفتاح Tab، ويلصقون " 45.50 "، وينقرون “Add” وحقل المبلغ ما زال فارغًا، وينقرون نقرًا مزدوجًا. لا يستطيع unit test لـ parseAmount أن يخبرك إن كان النموذج يربط كل ذلك بشكل صحيح. أما الاختبار الذي يستخدم النموذج كما يستخدمه إنسان فيستطيع.
تأتي Testing Library بطريقتين للتفاعل.
\nfireEvent (من @testing-library/dom) يُطلق حدث DOM واحدًا بالضبط. fireEvent.click(button) يرسل click. وfireEvent.change(input, { target: { value: '45.50' } }) يضبط القيمة ويرسل change. إنه سريع ودقيق، لكنه ليس ما يحدث حين ينقر إنسان أو يكتب.
user-event (من @testing-library/user-event) يحاكي التفاعل نفسه. user.click(button) يُنتج أحداث المؤشّر والفأرة، وينقل التركيز، ثم يُطلق click، ويرفض النقر على زر معطّل أو مخفيّ تحت pointer-events: none، تمامًا كالمتصفّح الحقيقي. وuser.type(input, '45.50') ينقر الحقل، ثم يرسل لكل حرف keydown وkeypress وinput وkeyup.
اجعل user-event خيارك الافتراضي. ولا تلجأ إلى fireEvent إلا مع أحداث لا يحاكيها user-event، مثل حدث مخصّص أو scroll.
في النموذج حقلان لهما تسميتان، وزر “Add expense”، ومنطقة للتنبيه. إليك المسار السعيد، مكتوبًا بالطريقة التي ستصفه بها لزميل:
\n// @vitest-environment jsdom\nimport { afterEach, test, expect, vi } from 'vitest';\nimport { screen } from '@testing-library/dom';\nimport userEvent from '@testing-library/user-event';\nimport { mountExpenseForm } from './expense-form.js';\n\nafterEach(() => {\n document.body.innerHTML = '';\n});\n\ntest('adds a valid expense in cents and clears the form', async () => {\n const user = userEvent.setup();\n const onAdd = vi.fn();\n mountExpenseForm(document.body, onAdd);\n\n await user.type(screen.getByRole('textbox', { name: 'Description' }), 'Dinner');\n await user.type(screen.getByRole('textbox', { name: 'Amount' }), '45.50');\n await user.click(screen.getByRole('button', { name: 'Add expense' }));\n\n expect(onAdd).toHaveBeenCalledWith({ description: 'Dinner', amountCents: 4550 });\n expect(screen.getByRole('textbox', { name: 'Amount' }).value).toBe('');\n});لاحظ ثلاثة أشياء. يأتي userEvent.setup() أولًا ويعطيك جلسة user تتتبّع حالة لوحة المفاتيح والمؤشّر عبر الاستدعاءات. وكل تفاعل يُنتظَر بـ await: فدوال user-event غير متزامنة، وبدون await تعمل الـ assertions قبل أن تنتهي الكتابة. والـ assertions تتعلّق بالنتائج: ما استلمته onAdd (العقد مع بقية التطبيق) وما يراه المستخدم الآن.
ومستخدمو لوحة المفاتيح مهمّون أيضًا. ينقل await user.tab() التركيز كما يفعل مفتاح Tab، ويضغط await user.keyboard('{Enter}') مفتاح Enter، فتستطيع اختبار أن النموذج يعمل دون فأرة.
يحاكي user-event السلوك الافتراضي للمتصفّح في التفاعل، لكنه لا يرى تخطيط الـ CSS لديك. لن يلاحظ أن نافذة منبثقة تغطّي الزر بصريًا، أو أن زر “Add expense” خارج الشاشة على الهاتف. ليس في jsdom محرّك تخطيط، فكل الأحجام والمواقع أصفار. هذه مهام اختبارات الـ end-to-end في متصفّح حقيقي، وهذا ما يتّجه إليه القسم 4. أما في اختبارات الوحدات والمكوّنات، فيعطيك user-event تسلسل الأحداث الصحيح وسلوك التركيز الصحيح، وهذا يغطّي الغالبية العظمى من أخطاء النماذج.
\nتعيش معظم أخطاء النماذج في معالجة الأخطاء، فأعطها على الأقل عدد الاختبارات نفسه. كتابة abc كمبلغ ثم النقر على “Add expense” يجب أن:
role="alert"، وهو ما تعلنه قارئات الشاشة؛onAdd؛test('explains an invalid amount and keeps the input', async () => {\n const user = userEvent.setup();\n const onAdd = vi.fn();\n mountExpenseForm(document.body, onAdd);\n\n await user.type(screen.getByRole('textbox', { name: 'Description' }), 'Taxi');\n await user.type(screen.getByRole('textbox', { name: 'Amount' }), 'abc');\n await user.click(screen.getByRole('button', { name: 'Add expense' }));\n\n expect(screen.getByRole('alert').textContent).toMatch('Not a valid amount');\n expect(onAdd).not.toHaveBeenCalled();\n expect(screen.getByRole('textbox', { name: 'Amount' }).value).toBe('abc');\n});كل assertion يحمي من خطأ مختلف. احذف فحص التنبيه، فينجح الفشل الصامت. احذف not.toHaveBeenCalled، فينجح نموذج يحفظ قيمًا عبثية. احذف الأخير، فينجح نموذج يمسح ما كتبه المستخدم.
لا توجد حزمة user-event في البيئة المعزولة، لذا يتضمّن الكود المبدئي للتمرين دالتين مساعدتين صغيرتين: typeInto(element, text)، التي تضع التركيز على الحقل وترسل أحداث المفاتيح والإدخال لكل حرف، وclickOn(element)، التي ترسل تسلسل المؤشّر والفأرة، وتضع التركيز وتنقر (ولا تفعل شيئًا مع زر معطّل). كلتاهما متزامنة، فلا تضع قبلهما await. وتمنع البيئة المعزولة أيضًا الإرسال الحقيقي للنماذج، لذا يستمع العنصر إلى نقر الزر بدل حدث submit؛ أما في تطبيقك، فـ <form> حقيقي مع معالِج submit أفضل، لأنه يعطيك الإرسال بمفتاح Enter دون جهد.
بعد ذلك، أصعب جزء في اختبار الواجهة: الأشياء التي تحدث لاحقًا.
\n","toc":[{"id":"sec-1","text":"fireEvent مقابل user-event","level":2},{"id":"sec-2","text":"اختبار نموذج المصروفات","level":2},{"id":"sec-3","text":"ما لن يفعله user-event من أجلك","level":3},{"id":"sec-4","text":"المسار غير السعيد هو معظم العمل","level":2},{"id":"sec-5","text":"في ساحة التجربة","level":2}],"takeaways":["يُطلقfireEvent حدث DOM واحدًا؛ أما user-event فيؤدّي التسلسل الكامل الذي يُحدثه إنسان حقيقي (المؤشّر، والتركيز، وkeydown، وinput، وkeyup، والنقر).","أنشئ جلسة بـ userEvent.setup() وضع await قبل كل تفاعل، لأن دوال user-event غير متزامنة.","اختبر النموذج من خلال نتائجه: معاملات الدالة الراجعة (callback)، والخطأ الذي سيقرؤه المستخدم، وحالة الحقول بعد ذلك.","اختبر المسار غير الصالح بالعناية نفسها التي تختبر بها الصالح؛ “لم يحدث شيء” سلوك يجب تأكيده."],"further":[{"title":"Testing Library — user-event introduction","url":"https://testing-library.com/docs/user-event/intro"},{"title":"Testing Library — Firing events","url":"https://testing-library.com/docs/dom-testing-library/api-events"},{"title":"Testing Library — user-event setup","url":"https://testing-library.com/docs/user-event/setup"}],"quiz":[{"q":"ينسّق حقل المبلغ المدخلات عند كل keydown. يستخدم اختبار fireEvent.change(input, { target: { value: '45.50' } })، فلا يعمل كود التنسيق أبدًا. لماذا؟
fireEvent.change القيمة ويُطلق حدث change واحدًا، دون أي أحداث مفاتيح.","why":"صحيح. لم يضغط شيء أي مفتاح، فلا تعمل معالِجات keydown أبدًا. أما await user.type(input, '45.50') فيُنتج أحداث مفاتيح لكل حرف."},{"text":"fireEvent لا يعمل إلا مع مكوّنات React.","why":"يأتي fireEvent من @testing-library/dom ويعمل مع أي DOM؛ المشكلة في نوع الأحداث التي يرسلها."},{"text":"أحداث change لا تنتشر صعودًا (bubble) في jsdom.","why":"الانتشار ليس المشكلة؛ فمعالِج keydown لا ينتظر حدث change أصلًا."}],"answer":0},{"q":"ما المشكلة في هذا الاختبار؟
\ntest('adds the expense', () => {\n const user = userEvent.setup();\n mountExpenseForm(document.body, onAdd);\n user.type(screen.getByRole('textbox', { name: 'Amount' }), '12');\n user.click(screen.getByRole('button', { name: 'Add expense' }));\n expect(onAdd).toHaveBeenCalled();\n});userEvent.setup() داخل beforeEach.","why":"استدعاء setup() في بداية كل اختبار هو النمط الموصى به؛ ولا حاجة إلى hook."},{"text":"لا يستطيع getByRole إيجاد حقول الإدخال؛ يجب استخدام getByTestId.","why":"لحقول الإدخال الدور textbox، ومع وجود تسمية يصبح لها اسم قابل للوصول، فـ getByRole هو الـ query الصحيح."},{"text":"التفاعلات بلا await، فيعمل الـ assertion قبل انتهاء الكتابة والنقر.","why":"صحيح. دوال user-event تعيد promises؛ اجعل الاختبار async وضع await قبل كل استدعاء."}],"answer":2},{"q":"كتابة 'abc' في حقل المبلغ ثم النقر على “Add expense” يجب أن يُظهر خطأً. أيّ مجموعة assertions تختبر هذا المسار على أفضل وجه؟
onAdd بقيمة عبثية ستنجح أيضًا."},{"text":"التنبيه يعرض الرسالة، وonAdd لم تُستدعَ، والنص المكتوب ما زال في الحقل.","why":"صحيح. كل assertion يحمي من خطأ مختلف: الفشل الصامت، وحفظ مصروف سيئ، ومسح ما كتبه المستخدم."},{"text":"onAdd لم تُستدعَ.","why":"النسخة التي تتجاهل النقر بصمت تنجح في هذا أيضًا؛ وسيبقى المستخدم يخمّن ما حدث."}],"answer":1}],"exercise":{"kind":"web","mode":"test","subject":"function parseAmount(input) {\n const text = String(input).trim();\n if (!/^\\d+(\\.\\d{1,2})?$/.test(text)) throw new Error(`Not a valid amount: \"${input}\"`);\n const [whole, fraction = ''] = text.split('.');\n const cents = Number(whole) * 100 + Number(fraction.padEnd(2, '0'));\n if (cents === 0) throw new Error('Amount must be greater than zero');\n return cents;\n}\n\n// Mounts the \"Add expense\" form into container.\n// - Text fields labelled \"Description\" and \"Amount\", and an\n// \"Add expense\" button.\n// - On click, if valid: calls onAdd({ description, amountCents }) with the\n// trimmed description and the amount in integer cents, hides any error,\n// then clears both fields.\n// - If invalid: shows the reason in the element with role=\"alert\",\n// does NOT call onAdd, and keeps what the user typed.\n// Blank description -> \"Add a description\"; bad amount -> parseAmount's message.\n// (The playground blocks real form submission, so this reacts to the click.)\nfunction mountExpenseForm(container, onAdd) {\n container.innerHTML = `\n تعرض mountExpenseForm(container, onAdd) حقلين تسميتاهما Description وAmount، وزر Add expense. النقرة الصالحة تستدعي onAdd({ description, amountCents }) وتمسح الحقول؛ وغير الصالحة تعرض السبب في role="alert"، ولا تستدعي onAdd، وتُبقي النص المكتوب.
يتضمّن الكود المبدئي بدائل الاستعلامات من التمرين السابق، إضافة إلى typeInto(el, text) وclickOn(el) اللتين تحاكيان user-event (وهما متزامنتان: بلا await). أضف اختبارات حتى تلتقط مجموعتك أربعة أخطاء مخفيّة: نسخة تستدعي onAdd حتى حين يكون المبلغ غير صالح، ونسخة لا تمسح الحقول، ونسخة تمرّر المبلغ بالدولار بدل السنتات، ونسخة لا تعرض التنبيه أبدًا.
expect(onAdd).toHaveBeenCalledWith({ description: 'Dinner', amountCents: 4550 }).","بعد إضافة ناجحة، اقرأ الحقلين مرة أخرى وتحقّق من أن .value تساوي '' في كليهما.","المسار غير الصالح: اكتب ‘abc’ كمبلغ، وانقر، ثم افحص getByRole(container, 'alert').textContent، وexpect(onAdd).not.toHaveBeenCalled()، وأن حقل المبلغ ما زال يحتوي ‘abc’. بدائل الاستعلامات تتخطّى العناصر المخفيّة، تمامًا مثل getByRole الحقيقي."],"explanation":"اختباران، وستة assertions، وأربعة أخطاء. يثبّت toHaveBeenCalledWith({ description: 'Dinner', amountCents: 4550 }) العقد مع بقية التطبيق، فيُفشله خطأ الدولار بدل السنتات (لأنه يرسل 45.5). وفحص الحقلين بعد الإضافة يلتقط النموذج الذي ينسى المسح. وفي المسار غير الصالح، يفشل getByRole(container, 'alert') حين يبقى التنبيه مخفيًّا، لأن العناصر المخفيّة ليست في شجرة إمكانية الوصول، ويلتقط not.toHaveBeenCalled() النموذج الذي يحفظ القيم العبثية رغم ذلك. كل assertion يتعلّق بشيء يراه المستخدم أو يستلمه التطبيق؛ ولا يذكر أيّ منها متغيّرًا داخل العنصر.