يحفظ Splitwise-lite المصروفات عبر اتصال هاتف في قطار. الطلبات تفشل. بعض حالات الفشل تستحق إعادة محاولة واحدة (انتهاء المهلة)؛ وبعضها لا (حين يقول الخادم إن المبلغ غير صالح). الكود الذي يقرّر ذلك نحو اثني عشر سطرًا لا أكثر، وهو بالضبط الكود الذي لا يختبره أحد، لأنه “غير متزامن” و"يحتاج إلى الـ API". ولا واحد من السببين عائق حقيقي.
\nexport async function saveExpense(expense, api) {\n if (!expense.description?.trim()) throw new Error('Description is required');\n if (!Number.isInteger(expense.amountCents) || expense.amountCents <= 0) {\n throw new Error('Amount must be positive');\n }\n try {\n const { id } = await api.post('/expenses', expense);\n return id;\n } catch (error) {\n if (!error.retryable) throw error;\n const { id } = await api.post('/expenses', expense); // one retry\n return id;\n }\n}لأنها دالة async، يتحوّل كل throw داخلها إلى promise مرفوض. المستدعون (والاختبارات) لا يرون أبدًا استثناءً متزامنًا؛ بل يرون promise يُرفض.
تنتظر Vitest الاختبار الذي يكون async أو يعيد promise. وفي داخله لديك خياران جيدان:
test('resolves with the new id', async () => {\n const api = { post: async () => ({ id: 'e1' }) };\n\n await expect(saveExpense({ description: 'Dinner', amountCents: 4500 }, api))\n .resolves.toBe('e1');\n});\n\ntest('rejects a blank description', async () => {\n const api = { post: async () => ({ id: 'e1' }) };\n\n await expect(saveExpense({ description: ' ', amountCents: 4500 }, api))\n .rejects.toThrow('Description is required');\n});يمكنك أيضًا أن تستخدم await مع الاستدعاء ثم تؤكّد القيمة: const id = await saveExpense(...); expect(id).toBe('e1');. أما مع حالات الرفض، ففضّل rejects على try/catch: إن حُلّ الـ promise بنجاح على غير المتوقّع، يُفشل rejects الاختبار، بينما تتخطّى try/catch كتلة catch بصمت وينجح الاختبار. (وإن اضطررت إلى try/catch، فضع expect.assertions(1) في أعلى الاختبار كي تُفشله Vitest حين لا يُنفَّذ أي assertion.)
تتحدّث saveExpense إلى api. في الاختبار لا تريد خادمًا حقيقيًا؛ بل تريد كائنًا تفعل دالة post فيه ما يحتاجه هذا الاختبار بالذات. هذا الكائن هو الـ stub (بديل ثابت الاستجابة)، ولا تحتاج إلى مكتبة لكتابته:
// Fails once with a retryable error, then succeeds; counts its calls.\nfunction flakyApi() {\n let calls = 0;\n return {\n get calls() { return calls; },\n async post() {\n calls += 1;\n if (calls === 1) throw Object.assign(new Error('Timed out'), { retryable: true });\n return { id: 'e2' };\n },\n };\n}\n\ntest('retries once after a retryable error', async () => {\n const api = flakyApi();\n\n await expect(saveExpense({ description: 'Taxi', amountCents: 1800 }, api)).resolves.toBe('e2');\n expect(api.calls).toBe(2);\n});تمرير api كمعامل هو ما يجعل هذا سهلًا. الكود الذي يستورد عميلًا عامًّا في أعماقه أصعب اختبارًا بكثير؛ وستتعرّف إلى أدوات ذلك (وثمنها) في الدرس القادم.
لمعالجة الأخطاء فروع أكثر من المسار السعيد، وكل فرع منها قرار اتّخذه شخص ما. بالنسبة إلى saveExpense:
| الموقف | \nالمتوقّع | \n
|---|---|
| ينجح الـ API | \nيُحلّ بالـ id، باستدعاء واحد | \n
| خطأ قابل لإعادة المحاولة، ثم نجاح | \nيُحلّ بالـ id، باستدعاءين | \n
| خطأ غير قابل لإعادة المحاولة | \nيُرفض بـ ذلك الخطأ، باستدعاء واحد | \n
| مدخل غير صالح | \nيُرفض برسالة تحقّق، بلا أي استدعاء | \n
الصف الثالث هو الذي يتخطّاه الناس، وهو يخبّئ خطأين شائعين: catch تبتلع الخطأ وتعيد null (فيظنّ المستدعون أن الحفظ نجح)، وcatch تعيد المحاولة مع كل شيء (فتُحصَّل دفعة مرفوضة مرتين). الرفض وحده لا يستطيع كشف الخطأ الثاني، لأن إعادة المحاولة تفشل هي الأخرى. أما عدّ الاستدعاءات فيستطيع.
لاحظ الصف الأخير أيضًا: المدخل غير الصالح يجب ألا يُحدث أي استدعاء. هذا وعد يتعلّق بالآثار الجانبية، وهو مهم. النسخة التي تتحقّق بعد الإرسال سترفض بالرسالة الصحيحة رغم ذلك، فلا يثبت أن المصروف السيئ لم يصل إلى الخادم سوى عدد الاستدعاءات.
\n\nإن لم يستقرّ promise أبدًا (stub نسي أن يُحلّ، أو await مفقود داخل حلقة)، يعلق الاختبار حتى تنتهي مهلة Vitest، وهي خمس ثوانٍ افتراضيًا، ثم يفشل بخطأ انتهاء المهلة. مرّر معاملًا ثالثًا إلى test لحالة أبطأ، أو اضبط testTimeout في الإعدادات، لكن تعامل مع الـ unit test البطيء كعلامة على مشكلة: على الأرجح يتسرّب شيء حقيقي إلى الاختبار.
في التمرين تختبر الصفوف الأربعة في ذلك الجدول وتلتقط أربعة أخطاء واقعية، منها خطأ التحصيل المزدوج. ويستبدل الدرس القادم الـ stubs المكتوبة باليد بـ vi.fn.
await دائمًا مع الـ promise أو مع الـ assertion عليه؛ فالاختبار الذي ينتهي قبل أن يستقرّ الـ promise قد ينجح أيًّا كان ما يفعله الكود.","await expect(promise).rejects.toThrow('message') هي أوضح طريقة لاختبار فشل غير متزامن.","الـ stub (بديل ثابت الاستجابة) متعاون مزيّف صغير تتحكّم فيه، مثل كائن api تنجح دالة post فيه، أو تفشل، أو تعدّ استدعاءاتها.","اختبر كل فرع من فروع معالجة الأخطاء، بما فيها الفرع الذي يجب أن يستسلم، وعُدّ الاستدعاءات حين يكون الفرق في عدد المحاولات."],"further":[{"title":"Vitest — resolves and rejects","url":"https://vitest.dev/api/expect#rejects"},{"title":"MDN — Using promises","url":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises"},{"title":"Vitest — testTimeout","url":"https://vitest.dev/config/testtimeout"}],"quiz":[{"q":"ينجح هذا الاختبار، مع أن التحقّق داخل saveExpense حُذف وصار الاستدعاء يُحلّ بنجاح. لماذا لم يلتقط الاختبار ذلك؟
test('rejects a blank description', async () => {\n try {\n await saveExpense({ description: ' ', amountCents: 100 }, api);\n } catch (error) {\n expect(error.message).toBe('Description is required');\n }\n});toBe مقارنة رسائل الأخطاء؛ يحتاج إلى toEqual.","why":"الرسائل نصوص، فيقارنها toBe بشكل صحيح؛ والمشكلة أن الـ matcher لا يُبلغ أصلًا هنا."},{"text":"حين يُحلّ الـ promise بنجاح، لا تعمل كتلة catch أبدًا، فلا يُنفَّذ أي assertion وينجح الاختبار.","why":"صحيح. استخدم await expect(...).rejects.toThrow(...)، الذي يفشل حين يُحلّ الـ promise بنجاح، أو أضف expect.assertions(1)."},{"text":"تتجاهل Vitest الأخطاء المرمية داخل كتل catch.","why":"فشل assertion داخل catch كان سيُفشل الاختبار؛ المشكلة أن catch لا تعمل أصلًا."}],"answer":1},{"q":"يجب أن تعيد saveExpense المحاولة مرة واحدة عند خطأ قابل لإعادة المحاولة، وأن تستسلم فورًا عند أي خطأ آخر. أيّ اختبار يلتقط نسخة تعيد المحاولة مع كل خطأ؟
post يرفض دائمًا بخطأ غير قابل لإعادة المحاولة، وأكّد أن الـ promise يُرفض.","why":"النسخة المعطوبة تنتهي بالرفض أيضًا (لأن محاولتها الثانية تفشل كذلك)، فلا يستطيع هذا الـ assertion وحده التمييز بين النسختين."},{"text":"اجعل الـ stub لـ post ينجح، وأكّد أن الـ id يُعاد.","why":"في المسار السعيد لا يقع أي خطأ، فلا يعمل منطق إعادة المحاولة أبدًا."},{"text":"اجعل الـ stub لـ post يرفض مرة واحدة بخطأ غير قابل لإعادة المحاولة، وعُدّ الاستدعاءات، وأكّد أنها واحدة بالضبط.","why":"صحيح. كلتا النسختين ترفضان، لكن المعطوبة وحدها تستدعي الـ API مرتين؛ وعدد الاستدعاءات هو الفرق الذي يمكن ملاحظته."}],"answer":2},{"q":"يفشل اختبار يستخدم الـ stub التالي { post: () => new Promise(() => {}) } بعد خمس ثوانٍ بسبب انتهاء المهلة. ما الذي حدث؟
await saveExpense(...) حتى تنتهي مهلة الاختبار في Vitest.","why":"صحيح. الـ promise الذي لا يُستدعى فيه resolve ولا reject يبقى معلّقًا إلى الأبد؛ اجعل الـ stub ينجح أو يرفض صراحةً."},{"text":"تحتاج Vitest إلى vi.fn() بدل الكائن العادي مع أي متعاون غير متزامن.","why":"الكائنات العادية التي تحتوي دوالًا غير متزامنة stubs صالحة تمامًا؛ المشكلة أن هذا تحديدًا لا ينتهي أبدًا."},{"text":"المهلة الافتراضية للاختبار أقصر من اللازم لكود الشبكة، ويجب رفعها إلى 30 ثانية.","why":"لا توجد شبكة هنا أصلًا. رفع المهلة يجعل الفشل نفسه يستغرق وقتًا أطول فقط."}],"answer":0}],"exercise":{"kind":"web","mode":"test","subject":"// Saves an expense through the API and resolves with the new id.\n// - Rejects with \"Description is required\" if the description is blank.\n// - Rejects with \"Amount must be positive\" unless amountCents is a\n// positive integer. Invalid input never reaches the API.\n// - If api.post fails with an error that has { retryable: true },\n// it tries exactly ONE more time.\n// - Any other API error is passed on: the promise rejects with it.\nasync function saveExpense(expense, api) {\n if (!expense.description || !expense.description.trim()) {\n throw new Error('Description is required');\n }\n if (!Number.isInteger(expense.amountCents) || expense.amountCents <= 0) {\n throw new Error('Amount must be positive');\n }\n try {\n const { id } = await api.post('/expenses', expense);\n return id;\n } catch (error) {\n if (!error.retryable) throw error;\n const { id } = await api.post('/expenses', expense);\n return id;\n }\n}\n","mutants":[{"id":"missing-await","code":"// Saves an expense through the API and resolves with the new id.\n// - Rejects with \"Description is required\" if the description is blank.\n// - Rejects with \"Amount must be positive\" unless amountCents is a\n// positive integer. Invalid input never reaches the API.\n// - If api.post fails with an error that has { retryable: true },\n// it tries exactly ONE more time.\n// - Any other API error is passed on: the promise rejects with it.\nasync function saveExpense(expense, api) {\n if (!expense.description || !expense.description.trim()) {\n throw new Error('Description is required');\n }\n if (!Number.isInteger(expense.amountCents) || expense.amountCents <= 0) {\n throw new Error('Amount must be positive');\n }\n try {\n const { id } = api.post('/expenses', expense);\n return id;\n } catch (error) {\n if (!error.retryable) throw error;\n const { id } = await api.post('/expenses', expense);\n return id;\n }\n}\n"},{"id":"swallows-error","code":"// Saves an expense through the API and resolves with the new id.\n// - Rejects with \"Description is required\" if the description is blank.\n// - Rejects with \"Amount must be positive\" unless amountCents is a\n// positive integer. Invalid input never reaches the API.\n// - If api.post fails with an error that has { retryable: true },\n// it tries exactly ONE more time.\n// - Any other API error is passed on: the promise rejects with it.\nasync function saveExpense(expense, api) {\n if (!expense.description || !expense.description.trim()) {\n throw new Error('Description is required');\n }\n if (!Number.isInteger(expense.amountCents) || expense.amountCents <= 0) {\n throw new Error('Amount must be positive');\n }\n try {\n const { id } = await api.post('/expenses', expense);\n return id;\n } catch (error) {\n if (!error.retryable) return null;\n const { id } = await api.post('/expenses', expense);\n return id;\n }\n}\n"},{"id":"no-retry","code":"// Saves an expense through the API and resolves with the new id.\n// - Rejects with \"Description is required\" if the description is blank.\n// - Rejects with \"Amount must be positive\" unless amountCents is a\n// positive integer. Invalid input never reaches the API.\n// - If api.post fails with an error that has { retryable: true },\n// it tries exactly ONE more time.\n// - Any other API error is passed on: the promise rejects with it.\nasync function saveExpense(expense, api) {\n if (!expense.description || !expense.description.trim()) {\n throw new Error('Description is required');\n }\n if (!Number.isInteger(expense.amountCents) || expense.amountCents <= 0) {\n throw new Error('Amount must be positive');\n }\n try {\n const { id } = await api.post('/expenses', expense);\n return id;\n } catch (error) {\n throw error;\n const { id } = await api.post('/expenses', expense);\n return id;\n }\n}\n"},{"id":"retries-everything","code":"// Saves an expense through the API and resolves with the new id.\n// - Rejects with \"Description is required\" if the description is blank.\n// - Rejects with \"Amount must be positive\" unless amountCents is a\n// positive integer. Invalid input never reaches the API.\n// - If api.post fails with an error that has { retryable: true },\n// it tries exactly ONE more time.\n// - Any other API error is passed on: the promise rejects with it.\nasync function saveExpense(expense, api) {\n if (!expense.description || !expense.description.trim()) {\n throw new Error('Description is required');\n }\n if (!Number.isInteger(expense.amountCents) || expense.amountCents <= 0) {\n throw new Error('Amount must be positive');\n }\n try {\n const { id } = await api.post('/expenses', expense);\n return id;\n } catch (error) {\n \n const { id } = await api.post('/expenses', expense);\n return id;\n }\n}\n"}],"starter":{"js":"const dinner = { description: 'Dinner', amountCents: 4500 };\n\n// A stub API: each call to post runs the next step in the list.\n// A step is either a value to resolve with or an Error to reject with.\nfunction stubApi(...steps) {\n const api = {\n calls: 0,\n async post() {\n const step = steps[api.calls];\n api.calls += 1;\n if (step instanceof Error) throw step;\n return step;\n },\n };\n return api;\n}\n\nconst retryable = (message) => Object.assign(new Error(message), { retryable: true });\n\ndescribe('saveExpense', () => {\n test('rejects a blank description without calling the API', async () => {\n const api = stubApi({ id: 'e1' });\n\n await expect(saveExpense({ description: ' ', amountCents: 100 }, api)).rejects.toThrow('Description is required');\n expect(api.calls).toBe(0);\n });\n\n // Add: the happy path, a retryable error followed by success,\n // and a non-retryable error.\n});\n"},"solution":{"js":"const dinner = { description: 'Dinner', amountCents: 4500 };\n\nfunction stubApi(...steps) {\n const api = {\n calls: 0,\n async post() {\n const step = steps[api.calls];\n api.calls += 1;\n if (step instanceof Error) throw step;\n return step;\n },\n };\n return api;\n}\n\nconst retryable = (message) => Object.assign(new Error(message), { retryable: true });\n\ndescribe('saveExpense', () => {\n test('rejects a blank description without calling the API', async () => {\n const api = stubApi({ id: 'e1' });\n\n await expect(saveExpense({ description: ' ', amountCents: 100 }, api)).rejects.toThrow('Description is required');\n expect(api.calls).toBe(0);\n });\n\n test('resolves with the id from the API', async () => {\n const api = stubApi({ id: 'e1' });\n\n await expect(saveExpense(dinner, api)).resolves.toBe('e1');\n expect(api.calls).toBe(1);\n });\n\n test('retries once after a retryable error', async () => {\n const api = stubApi(retryable('Timed out'), { id: 'e2' });\n\n await expect(saveExpense(dinner, api)).resolves.toBe('e2');\n expect(api.calls).toBe(2);\n });\n\n test('passes on a non-retryable error without retrying', async () => {\n const api = stubApi(new Error('Amount too large'), { id: 'e3' });\n\n await expect(saveExpense(dinner, api)).rejects.toThrow('Amount too large');\n expect(api.calls).toBe(1);\n });\n});\n"},"checks":[{"id":"passes","suite":"subject"},{"id":"catches-missing-await","suite":"missing-await"},{"id":"catches-swallows-error","suite":"swallows-error"},{"id":"catches-no-retry","suite":"no-retry"},{"id":"catches-retries-everything","suite":"retries-everything"}],"title":"اختبر كل فروع saveExpense","prompt":"تتحقّق saveExpense(expense, api) من المصروف، وتستدعي api.post، وتعيد المحاولة مرة واحدة عند الأخطاء المعلَّمة بـ retryable: true، وتمرّر أي خطأ آخر كما هو. قواعدها مذكورة في تعليق الـ subject.
يعطيك الكود المبدئي الدالة المساعدة stubApi(...steps): كل استدعاء لـ post يستخدم الخطوة التالية، فيُحلّ بكائن أو يُرفض بـ Error، ويعدّ api.calls الاستدعاءات. وهناك أيضًا الدالة المساعدة retryable(message).
أضف اختبارات حتى تلتقط مجموعتك أربعة أخطاء مخفيّة: await مفقود، وcatch تعيد null بدل الرفض، ونسخة لا تعيد المحاولة أبدًا، ونسخة تعيد المحاولة مع كل خطأ. تذكّر أن تضع await قبل كل resolves وrejects.
stubApi({ id: 'e1' }) ثم await expect(saveExpense(dinner, api)).resolves.toBe('e1'). هذا وحده يلتقط الـ await المفقود.","لإعادة المحاولة: يجب أن يُحلّ stubApi(retryable('Timed out'), { id: 'e2' }) بالقيمة 'e2' بعد استدعاءين.","للخطأ غير القابل لإعادة المحاولة: يجب أن يُرفض stubApi(new Error('Amount too large'), { id: 'e3' }) بتلك الرسالة وأن يكون api.calls يساوي 1. عدد الاستدعاءات يثبّت قاعدة “لا إعادة محاولة” مباشرةً، أيًّا كانت الخطوة الثانية في الـ stub."],"explanation":"الاختبارات الأربعة تعكس الفروع الأربعة. المسار السعيد يلتقط الـ await المفقود: تفكيك promise معلّق يعطي id === undefined. واختبار إعادة المحاولة يلتقط النسخة التي لا تعيد المحاولة أبدًا. أما اختبار الخطأ غير القابل لإعادة المحاولة فيؤدّي مهمّتين: rejects.toThrow يلتقط الـ catch التي تبتلع الأخطاء (لأنها تُحلّ بـ null)، وexpect(api.calls).toBe(1) يلتقط النسخة التي تعيد المحاولة مع كل شيء. لو كان الـ stub يفشل في كل استدعاء، لكان هذا الخطأ الأخير غير مرئي لـ assertion الرفض، لأن محاولته الثانية ستفشل هي أيضًا؛ وفي تطبيق حقيقي هو الخطأ الذي يحصّل المبلغ من البطاقة مرتين. أما هنا فخطوة الـ stub الثانية نجاح، فتُحلّ النسخة المعطوبة بـ 'e3' وتُفشل assertion الـ rejects أيضًا؛ لكن عدد الاستدعاءات هو ما يثبّت القاعدة أيًّا كان إعداد الـ stub.