Splitwise-lite saves expenses over a phone connection on a train. Requests fail. Some failures are worth one retry (a timeout); others are not (the server says the amount is invalid). The code that decides is a dozen lines, and it is exactly the code nobody tests, because “it’s async” and “it needs the API”. Neither is a real obstacle.
\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}Because it’s an async function, every throw inside it becomes a rejected promise. Callers (and tests) never see a synchronous exception; they see a promise that rejects.
Vitest waits for a test that is async or returns a promise. Inside, you have two good options:
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});You can also await the call and assert on the value: const id = await saveExpense(...); expect(id).toBe('e1');. For rejections, prefer rejects over try/catch: if the promise unexpectedly resolves, rejects fails the test, while a try/catch silently skips the catch block and passes. (If you must use try/catch, put expect.assertions(1) at the top so Vitest fails when no assertion ran.)
saveExpense talks to an api. In a test you don’t want a real server; you want an object whose post does whatever this test needs. That object is a stub, and you don’t need a library to write one:
// 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});Passing api in as a parameter is what makes this easy. Code that imports a global client deep inside is much harder to test; you meet the tools for that (and their cost) in the next lesson.
Error handling has more branches than the happy path, and each one is a decision someone made. For saveExpense:
| Situation | \nExpected | \n
|---|---|
| API succeeds | \nresolves with the id, one call | \n
| Retryable error, then success | \nresolves with the id, two calls | \n
| Non-retryable error | \nrejects with that error, one call | \n
| Invalid input | \nrejects with a validation message, zero calls | \n
The third row is the one people skip, and it hides two common bugs: a catch that swallows the error and returns null (callers think the save worked), and a catch that retries everything (a rejected payment charged twice). The rejection alone can’t distinguish the second bug, because the retry fails too. Counting the calls can.
Notice the last row too: invalid input should make zero calls. That is a promise about side effects, and it matters. A version that validates after posting would still reject with the right message, so only the call count proves the bad expense never reached the server.
\n\nIf a promise never settles (a stub that forgets to resolve, a missing await in a loop), the test hangs until Vitest’s timeout, five seconds by default, and fails with a timeout error. Pass a third argument to test for a slower case, or set testTimeout in the config, but treat a slow unit test as a smell: something real is probably leaking in.
In the exercise you test all four rows of that table and catch four realistic bugs, including the double-charge one. The next lesson replaces the hand-written stubs with vi.fn.
await the promise or the assertion on it; a test that ends before the promise settles can pass no matter what the code does.","await expect(promise).rejects.toThrow('message') is the clearest way to test an async failure.","A stub is a tiny fake collaborator you control, such as an api object whose post method succeeds, fails or counts its calls.","Test every branch of error handling, including the one that should give up, and count calls when the difference is how many attempts were made."],"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":"This test passes, yet the validation in saveExpense was deleted and the call now resolves. Why didn’t the test catch it?
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 can’t compare error messages; it needs toEqual.","why":"Messages are strings, so toBe compares them correctly; the matcher is never reached here."},{"text":"When the promise resolves, the catch block never runs, so no assertion executes and the test passes.","why":"Correct. Use await expect(...).rejects.toThrow(...), which fails when the promise resolves, or add expect.assertions(1)."},{"text":"Vitest ignores errors thrown inside catch blocks.","why":"An assertion failing inside catch would fail the test; the problem is that the catch never runs at all."}],"answer":1},{"q":"saveExpense should retry once on a retryable error, but give up immediately on any other error. Which test catches a version that retries every error?
post to always reject with a non-retryable error and assert the promise rejects.","why":"The buggy version also ends up rejecting (its retry fails too), so this assertion alone can’t tell the versions apart."},{"text":"Stub post to resolve and assert the id is returned.","why":"On the happy path no error happens, so the retry logic never runs."},{"text":"Stub post to reject once with a non-retryable error, count the calls, and assert there was exactly one.","why":"Correct. Both versions reject, but only the buggy one calls the API twice; the call count is the observable difference."}],"answer":2},{"q":"A test that uses the stub { post: () => new Promise(() => {}) } fails after five seconds with a timeout. What happened?
await saveExpense(...) waits until Vitest’s test timeout.","why":"Correct. A promise with no resolve or reject call stays pending forever; make the stub resolve or reject explicitly."},{"text":"Vitest needs vi.fn() instead of a plain object for any async collaborator.","why":"Plain objects with async methods are perfectly valid stubs; the issue is this one never finishes."},{"text":"The default test timeout is too short for network code and should be raised to 30 seconds.","why":"There is no network here. Raising the timeout only makes the same failure take longer."}],"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":"Test every branch of saveExpense","prompt":"saveExpense(expense, api) validates the expense, calls api.post, retries once on errors marked retryable: true, and passes every other error on. Its rules are in the subject’s comment.
The starter gives you a stubApi(...steps) helper: each call to post uses the next step, resolving with an object or rejecting with an Error, and api.calls counts the calls. There is also a retryable(message) helper.
Add tests until your suite catches four hidden bugs: a missing await, a catch that returns null instead of rejecting, a version that never retries, and a version that retries every error. Remember to await every resolves and rejects.
stubApi({ id: 'e1' }) and await expect(saveExpense(dinner, api)).resolves.toBe('e1'). That alone catches the missing await.","For the retry: stubApi(retryable('Timed out'), { id: 'e2' }) must resolve with 'e2' after two calls.","For a non-retryable error: stubApi(new Error('Amount too large'), { id: 'e3' }) must reject with that message and api.calls must be 1. The call count states the “don’t retry” rule directly, whatever the stub’s second step does."],"explanation":"The four tests mirror the four branches. The happy path catches the missing await: destructuring a pending promise gives id === undefined. The retry test catches the version that never retries. The non-retryable test does double duty: rejects.toThrow catches the catch that swallows errors (it resolves with null), and expect(api.calls).toBe(1) catches the version that retries everything. If the stub failed on every call, that last bug would be invisible to the rejection assertion, because its retry would fail too; in a real app it is the one that charges a card twice. Here the stub’s second step is a success, so the buggy version also resolves with 'e3' and fails the rejects assertion; the call count is what pins the rule no matter how the stub is set up.