تحمّل لوحة الأرصدة في Splitwise-lite بياناتها من الخادم. للحظة تعرض “Loading balances…”، ثم تعرض القائمة، أو، في قطار داخل نفق، “Could not load balances.” مع زر “Try again”. كل حالة من هذه الحالات شيء يراه المستخدم، لذا تستحق كل منها اختبارًا. الصعوبة في الزمن: الـ DOM الذي تريد فحصه لم يوجد بعد حين يصل الاختبار إلى السطر الذي يفحصه.
\nأول ما يخطر في البال هو الانتظار قليلًا:
\nmountBalancePanel(document.body, loadBalances);\nawait new Promise((resolve) => setTimeout(resolve, 500)); // please be enough\nexpect(screen.getByRole('list', { name: 'Balances' })).toBeInTheDocument();على حاسوبك تصل البيانات في 5 ms، فيضيّع الاختبار 495. وعلى خادم CI مشغول تستغرق أحيانًا 600، فيفشل الاختبار بلا سبب. اضرب ذلك في بضع مئات من الاختبارات، فتحصل على مجموعة بطيئة حمراء كل ثلاثاء. انتظر الشرط، لا الساعة.
\nاستعلامات findBy هي استعلامات getBy تعيد المحاولة. تعيد promise يُحلّ بمجرد أن يوجد العنصر، ويُرفض إن لم يظهر خلال المهلة (1,000 ms افتراضيًا):
// @vitest-environment jsdom\nimport { afterEach, test, expect, vi } from 'vitest';\nimport { screen } from '@testing-library/dom';\nimport '@testing-library/jest-dom/vitest';\nimport { mountBalancePanel } from './balance-panel.js';\n\nafterEach(() => {\n document.body.innerHTML = '';\n});\n\ntest('shows a loading message, then the balances', async () => {\n const loadBalances = vi.fn().mockResolvedValue({ Ana: 500, Ben: -500 });\n\n mountBalancePanel(document.body, loadBalances);\n\n expect(screen.getByRole('status')).toHaveTextContent('Loading balances');\n expect(await screen.findByRole('list', { name: 'Balances' })).toBeInTheDocument();\n expect(screen.queryByRole('status')).not.toBeInTheDocument();\n});الاختبار سريع حين يكون الكود سريعًا، وصبور حين يكون بطيئًا، ويُقرأ كقصة ما يراه المستخدم. والسطر الأخير مهم أيضًا: اللوحة التي تعرض البيانات لكنها تترك “Loading…” على الشاشة فيها خطأ حقيقي.
\nيشغّل waitFor(callback) الدالة، فإن رمت خطأً، يعيد تشغيلها كل 50 ms حتى تنجح أو تنتهي المهلة. استخدمه للشروط التي ليست “ظهر عنصر”:
await waitFor(() => expect(loadBalances).toHaveBeenCalledTimes(2));ولدى Vitest دالتها الخاصة vi.waitFor التي تعمل بالطريقة نفسها خارج الـ DOM. وللحالة المعاكسة، ينتظر waitForElementToBeRemoved(() => screen.queryByRole('status')) اختفاء شيء ما.
يتولّى findBy الانتظار. ولتختبر كل حالة بشكل حتمي، تتحكّم أيضًا في الاعتمادية. ولأن loadBalances تُمرَّر كمعامل، يستطيع vi.fn أن يجعلها تفعل أي شيء:
mockResolvedValue(data) للنجاح؛mockRejectedValue(new Error('Offline')) للفشل؛test('keeps showing the loading message until data arrives', async () => {\n let finish;\n const loadBalances = vi.fn(() => new Promise((resolve) => { finish = resolve; }));\n\n mountBalancePanel(document.body, loadBalances);\n expect(screen.getByRole('status')).toHaveTextContent('Loading balances');\n\n finish({ Ana: 0 });\n expect(await screen.findByText('Ana is settled up')).toBeInTheDocument();\n});لمسار إعادة المحاولة، ابدأ بـ mock يرفض، وانتظر التنبيه، ثم حوّل الـ mock إلى النجاح، وانقر “Try again” مرة واحدة، ثم استخدم findBy لإيجاد القائمة. كل خطوة شيء يفعله المستخدم أو يراه، ولا شيء يعتمد على سرعة الجهاز.
يستسلم findBy وwaitFor بعد ثانية واحدة. وهذا أكثر من كافٍ لكود تتحكّم في اعتمادياته، وإن احتاج اختبار مكوّن إلى وقت أطول، فالسبب المعتاد استدعاء شبكة حقيقي أو مؤقّت حقيقي تسرّب إليه. أصلح التسرّب أولًا. وحين يكون الانتظار مشروعًا فعلًا، مرّر خيارات: screen.findByRole('list', {}, { timeout: 3000 }) (المعامل الثالث هو خيارات الانتظار) أو waitFor(callback, { timeout: 3000 }).
في اختبارات React سترى أحيانًا تحذيرًا بأن تحديثًا “was not wrapped in act(…)”. يعني ذلك عادةً أن تحديثًا للـ state حدث بعد أن توقّف الاختبار عن النظر: promise ما حُلّ متأخرًا. والإصلاح لا يكون تقريبًا أبدًا بلفّ الأشياء في act يدويًا؛ بل بانتظار الحالة النهائية التي سيراها المستخدم بـ await، مع استعلام findBy.
يضيف الكود المبدئي للتمرين waitFor(callback) وfindByRole(root, role, options) وfindByText(root, text) إلى بدائل الاستعلامات. تستطلع كل 20 ms وتستسلم بعد 500 ms، فيفشل الاختبار على نسخة معطوبة بسرعة.
ينقل الدرس القادم هذا كله إلى مكوّنات React، وإلى استدعاءات الشبكة التي تقف خلف loadBalances.
findBy وعدًا (promise) يُحلّ حين يظهر العنصر، وتعيد المحاولة حتى انتهاء المهلة (ثانية واحدة افتراضيًا).","يعيد waitFor(callback) تشغيل الدالة حتى تتوقّف عن رمي الأخطاء؛ استخدمه مع assertions لا تتعلّق بظهور عنصر، مثل عدد استدعاءات mock.","لا تنتظر وقتًا ثابتًا أبدًا (sleep)؛ انتظر الشرط الذي يهمّك فعلًا.","تحكّم في الاعتمادية غير المتزامنة بنفسك (vi.fn يُحلّ، أو يُرفض، أو يبقى معلّقًا)، كي تكون حالات التحميل والنجاح والخطأ وإعادة المحاولة كل منها اختبارًا حتميًّا واحدًا."],"further":[{"title":"Testing Library — Async methods","url":"https://testing-library.com/docs/dom-testing-library/api-async"},{"title":"Testing Library — Appearance and disappearance","url":"https://testing-library.com/docs/guide-disappearance"},{"title":"Vitest — vi.waitFor","url":"https://vitest.dev/api/vi#vi-waitfor"}],"quiz":[{"q":"تظهر قائمة الأرصدة بعد أن يُحلّ loadBalances(). أيّ سطر ينتظرها بشكل صحيح؟
await new Promise((r) => setTimeout(r, 500)); screen.getByRole('list');","why":"الانتظار الثابت أطول من اللازم على جهاز سريع، وأقصر من اللازم على خادم CI مشغول؛ وهو المصدر الكلاسيكي لاختبارات الواجهة المتقلّبة."},{"text":"const list = await screen.findByRole('list', { name: 'Balances' });","why":"صحيح. يعيد findByRole المحاولة حتى تظهر القائمة (أو تمرّ ثانية)، فينتظر بالضبط المدة اللازمة."},{"text":"const list = screen.getByRole('list', { name: 'Balances' });","why":"يفحص getByRole مرة واحدة، فورًا، قبل أن يُحلّ الـ promise، فيرمي خطأً."}],"answer":1},{"q":"ما المشكلة هنا؟
\nawait waitFor(() => {\n user.click(screen.getByRole('button', { name: 'Try again' }));\n expect(loadBalances).toHaveBeenCalledTimes(2);\n});waitFor على استدعاءات expect.","why":"الـ assertions هي بالضبط ما يوضع داخل waitFor؛ فهو يعيد تشغيل الدالة حتى تتوقّف عن رمي الأخطاء."},{"text":"toHaveBeenCalledTimes لا يعمل مع الدوال غير المتزامنة.","why":"يعدّ الاستدعاءات على أي mock، متزامنًا كان أو غير متزامن؛ وهذا السطر سليم وحده."},{"text":"النقر أثر جانبي داخل دالة يُعاد تشغيلها، فقد يُنفَّذ عدة مرات ويضخّم عدد الاستدعاءات.","why":"صحيح. انقر مرة واحدة، خارجها، ثم await waitFor(() => expect(loadBalances).toHaveBeenCalledTimes(2))."}],"answer":2},{"q":"كيف تختبر أن رسالة “Loading balances…” تظهر قبل وصول البيانات، دون أن تتسابق مع الـ promise؟
","options":[{"text":"اجعلloadBalances تعيد promise يحلّه الاختبار يدويًا، ثم أكّد رسالة التحميل، ثم حلّه.","why":"صحيح. الـ promise المؤجَّل يجمّد المكوّن في حالة التحميل للمدة التي تحتاجها، فيكون الاختبار حتميًّا."},{"text":"أضف تأخيرًا بمقدار 50 ms إلى loadBalances الحقيقية في الاختبارات.","why":"أي طريقة تعتمد على التوقيت تتسابق: على خادم بطيء قد يفوت الـ assertion أو يصيب في اللحظة الخطأ."},{"text":"استخدم findByRole('status') كي ينتظر الرسالة.","why":"الرسالة تظهر فورًا، فإيجادها ليس الجزء الصعب؛ الخطر أن تكون البيانات قد حلّت محلّها بحلول الوقت الذي تنظر فيه."}],"answer":0}],"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\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\n// Shows balances loaded with loadBalances() (returns a promise).\n// - While loading: Loading balances…
\n// - On success: the \"Balances\" list from renderBalances; the status is gone.\n// - On failure:Could not load balances.
and a\n// \"Try again\" button that calls loadBalances again.\nfunction mountBalancePanel(container, loadBalances) {\n async function load() {\n container.innerHTML = 'Loading balances…
';\n try {\n const balances = await loadBalances();\n renderBalances(container, balances);\n } catch {\n container.innerHTML =\n 'Could not load balances.
';\n container.querySelector('button').addEventListener('click', load);\n }\n }\n load();\n}\n","mutants":[{"id":"no-loading","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\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\n// Shows balances loaded with loadBalances() (returns a promise).\n// - While loading:Loading balances…
\n// - On success: the \"Balances\" list from renderBalances; the status is gone.\n// - On failure:Could not load balances.
and a\n// \"Try again\" button that calls loadBalances again.\nfunction mountBalancePanel(container, loadBalances) {\n async function load() {\n container.innerHTML = '';\n try {\n const balances = await loadBalances();\n renderBalances(container, balances);\n } catch {\n container.innerHTML =\n 'Could not load balances.
';\n container.querySelector('button').addEventListener('click', load);\n }\n }\n load();\n}\n"},{"id":"stale-loading","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\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\n// Shows balances loaded with loadBalances() (returns a promise).\n// - While loading:Loading balances…
\n// - On success: the \"Balances\" list from renderBalances; the status is gone.\n// - On failure:Could not load balances.
and a\n// \"Try again\" button that calls loadBalances again.\nfunction mountBalancePanel(container, loadBalances) {\n async function load() {\n container.innerHTML = 'Loading balances…
';\n try {\n const balances = await loadBalances();\n const box = document.createElement('div');\n container.append(box);\n renderBalances(box, balances);\n } catch {\n container.innerHTML =\n 'Could not load balances.
';\n container.querySelector('button').addEventListener('click', load);\n }\n }\n load();\n}\n"},{"id":"error-hidden","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\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\n// Shows balances loaded with loadBalances() (returns a promise).\n// - While loading:Loading balances…
\n// - On success: the \"Balances\" list from renderBalances; the status is gone.\n// - On failure:Could not load balances.
and a\n// \"Try again\" button that calls loadBalances again.\nfunction mountBalancePanel(container, loadBalances) {\n async function load() {\n container.innerHTML = 'Loading balances…
';\n try {\n const balances = await loadBalances();\n renderBalances(container, balances);\n } catch {\n container.innerHTML = '';\n }\n }\n load();\n}\n"},{"id":"no-retry","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\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\n// Shows balances loaded with loadBalances() (returns a promise).\n// - While loading:Loading balances…
\n// - On success: the \"Balances\" list from renderBalances; the status is gone.\n// - On failure:Could not load balances.
and a\n// \"Try again\" button that calls loadBalances again.\nfunction mountBalancePanel(container, loadBalances) {\n async function load() {\n container.innerHTML = 'Loading balances…
';\n try {\n const balances = await loadBalances();\n renderBalances(container, balances);\n } catch {\n container.innerHTML =\n 'Could not load balances.
';\n }\n }\n load();\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\n// ── Stand-ins for waitFor and findBy (poll every 20 ms, give up after 500 ms) ──\nasync function waitFor(callback, { timeout = 500, interval = 20 } = {}) {\n const start = Date.now();\n for (;;) {\n try {\n return await callback();\n } catch (error) {\n if (Date.now() - start > timeout) throw error;\n await new Promise((resolve) => setTimeout(resolve, interval));\n }\n }\n}\nconst findByRole = (root, role, options) => waitFor(() => getByRole(root, role, options));\nconst findByText = (root, text) => waitFor(() => getByText(root, text));\n// ────────────────────────────────────────────────────────────────────────────\n\n// ── Stand-ins for user-event (synchronous here, so no await) ──\nfunction typeInto(el, text) {\n clickOn(el);\n for (const key of text) {\n el.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true }));\n el.value += key;\n el.dispatchEvent(new InputEvent('input', { data: key, inputType: 'insertText', bubbles: true }));\n el.dispatchEvent(new KeyboardEvent('keyup', { key, bubbles: true }));\n }\n}\nfunction clickOn(el) {\n if (el.disabled) return;\n el.dispatchEvent(new PointerEvent('pointerdown', { bubbles: true }));\n el.dispatchEvent(new MouseEvent('mousedown', { bubbles: true }));\n el.focus();\n el.dispatchEvent(new PointerEvent('pointerup', { bubbles: true }));\n el.dispatchEvent(new MouseEvent('mouseup', { bubbles: true }));\n el.click();\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('balance panel', () => {\n test('eventually shows the balances', async () => {\n const loadBalances = vi.fn().mockResolvedValue({ Ana: 500, Ben: -500 });\n\n mountBalancePanel(container, loadBalances);\n\n expect(await findByRole(container, 'list', { name: 'Balances' })).toBeTruthy();\n });\n\n // Add: the loading status (and that it goes away),\n // the error alert, and the \"Try again\" button.\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\n// ── Stand-ins for waitFor and findBy (poll every 20 ms, give up after 500 ms) ──\nasync function waitFor(callback, { timeout = 500, interval = 20 } = {}) {\n const start = Date.now();\n for (;;) {\n try {\n return await callback();\n } catch (error) {\n if (Date.now() - start > timeout) throw error;\n await new Promise((resolve) => setTimeout(resolve, interval));\n }\n }\n}\nconst findByRole = (root, role, options) => waitFor(() => getByRole(root, role, options));\nconst findByText = (root, text) => waitFor(() => getByText(root, text));\n// ────────────────────────────────────────────────────────────────────────────\n\n// ── Stand-ins for user-event (synchronous here, so no await) ──\nfunction typeInto(el, text) {\n clickOn(el);\n for (const key of text) {\n el.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true }));\n el.value += key;\n el.dispatchEvent(new InputEvent('input', { data: key, inputType: 'insertText', bubbles: true }));\n el.dispatchEvent(new KeyboardEvent('keyup', { key, bubbles: true }));\n }\n}\nfunction clickOn(el) {\n if (el.disabled) return;\n el.dispatchEvent(new PointerEvent('pointerdown', { bubbles: true }));\n el.dispatchEvent(new MouseEvent('mousedown', { bubbles: true }));\n el.focus();\n el.dispatchEvent(new PointerEvent('pointerup', { bubbles: true }));\n el.dispatchEvent(new MouseEvent('mouseup', { bubbles: true }));\n el.click();\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('balance panel', () => {\n test('shows a loading status, then the balances', async () => {\n const loadBalances = vi.fn().mockResolvedValue({ Ana: 500, Ben: -500 });\n\n mountBalancePanel(container, loadBalances);\n\n expect(getByRole(container, 'status').textContent).toMatch('Loading balances');\n expect(await findByRole(container, 'list', { name: 'Balances' })).toBeTruthy();\n expect(queryByRole(container, 'status')).toBeNull();\n });\n\n test('explains a failure and retries on request', async () => {\n const loadBalances = vi.fn().mockRejectedValue(new Error('Offline'));\n\n mountBalancePanel(container, loadBalances);\n expect((await findByRole(container, 'alert')).textContent).toBe('Could not load balances.');\n\n loadBalances.mockResolvedValue({ Ana: 0 });\n clickOn(getByRole(container, 'button', { name: 'Try again' }));\n\n expect(await findByText(container, 'Ana is settled up')).toBeTruthy();\n expect(loadBalances).toHaveBeenCalledTimes(2);\n });\n});\n"},"checks":[{"id":"passes","suite":"subject"},{"id":"catches-no-loading","suite":"no-loading"},{"id":"catches-stale-loading","suite":"stale-loading"},{"id":"catches-error-hidden","suite":"error-hidden"},{"id":"catches-no-retry","suite":"no-retry"}],"title":"التحميل والخطأ وإعادة المحاولة","prompt":"تعرض mountBalancePanel(container, loadBalances) الرسالة “Loading balances…” في role="status" ما دام loadBalances() معلّقًا، ثم قائمة Balances. وإن رُفض الـ promise، تعرض “Could not load balances.” في role="alert" مع زر Try again يحمّل من جديد.
يضيف الكود المبدئي waitFor وfindByRole وfindByText إلى البدائل (وهي تستطلع حتى 500 ms). تحكّم في loadBalances باستخدام vi.fn() وأضف اختبارات حتى تلتقط مجموعتك أربعة أخطاء مخفيّة: نسخة لا تعرض حالة التحميل أبدًا، ونسخة تُبقيها على الشاشة بعد وصول البيانات، ونسخة لا تعرض شيئًا عند الفشل، ونسخة لا يفعل زر Try again فيها شيئًا.
getByRole(container, 'status') مباشرة بعد mountBalancePanel(...). وبعد await findByRole(... 'list' ...) يجب أن يكون queryByRole(container, 'status') مساويًا null.","للفشل: vi.fn().mockRejectedValue(new Error('Offline'))، ثم await findByRole(container, 'alert').","لإعادة المحاولة: بعد ظهور التنبيه، استدعِ loadBalances.mockResolvedValue({ Ana: 0 })، وانقر Try again بـ clickOn، ثم await findByText(container, 'Ana is settled up')."],"explanation":"كل حالة assertion واحد عمّا يراه المستخدم. فحص حالة التحميل مباشرة بعد التركيب يلتقط اللوحة التي لا تعرض رسالة تحميل؛ وفحص اختفائها بعد أن يُحلّ findByRole يلتقط اللوحة التي تتركها خلفها. وينتظر اختبار الفشل التنبيه بـ findByRole، الذي تنتهي مهلته إن ابتُلع الخطأ. وتحويل الـ mock إلى النجاح قبل النقر على Try again يجعل إعادة المحاولة قصة حتمية: إن لم يكن الزر موصولًا، لا يظهر نص التسوية أبدًا ويفشل الاختبار. لا يوجد أي انتظار ثابت في أي مكان، فالمجموعة بسرعة الكود نفسه.