A test is read far more often than it is written. It is read when it fails at a bad moment, by someone who didn’t write it, who wants one answer: what broke? This lesson is about writing tests that answer that in seconds, and about reading the answer Vitest gives you.
\nNearly every good test has the same three parts:
\nimport { test, expect } from 'vitest';\nimport { withTip } from './tip.js';\n\ntest('rounds a half-cent tip up to the next cent', () => {\n // Arrange: the inputs that matter for this behaviour\n const subtotalCents = 1980;\n const percent = 12.5;\n\n // Act: one call to the code under test\n const result = withTip(subtotalCents, percent);\n\n // Assert: the claims about the outcome\n expect(result).toEqual({ tipCents: 248, totalCents: 2228 });\n});Arrange builds the world the test needs. Act does exactly one thing: the behaviour you are testing. Assert states what should now be true. You don’t need the comments once the shape is a habit; the blank lines are enough.
\nThe shape protects you from the most common smell: a test that acts, asserts, acts again, asserts again. When that fails, you can’t tell which step broke. Split it into two tests, each with a name that says what it proves.
\n“One assertion per test” is a rule you will hear, and it is too strict. The real rule is one behaviour per test. Checking both tipCents and totalCents after a single call is one behaviour with two observable facts, so asserting both is fine, and toEqual on the whole object does it in one line. What you want to avoid is a test that checks rounding, then calls the function again to check the error case, then a third time for zero. When the first claim fails, Vitest stops that test, so you never learn whether the other two behaviours still work. Three small tests report three separate answers.
When a test fails, the report prints its full path: withTip > rounds a half-cent tip up to the next cent. Write that name as a sentence about behaviour. “withTip works” tells you nothing; “rejects a negative tip percent” tells you what regressed before you open a file. Group with describe by unit, name with test by rule.
Two matchers do most of the work, and they compare differently:
\ntoBe uses Object.is: same primitive value, or the same object reference. Use it for numbers, strings and booleans.toEqual compares structure, recursively: same keys, same values. Use it for objects and arrays. (toStrictEqual also checks that undefined properties and class types match.)expect(withTip(2000, 15)).toBe({ tipCents: 300, totalCents: 2300 }) fails even though the values match, because the function returns a new object. This trips up everyone once.
Here is a real kind of bug. A first version of toCents, which turns a dollar amount into cents, used Math.floor:
const toCents = (dollars) => Math.floor(dollars * 100);\nconsole.log(0.29 * 100); // what the computer actually computes\nconsole.log(toCents(0.29)); // one cent short\nconsole.log(Math.round(0.29 * 100));The test expect(toCents(0.29)).toBe(29) fails, and Vitest reports something like this:
FAIL src/money.test.js > toCents > converts 0.29 dollars to 29 cents\nAssertionError: expected 28 to be 29 // Object.is equality\n\n- Expected\n+ Received\n\n- 29\n+ 28\n\n ❯ src/money.test.js:7:28Read it top to bottom, in three passes:
\nmoney.test.js:7:28) points at the assertion line in the test. The bug is in the code that line calls.For objects, the diff marks only the lines that differ, so a wrong totalCents inside a ten-key object stands out immediately.
Sometimes the behaviour is “refuse bad input”. Wrap the call in a function so expect can call it and catch the error:
test('rejects a negative tip percent', () => {\n expect(() => withTip(1000, -5)).toThrow(RangeError);\n});Without the arrow function, withTip throws while the arguments are being evaluated, before expect runs, and the test crashes instead of passing. toThrow also accepts a string or regex to match the message.
In the exercise you write AAA tests for withTip, including the boundary that is easy to forget: a tip of zero. The next section moves from “how a test looks” to “which tests are worth writing”.
toBe compares with Object.is (same value or same reference); toEqual compares structure, which is what you want for objects and arrays.","A failure report gives you the test path, the expected and received values, and the file and line; read all three before touching code."],"further":[{"title":"Vitest — expect API","url":"https://vitest.dev/api/expect"},{"title":"Vitest — Test API","url":"https://vitest.dev/api/test"},{"title":"MDN — Number.EPSILON and floating point","url":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/EPSILON"}],"quiz":[{"q":"What does this test report?
\ntest('builds the tip summary', () => {\n expect(withTip(2000, 15)).toBe({ tipCents: 300, totalCents: 2300 });\n});toBe checks identity with Object.is, and two separately created objects are never the same reference."},{"text":"It fails, because toBe compares references and the function returns a new object.","why":"Correct. Use toEqual (or toStrictEqual) to compare objects by their contents."},{"text":"It throws a syntax error because objects can’t be passed to toBe.","why":"Any value can be passed to toBe; the problem is the comparison it performs, not the syntax."}],"answer":1},{"q":"A failing test prints expected 28 to be 29 for toCents(0.29). Where do you look first?
0.29 * 100 is 28.999999999999996 everywhere, so the config is not involved."},{"text":"At how toCents turns the float into an integer, because 0.29 * 100 is slightly below 29.","why":"Correct. The received value tells you the code truncated a value that was a hair under 29; Math.round fixes it, Math.floor causes it."}],"answer":2},{"q":"Which test name is most useful when it fails in CI at 2 a.m.?
","options":[{"text":"test('withTip works')","why":"It says which function, not which behaviour; you still have to open the file to learn what broke."},{"text":"test('test 3')","why":"A number carries no information and becomes wrong as soon as tests are reordered."},{"text":"test('rounds a half-cent tip up to the next cent')","why":"Correct. The name states the rule, so the failure report alone tells you which behaviour regressed."},{"text":"test('withTip(1980, 12.5)')","why":"The input is visible but not the expected behaviour; the reader can’t tell what the right output was meant to be."}],"answer":2},{"q":"Why do Arrange, Act and Assert usually appear in that order, separated by a blank line?
","options":[{"text":"Vitest requires the three phases in that order or it skips the test.","why":"Vitest has no idea about phases; AAA is a convention for humans, not a rule the runner enforces."},{"text":"It makes setup, the single action under test and the claims easy to find at a glance.","why":"Correct. A consistent shape means a reader can jump straight to the action and the assertion in any test."},{"text":"It lets Vitest run the Arrange phase once for the whole file.","why":"Shared setup belongs in hooks likebeforeEach; the blank lines in a test change nothing at runtime."}],"answer":1}],"exercise":{"kind":"web","mode":"test","subject":"// Adds a tip to a subtotal. Money is in integer cents; percent is a\n// number such as 15 or 12.5. The tip is rounded to the nearest cent\n// (a half cent rounds up). A zero tip is allowed; a negative one is not.\nfunction withTip(subtotalCents, percent) {\n if (percent < 0) throw new RangeError('Tip percent cannot be negative');\n const tipCents = Math.round((subtotalCents * percent) / 100);\n return { tipCents, totalCents: subtotalCents + tipCents };\n}\n","mutants":[{"id":"floors-tip","code":"// Adds a tip to a subtotal. Money is in integer cents; percent is a\n// number such as 15 or 12.5. The tip is rounded to the nearest cent\n// (a half cent rounds up). A zero tip is allowed; a negative one is not.\nfunction withTip(subtotalCents, percent) {\n if (percent < 0) throw new RangeError('Tip percent cannot be negative');\n const tipCents = Math.floor((subtotalCents * percent) / 100);\n return { tipCents, totalCents: subtotalCents + tipCents };\n}\n"},{"id":"allows-negative","code":"// Adds a tip to a subtotal. Money is in integer cents; percent is a\n// number such as 15 or 12.5. The tip is rounded to the nearest cent\n// (a half cent rounds up). A zero tip is allowed; a negative one is not.\nfunction withTip(subtotalCents, percent) {\n \n const tipCents = Math.round((subtotalCents * percent) / 100);\n return { tipCents, totalCents: subtotalCents + tipCents };\n}\n"},{"id":"rejects-zero","code":"// Adds a tip to a subtotal. Money is in integer cents; percent is a\n// number such as 15 or 12.5. The tip is rounded to the nearest cent\n// (a half cent rounds up). A zero tip is allowed; a negative one is not.\nfunction withTip(subtotalCents, percent) {\n if (percent <= 0) throw new RangeError('Tip percent cannot be negative');\n const tipCents = Math.round((subtotalCents * percent) / 100);\n return { tipCents, totalCents: subtotalCents + tipCents };\n}\n"}],"starter":{"js":"describe('withTip', () => {\n test('adds a 15% tip to the subtotal', () => {\n // Arrange\n const subtotalCents = 2000;\n\n // Act\n const result = withTip(subtotalCents, 15);\n\n // Assert\n expect(result).toEqual({ tipCents: 300, totalCents: 2300 });\n });\n\n // Add: a half-cent tip that must round up,\n // a zero tip, and a negative percent that must throw.\n});\n"},"solution":{"js":"describe('withTip', () => {\n test('adds a 15% tip to the subtotal', () => {\n const subtotalCents = 2000;\n\n const result = withTip(subtotalCents, 15);\n\n expect(result).toEqual({ tipCents: 300, totalCents: 2300 });\n });\n\n test('rounds a half-cent tip up to the next cent', () => {\n const result = withTip(1980, 12.5);\n\n expect(result).toEqual({ tipCents: 248, totalCents: 2228 });\n });\n\n test('allows a zero tip', () => {\n const result = withTip(2000, 0);\n\n expect(result).toEqual({ tipCents: 0, totalCents: 2000 });\n });\n\n test('rejects a negative tip percent', () => {\n expect(() => withTip(2000, -5)).toThrow(RangeError);\n });\n});\n"},"checks":[{"id":"passes","suite":"subject"},{"id":"catches-floors-tip","suite":"floors-tip"},{"id":"catches-allows-negative","suite":"allows-negative"},{"id":"catches-rejects-zero","suite":"rejects-zero"}],"title":"AAA tests for withTip","prompt":"withTip(subtotalCents, percent) returns { tipCents, totalCents }. The tip is rounded to the nearest cent (a half cent rounds up), a 0% tip is valid, and a negative percent throws a RangeError.
The starter test checks a 15% tip on $20.00. Add tests in Arrange, Act, Assert shape until your suite passes on the real code and catches three hidden bugs: one floors the tip instead of rounding it, one forgets to reject negative percents, and one wrongly rejects a zero tip.
\n","hints":["A 15% tip on 2000 is exactly 300, so rounding never matters there. You need an input where the exact tip ends in .5 or more.","1980 cents at 12.5% is 247.5 cents, which must round to 248. Compare the whole object withtoEqual.","For the error, wrap the call: expect(() => withTip(2000, -5)).toThrow(RangeError). For zero, assert the result, not just that it doesn’t throw."],"explanation":"Each added test pins one rule from the spec with an input that separates right from wrong. A tip that lands on a half cent tells Math.round from Math.floor. The zero tip catches the classic boundary slip (<= instead of <), which would make Splitwise-lite refuse a perfectly normal bill. The negative case needs the arrow function so expect can catch the throw. Asserting the full { tipCents, totalCents } object with toEqual also guards the total, so one assertion covers both fields.