{"id":"l-tj-3-1","courseId":"testing-javascript","lang":"ar","kind":"lesson","summary":"تجد العناصر في اختبارات الـ DOM بالطريقة التي يجدها بها المستخدمون والتقنيات المساعدة، باستخدام استعلامات Testing Library بالدور والتسمية والنص، وفق ترتيب الأولوية الموصى به.","html":"

إليك اختبارًا وجدته في قاعدة كود العام الماضي: document.querySelector('.card > div:nth-child(2) span.amount-red'). انكسر حين غيّر مصمّم لون المبالغ السالبة. لم ينكسر شيء مما يراه المستخدم، باستثناء اللون، الذي لم يختبره أحد أصلًا. كان الاختبار مرتبطًا بشكل الـ DOM وبالـ CSS، لا بما تقوله الصفحة.

\n

المبدأ الموجّه

\n

فكرة Testing Library الجوهرية تتّسع لها جملة واحدة: كلما أشبهت اختباراتك الطريقة التي يُستخدم بها برنامجك، زادت الثقة التي تمنحك إياها. لا يرى المستخدمون أسماء الأصناف ولا nth-child. بل يرون زرًّا عنوانه “Add expense”، وحقلًا تسميته “Amount”، وقائمة أرصدة. ويحصل مستخدمو قارئ الشاشة على هذه المعلومات بالضبط عبر شجرة إمكانية الوصول (accessibility tree): دور كل عنصر (button وlist وtextbox) واسمه القابل للوصول (تسميته أو نصّه).

\n

لذا تجد استعلامات Testing Library العناصر بالدور والتسمية والنص. والاختبار الذي يجد زر “Settle up” بدوره واسمه يظلّ ينجح مع أي إعادة تصميم، ويفشل في اليوم الذي يتوقّف فيه الزر عن أن يكون متاحًا لمستخدمي لوحة المفاتيح وقارئ الشاشة. وهذا خطأ يستحق الالتقاط.

\n

ترتيب الأولوية

\n
\n ثلاث طبقات مكدّسة: متاح للجميع (ByRole وByLabelText وByPlaceholderText وByText وByDisplayValue)، ودلالي (ByAltText وByTitle)، والـ test ids في الأخير.\n \n 1. متاح للجميع\n ByRole · ByLabelText · ByPlaceholderText · ByText · ByDisplayValue\n \n 2. دلالي\n ByAltText · ByTitle\n \n 3. الملاذ الأخير\n ByTestId\n
أولوية الاستعلامات: ابدأ من الأعلى، ولا تنزل إلا عند الضرورة
\n

يغطّي getByRole مع الخيار name معظم الحالات: الأزرار، والروابط، والعناوين، وحقول النماذج، والقوائم، والحوارات، والتنبيهات. وgetByLabelText هو الخيار الطبيعي لحقول النماذج. ويجد getByText المحتوى غير التفاعلي مثل رسالة أو سطر رصيد. أما الـ test ids فللعناصر التي لا دور لها ولا نص، مثل لوحة رسم بياني (canvas)، وهي لا تثبت شيئًا عن إمكانية الوصول.

\n

اختبار DOM باستخدام Testing Library

\n

يعرض Splitwise-lite الأرصدة كقائمة بسيطة. مع ضبط البيئة على jsdom وتثبيت @testing-library/dom، يبدو الاختبار هكذا:

\n
src/render-balances.test.js
// @vitest-environment jsdom\nimport { afterEach, test, expect } from 'vitest';\nimport { screen, within } from '@testing-library/dom';\nimport { renderBalances } from './render-balances.js';\n\nafterEach(() => {\n  document.body.innerHTML = '';\n});\n\ntest('lists each person with what they owe or are owed', () => {\n  renderBalances(document.body, { Ben: -500, Ana: 1200, Cai: 0 });\n\n  const list = screen.getByRole('list', { name: 'Balances' });\n  const items = within(list).getAllByRole('listitem');\n\n  expect(items.map((item) => item.textContent)).toEqual([\n    'Ana is owed $12.00',\n    'Ben owes $5.00',\n    'Cai is settled up',\n  ]);\n});\n\ntest('shows an empty state instead of an empty list', () => {\n  renderBalances(document.body, {});\n\n  expect(screen.getByText('No expenses yet')).toBeTruthy();\n  expect(screen.queryByRole('list')).toBeNull();\n});
\n

يستعلم screen في المستند كله. ويحصر within(element) الاستعلامات في جزء منه، وهذا مهم بمجرد أن تحتوي الصفحة على قائمتين. وتنظيف document.body بعد كل اختبار يمنع الـ DOM الخاص باختبار من التسرّب إلى الاختبار التالي. (تستطيع React Testing Library أن تتولّى هذا التنظيف عنك؛ ويوضّح الدرس الرابع من هذا القسم متى يحدث ذلك.)

\n

getBy وqueryBy وfindBy

\n

لكل استعلام ثلاث نكهات، إضافة إلى نسخة All من كل منها:

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
البادئةلا يوجد تطابقعدة تطابقاتاستخدمها لـ
getByيرمي خطأًيرمي خطأًعناصر يجب أن تكون موجودة
queryByيعيد nullيرمي خطأًتأكيد أن شيئًا ما غائب
findByيُرفض بعد الانتظاريُرفضعناصر تظهر لاحقًا

رمي getBy خطأً عند وجود عدة تطابقات ميزة لا عيب: إن كان استعلامك ملتبسًا، يخبرك الاختبار بدل أن يختار الأول بصمت.

\n\n\n

حين لا يجد الـ query عنصرك

\n

تفشل استعلامات الدور بصوت عالٍ، وفشلها مفيد. حين لا يجد getByRole('button', { name: 'Settle up' }) شيئًا، تطبع Testing Library كل دور متاح داخل الحاوية مع الأسماء التي حسبتها، فترى أن اسم الزر في الحقيقة “Settle up all debts”، أو أن الـ div القابل للنقر لديك بلا دور أصلًا. استدعِ screen.debug() لطباعة الـ DOM الحالي حين تحتاج إلى سياق أكثر. تأتي الأسماء المتاحة من بضعة مصادر، بهذا الترتيب تقريبًا: aria-labelledby، ثم aria-label، ثم <label> مرتبط، ثم نص العنصر نفسه (أو alt للصور). وإن لم يعطِ أيّ منها الاسم الذي تتوقّعه، فمستخدم قارئ الشاشة يسمع الشيء المربك نفسه الذي يراه اختبارك.

\n

في ساحة التجربة

\n

لا توجد حزم npm في ساحة التجربة، لذا تبدأ تمارين هذا القسم بنحو أربعين سطرًا من البدائل: getByRole وgetAllByRole وqueryByRole وgetByText وqueryByText، بالأسماء والسلوك نفسه في الحالات التي تحتاجها. ومثل الدوال المصدَّرة مباشرة من @testing-library/dom (لا عبر screen)، تأخذ هذه البدائل الحاوية معاملًا أول: getByRole(container, 'list'). تقرأ الدور من الوسم (أو من خاصية role) والاسم من aria-label أو <label> أو النص. أما Testing Library الحقيقية فتحسب شجرة إمكانية الوصول بشمول أكبر بكثير، لذا ثبّتها في مشاريعك.

\n

الدرس القادم: النقر والكتابة كما يفعل المستخدم.

\n","toc":[{"id":"sec-1","text":"المبدأ الموجّه","level":2},{"id":"sec-2","text":"ترتيب الأولوية","level":2},{"id":"sec-3","text":"اختبار DOM باستخدام Testing Library","level":2},{"id":"sec-4","text":"getBy وqueryBy وfindBy","level":2},{"id":"sec-5","text":"حين لا يجد الـ query عنصرك","level":2},{"id":"sec-6","text":"في ساحة التجربة","level":2}],"takeaways":["استعلم بما يدركه المستخدمون (الدور والاسم القابل للوصول، والتسمية، والنص الظاهر)، لا بأصناف CSS أو بنية الـ DOM، كي لا تنكسر الاختبارات حين يتغيّر التصميم.","ترتيب الأولوية هو: getByRole، ثم getByLabelText وgetByPlaceholderText وgetByText وgetByDisplayValue، ثم النص البديل والعنوان، وgetByTestId في الأخير.","يرمي getBy خطأً حين يجد صفر تطابقات أو عدة تطابقات، ويعيد queryBy القيمة null (استخدمه لتأكيد الغياب)، وينتظر findBy ظهور العنصر.","إن لم يجد استعلام الدور عنصرك، فغالبًا ما تكون البنية غير قابلة للوصول بعد؛ أصلح البنية بدل الانتقال إلى test id."],"further":[{"title":"Testing Library — About Queries","url":"https://testing-library.com/docs/queries/about"},{"title":"Testing Library — ByRole","url":"https://testing-library.com/docs/queries/byrole"},{"title":"MDN — ARIA roles","url":"https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles"}],"quiz":[{"q":"

يُعرض زر “Settle up” هكذا: <button class="btn btn-primary" data-testid="settle">Settle up</button>. أيّ query يجب أن يستخدمه الاختبار؟

","options":[{"text":"container.querySelector('.btn-primary')","why":"أسماء الأصناف قرارات تنسيق؛ وإعادة تسميتها أثناء إعادة التصميم ستكسر الاختبار رغم أن الزر ما زال يعمل."},{"text":"screen.getByTestId('settle')","why":"يعمل ويصمد أمام تغيير التنسيق، لكنه الملاذ الأخير في قائمة الأولوية لأن المستخدمين لا يرون الـ test ids، فلا يثبت شيئًا عن إمكانية الوصول."},{"text":"screen.getByRole('button', { name: 'Settle up' })","why":"صحيح. يجد العنصر بالطريقة التي يجده بها مستخدم قارئ الشاشة، ويفشل إن فقد الزر دوره أو اسمه القابل للوصول."}],"answer":2},{"q":"

تريد تأكيد أن رسالة الحالة الفارغة اختفت بعد إضافة مصروف. أيّ query يناسب؟

","options":[{"text":"expect(screen.queryByText('No expenses yet')).toBeNull()","why":"صحيح. يعيد queryBy القيمة null حين لا يوجد تطابق، وهذا بالضبط ما تريد تأكيده."},{"text":"expect(screen.getByText('No expenses yet')).toBeNull()","why":"يرمي getBy خطأً حين لا يوجد تطابق، فيتعطّل الاختبار قبل أن يعمل toBeNull؛ ولا يمكن أن ينجح أبدًا."},{"text":"expect(screen.findByText('No expenses yet')).toBeNull()","why":"يعيد findBy وعدًا (promise) لا يكون null أبدًا، وينتظر ظهور العنصر، وهذا عكس ما تريده."}],"answer":0},{"q":"

يفشل screen.getByRole('textbox', { name: 'Amount' }) بالرسالة “Unable to find an accessible element with the role textbox and name Amount”. تعرض الصفحة كلمة Amount بجوار حقل الإدخال. ما الإصلاح الأرجح؟

","options":[{"text":"أضف data-testid="amount" واستعلم بـ getByTestId.","why":"هذا يجعل الاختبار ينجح لكنه يترك المشكلة الحقيقية؛ فمستخدمو قارئ الشاشة ما زالوا يسمعون حقلًا بلا تسمية."},{"text":"اربط النص بحقل الإدخال باستخدام <label> (بلفّه حوله أو بـ for/id).","why":"صحيح. النص الذي يجاور الحقل فحسب ليس تسمية. وبمجرد ربطه، يحصل الحقل على اسم قابل للوصول فيجده الـ query، ويجده مستخدموك كذلك."},{"text":"استخدم getByText('Amount') ثم اقرأ .nextSibling.","why":"التنقّل بين العناصر المتجاورة يربط الاختبار ببنية الـ DOM بالضبط، ويبقى الحقل بلا تسمية."}],"answer":1},{"q":"

أيّ زوج من الاستعلامات هو الأقرب إلى الطريقة التي يجد بها مستخدم مبصر يستعمل الفأرة ومستخدم قارئ الشاشة قائمةَ الأرصدة؟

","options":[{"text":"document.querySelector('ul') و.children","why":"هذان يتبعان بنية الـ DOM؛ وإضافة غلاف أو قائمة ثانية ستكسر الاختبار أو تربكه."},{"text":"getByTestId('balances') وgetAllByTestId('row')","why":"الـ test ids غير مرئية للمستخدمين، وهي الملاذ الأخير في قائمة الأولوية."},{"text":"getByRole('list', { name: 'Balances' }) وwithin(list).getAllByRole('listitem')","why":"صحيح. دور القائمة وتسميتها هما ما تعلنه التقنيات المساعدة، وwithin يحصر استعلام العناصر داخل تلك القائمة."}],"answer":2}],"exercise":{"kind":"web","mode":"test","subject":"function formatMoney(cents) {\n const sign = cents < 0 ? '-' : '';\n const abs = Math.abs(cents);\n return `${sign}$${Math.floor(abs / 100)}.${String(abs % 100).padStart(2, '0')}`;\n}\n\n// Renders balances (in cents) into container.\n// - A list labelled \"Balances\", one item per person, sorted by name:\n// positive -> \"Ana is owed $12.00\"\n// negative -> \"Ben owes $5.00\"\n// zero -> \"Cai is settled up\"\n// - With no people at all: a paragraph \"No expenses yet\" and no list.\nfunction renderBalances(container, balances) {\n const names = Object.keys(balances).sort((a, b) => a.localeCompare(b));\n if (names.length === 0) {\n const empty = document.createElement('p');\n empty.textContent = 'No expenses yet';\n container.replaceChildren(empty);\n return;\n }\n const list = document.createElement('ul');\n list.setAttribute('aria-label', 'Balances');\n for (const name of names) {\n const cents = balances[name];\n const item = document.createElement('li');\n item.textContent =\n cents > 0 ? `${name} is owed ${formatMoney(cents)}`\n : cents < 0 ? `${name} owes ${formatMoney(-cents)}`\n : `${name} is settled up`;\n list.append(item);\n }\n container.replaceChildren(list);\n}\n","mutants":[{"id":"swapped-wording","code":"function formatMoney(cents) {\n const sign = cents < 0 ? '-' : '';\n const abs = Math.abs(cents);\n return `${sign}$${Math.floor(abs / 100)}.${String(abs % 100).padStart(2, '0')}`;\n}\n\n// Renders balances (in cents) into container.\n// - A list labelled \"Balances\", one item per person, sorted by name:\n// positive -> \"Ana is owed $12.00\"\n// negative -> \"Ben owes $5.00\"\n// zero -> \"Cai is settled up\"\n// - With no people at all: a paragraph \"No expenses yet\" and no list.\nfunction renderBalances(container, balances) {\n const names = Object.keys(balances).sort((a, b) => a.localeCompare(b));\n if (names.length === 0) {\n const empty = document.createElement('p');\n empty.textContent = 'No expenses yet';\n container.replaceChildren(empty);\n return;\n }\n const list = document.createElement('ul');\n list.setAttribute('aria-label', 'Balances');\n for (const name of names) {\n const cents = balances[name];\n const item = document.createElement('li');\n item.textContent =\n cents > 0 ? `${name} owes ${formatMoney(cents)}`\n : cents < 0 ? `${name} is owed ${formatMoney(-cents)}`\n : `${name} is settled up`;\n list.append(item);\n }\n container.replaceChildren(list);\n}\n"},{"id":"hides-settled","code":"function formatMoney(cents) {\n const sign = cents < 0 ? '-' : '';\n const abs = Math.abs(cents);\n return `${sign}$${Math.floor(abs / 100)}.${String(abs % 100).padStart(2, '0')}`;\n}\n\n// Renders balances (in cents) into container.\n// - A list labelled \"Balances\", one item per person, sorted by name:\n// positive -> \"Ana is owed $12.00\"\n// negative -> \"Ben owes $5.00\"\n// zero -> \"Cai is settled up\"\n// - With no people at all: a paragraph \"No expenses yet\" and no list.\nfunction renderBalances(container, balances) {\n const names = Object.keys(balances).filter((n) => balances[n] !== 0).sort((a, b) => a.localeCompare(b));\n if (names.length === 0) {\n const empty = document.createElement('p');\n empty.textContent = 'No expenses yet';\n container.replaceChildren(empty);\n return;\n }\n const list = document.createElement('ul');\n list.setAttribute('aria-label', 'Balances');\n for (const name of names) {\n const cents = balances[name];\n const item = document.createElement('li');\n item.textContent =\n cents > 0 ? `${name} is owed ${formatMoney(cents)}`\n : cents < 0 ? `${name} owes ${formatMoney(-cents)}`\n : `${name} is settled up`;\n list.append(item);\n }\n container.replaceChildren(list);\n}\n"},{"id":"minus-sign","code":"function formatMoney(cents) {\n const sign = cents < 0 ? '-' : '';\n const abs = Math.abs(cents);\n return `${sign}$${Math.floor(abs / 100)}.${String(abs % 100).padStart(2, '0')}`;\n}\n\n// Renders balances (in cents) into container.\n// - A list labelled \"Balances\", one item per person, sorted by name:\n// positive -> \"Ana is owed $12.00\"\n// negative -> \"Ben owes $5.00\"\n// zero -> \"Cai is settled up\"\n// - With no people at all: a paragraph \"No expenses yet\" and no list.\nfunction renderBalances(container, balances) {\n const names = Object.keys(balances).sort((a, b) => a.localeCompare(b));\n if (names.length === 0) {\n const empty = document.createElement('p');\n empty.textContent = 'No expenses yet';\n container.replaceChildren(empty);\n return;\n }\n const list = document.createElement('ul');\n list.setAttribute('aria-label', 'Balances');\n for (const name of names) {\n const cents = balances[name];\n const item = document.createElement('li');\n item.textContent =\n cents > 0 ? `${name} is owed ${formatMoney(cents)}`\n : cents < 0 ? `${name} owes ${formatMoney(cents)}`\n : `${name} is settled up`;\n list.append(item);\n }\n container.replaceChildren(list);\n}\n"},{"id":"no-empty-state","code":"function formatMoney(cents) {\n const sign = cents < 0 ? '-' : '';\n const abs = Math.abs(cents);\n return `${sign}$${Math.floor(abs / 100)}.${String(abs % 100).padStart(2, '0')}`;\n}\n\n// Renders balances (in cents) into container.\n// - A list labelled \"Balances\", one item per person, sorted by name:\n// positive -> \"Ana is owed $12.00\"\n// negative -> \"Ben owes $5.00\"\n// zero -> \"Cai is settled up\"\n// - With no people at all: a paragraph \"No expenses yet\" and no list.\nfunction renderBalances(container, balances) {\n const names = Object.keys(balances).sort((a, b) => a.localeCompare(b));\n if (false) {\n const empty = document.createElement('p');\n empty.textContent = 'No expenses yet';\n container.replaceChildren(empty);\n return;\n }\n const list = document.createElement('ul');\n list.setAttribute('aria-label', 'Balances');\n for (const name of names) {\n const cents = balances[name];\n const item = document.createElement('li');\n item.textContent =\n cents > 0 ? `${name} is owed ${formatMoney(cents)}`\n : cents < 0 ? `${name} owes ${formatMoney(-cents)}`\n : `${name} is settled up`;\n list.append(item);\n }\n container.replaceChildren(list);\n}\n"}],"starter":{"js":"// ── Tiny stand-ins for Testing Library queries (no npm in the playground) ──\nconst ROLE_SELECTORS = {\n alert: '[role=\"alert\"]',\n button: 'button, [role=\"button\"]',\n list: 'ul, ol, [role=\"list\"]',\n listitem: 'li, [role=\"listitem\"]',\n status: '[role=\"status\"]',\n textbox: 'input:not([type]), input[type=\"text\"], textarea, [role=\"textbox\"]',\n};\nfunction accessibleName(el) {\n if (el.getAttribute('aria-label')) return el.getAttribute('aria-label');\n if (el.labels && el.labels.length) return el.labels[0].textContent.trim();\n return el.textContent.trim();\n}\nfunction queryAllByRole(root, role, { name } = {}) {\n return [...root.querySelectorAll(ROLE_SELECTORS[role])]\n .filter((el) => !el.closest('[hidden]'))\n .filter((el) => name === undefined || accessibleName(el) === name);\n}\nfunction queryByRole(root, role, options) {\n return queryAllByRole(root, role, options)[0] ?? null;\n}\nfunction getAllByRole(root, role, options = {}) {\n const found = queryAllByRole(root, role, options);\n if (!found.length) throw new Error(`Unable to find role \"${role}\"${options.name ? ` named \"${options.name}\"` : ''}`);\n return found;\n}\nfunction getByRole(root, role, options = {}) {\n const found = getAllByRole(root, role, options);\n if (found.length > 1) throw new Error(`Found ${found.length} elements with role \"${role}\"`);\n return found[0];\n}\nfunction queryByText(root, text) {\n return [...root.querySelectorAll('*')].find((el) =>\n !el.closest('[hidden]') &&\n el.textContent.trim() === text &&\n ![...el.children].some((child) => child.textContent.trim() === text)) ?? null;\n}\nfunction getByText(root, text) {\n const el = queryByText(root, text);\n if (!el) throw new Error(`Unable to find text \"${text}\"`);\n return el;\n}\n// ────────────────────────────────────────────────────────────────────────────\n\nlet container;\n\nbeforeEach(() => {\n container = document.createElement('div');\n document.body.append(container);\n});\n\nafterEach(() => {\n container.remove();\n});\n\ndescribe('renderBalances', () => {\n test('renders a list labelled Balances', () => {\n renderBalances(container, { Ana: 1200, Ben: -1200 });\n\n expect(getByRole(container, 'list', { name: 'Balances' })).toBeTruthy();\n });\n\n // Add tests that read what the user reads: the text of each item,\n // a settled-up person, and the empty state.\n});\n"},"solution":{"js":"// ── Tiny stand-ins for Testing Library queries (no npm in the playground) ──\nconst ROLE_SELECTORS = {\n alert: '[role=\"alert\"]',\n button: 'button, [role=\"button\"]',\n list: 'ul, ol, [role=\"list\"]',\n listitem: 'li, [role=\"listitem\"]',\n status: '[role=\"status\"]',\n textbox: 'input:not([type]), input[type=\"text\"], textarea, [role=\"textbox\"]',\n};\nfunction accessibleName(el) {\n if (el.getAttribute('aria-label')) return el.getAttribute('aria-label');\n if (el.labels && el.labels.length) return el.labels[0].textContent.trim();\n return el.textContent.trim();\n}\nfunction queryAllByRole(root, role, { name } = {}) {\n return [...root.querySelectorAll(ROLE_SELECTORS[role])]\n .filter((el) => !el.closest('[hidden]'))\n .filter((el) => name === undefined || accessibleName(el) === name);\n}\nfunction queryByRole(root, role, options) {\n return queryAllByRole(root, role, options)[0] ?? null;\n}\nfunction getAllByRole(root, role, options = {}) {\n const found = queryAllByRole(root, role, options);\n if (!found.length) throw new Error(`Unable to find role \"${role}\"${options.name ? ` named \"${options.name}\"` : ''}`);\n return found;\n}\nfunction getByRole(root, role, options = {}) {\n const found = getAllByRole(root, role, options);\n if (found.length > 1) throw new Error(`Found ${found.length} elements with role \"${role}\"`);\n return found[0];\n}\nfunction queryByText(root, text) {\n return [...root.querySelectorAll('*')].find((el) =>\n !el.closest('[hidden]') &&\n el.textContent.trim() === text &&\n ![...el.children].some((child) => child.textContent.trim() === text)) ?? null;\n}\nfunction getByText(root, text) {\n const el = queryByText(root, text);\n if (!el) throw new Error(`Unable to find text \"${text}\"`);\n return el;\n}\n// ────────────────────────────────────────────────────────────────────────────\n\nlet container;\n\nbeforeEach(() => {\n container = document.createElement('div');\n document.body.append(container);\n});\n\nafterEach(() => {\n container.remove();\n});\n\ndescribe('renderBalances', () => {\n test('renders a list labelled Balances', () => {\n renderBalances(container, { Ana: 1200, Ben: -1200 });\n\n expect(getByRole(container, 'list', { name: 'Balances' })).toBeTruthy();\n });\n\n test('says who owes and who is owed, sorted by name', () => {\n renderBalances(container, { Ben: -500, Cai: 0, Ana: 500 });\n\n const items = getAllByRole(container, 'listitem');\n expect(items.map((item) => item.textContent)).toEqual([\n 'Ana is owed $5.00',\n 'Ben owes $5.00',\n 'Cai is settled up',\n ]);\n });\n\n test('shows an empty state instead of an empty list', () => {\n renderBalances(container, {});\n\n expect(getByText(container, 'No expenses yet')).toBeTruthy();\n expect(queryByRole(container, 'list')).toBeNull();\n });\n});\n"},"checks":[{"id":"passes","suite":"subject"},{"id":"catches-swapped-wording","suite":"swapped-wording"},{"id":"catches-hides-settled","suite":"hides-settled"},{"id":"catches-minus-sign","suite":"minus-sign"},{"id":"catches-no-empty-state","suite":"no-empty-state"}],"title":"استعلم عن الأرصدة كما يفعل المستخدم","prompt":"

تعرض renderBalances(container, balances) قائمة تسميتها Balances: "Ana is owed $12.00"، "Ben owes $5.00"، "Cai is settled up"، مرتّبة حسب الاسم. وحين لا يوجد أشخاص تعرض No expenses yet دون أي قائمة.

\n

يبدأ الكود المبدئي ببدائل صغيرة لاستعلامات Testing Library (getByRole وgetAllByRole وqueryByRole وgetByText وqueryByText؛ وكلها تأخذ الحاوية معاملًا أول)، وينشئ container جديدة لكل اختبار. أضف اختبارات حتى تلتقط مجموعتك أربعة أخطاء مخفيّة: صياغة owes/is owed متبادلة، ونسخة تُخفي من سوّوا حساباتهم، ونسخة تطبع إشارة سالب (“owes -$5.00”)، ونسخة بلا حالة فارغة.

\n","hints":["اقرأ ما يقرؤه المستخدم: getAllByRole(container, 'listitem').map((li) => li.textContent) يعطيك كل سطر نص.","استخدم رصيدًا واحدًا من كل نوع (موجب، وسالب، وصفر)، كي يغطّي toEqual واحد على النصوص الصياغةَ والإشارةَ والشخصَ الذي سوّى حسابه.","للحالة الفارغة، استدعِ renderBalances(container, {})، ثم getByText(container, 'No expenses yet') وexpect(queryByRole(container, 'list')).toBeNull()."],"explanation":"

أقوى assertion هنا يقارن النص الظاهر لكل عنصر مع رصيد واحد من كل نوع. هذا الـ toEqual الوحيد يلتقط الصياغة المتبادلة، وإشارة السالب الشاردة، وسطر الشخص المسوّى الغائب، لأن كلًّا منها يغيّر ما سيقرؤه المستخدم. ويستخدم اختبار الحالة الفارغة getByText لما يجب أن يوجد، وqueryByRole(...) مع toBeNull() لما يجب ألا يوجد، وهذا هو التقسيم المعتاد بين getBy وqueryBy. لا يعتمد أيّ من الاختبارات على تداخل الوسوم أو الأصناف: تستطيع عرض الأرصدة في <div role="list"> بصفوف role="listitem"، أو تغيير التنسيق كله، وستظلّ تنجح.

\n","checkLabels":{"passes":"كل اختباراتك تنجح على renderBalances الحقيقية","catches-swapped-wording":"تلتقط النسخة التي تبادل بين “owes” و"is owed"","catches-hides-settled":"تلتقط النسخة التي تُخفي من سوّوا حساباتهم","catches-minus-sign":"تلتقط النسخة التي تطبع “owes -$5.00”","catches-no-empty-state":"تلتقط النسخة التي لا تعرض حالة فارغة"}},"words":657,"readMinutes":4}