Test TypeScript Logic with Vitest

A unit test checks a function’s observable contract: given an input, what result or failure should a caller observe? It does not need a browser, React rendering, or a live service.

In this tutorial, the contracts are workshop-booking rules in ordinary TypeScript modules. Vitest runs those local logic checks in Node’s default environment. Component and browser tests are separate concerns for later tutorials.

Create a self-contained folder named vitest-booking-lab. In a terminal, install the runner, TypeScript, and Node type definitions as development dependencies. The install creates package.json and a lockfile; create the src folder for the TypeScript files.

Before installing, ensure your installed Node.js version satisfies the Vitest version’s Node requirement. Check your local version with node --version, then compare it with the requirement reported by the Vitest release you install.

Run these commands from the parent folder where you want the project to live.

Create tsconfig.json in the project root with this strict configuration. It includes only files in src.

Set the project to use ES modules and add the three scripts below. These scripts are different checks, even though each is started with npm.

Do not run the test scripts yet: the first test is added in the next step.

Run these commands inside vitest-booking-lab. They update the package.json you created.

Match each command to the check it performs.

A unit test checks a function’s observable contract without a browser, React rendering, or a live service. For this workshop example, totalSeats receives valid bookings and returns their combined seat count.

In src/booking.ts, define the shared type and function below. The reduction starts at 0, so an empty collection can later produce a numeric total without special setup. The function reads each booking and does not change the input array.

Create or replace src/booking.ts with this implementation.

Put the colocated test in src/booking.test.ts. The explicit Vitest imports provide the test API:

• describe groups behavior for one exported function.
• it gives one observable behavior a readable name.
• expect checks the result.

The test follows Arrange, Act, Assert. It verifies the returned number with toBe; it does not care whether the implementation uses reduce, a loop, or another internal technique.

Create src/booking.test.ts.

First, run the suite once. This is single-run mode: Vitest executes the discovered tests and then finishes.

Run this command from the vitest-booking-lab folder.

Then start watch mode. While it remains active, make a harmless change in src/booking.test.ts—for example, add one space to a blank line—and save. Vitest reruns the test after the save. Stop it with Ctrl+C in the terminal.

parseBooking is a runtime boundary: it receives unknown data and returns a Booking only when the value meets the booking contract.

For a successful result, the input must be a non-null object, not an array. It needs an attendee string that remains nonempty after trimming, plus an integer seats value from 1 through 6. The parser does not convert '2' into the number 2.

A successful result is a new Booking. It contains the trimmed attendee and validated seat count, but not unrelated input fields.

Keep the existing Booking type and totalSeats function in src/booking.ts. Add this complete parser export below them. Its implementation is supplied so this step can focus on checking its successful returned result.

For a number, toBe checks a primitive result. For a parser result, use toEqual to compare the Booking structure and field values.

Two object literals with matching fields are still separate objects in memory. toBe is identity-style comparison for objects, so it is not appropriate when the expected Booking is constructed separately.

Replace the contents of src/booking.test.ts with this cumulative file. It preserves the earlier totalSeats suite, imports both application functions once, and adds the parseBooking suite without duplicate Vitest imports.

Invalid external data is part of a parser’s contract. When parseBooking receives invalid input, the correct behavior is to throw Error('Invalid booking')—not to return a partial booking.

A rejection test therefore passes when Vitest observes that expected exception. An exception that occurs outside the assertion, or no exception at all, makes the test fail.

toThrow('Invalid booking') checks whether the thrown error message contains that text. It does not require an exact-message equality match.

Inside the existing describe('parseBooking', ...) suite in src/booking.test.ts, add these two test cases. Each callback delays the parser call until the matcher evaluates it.

Save the file, then run the suite once. Your exact timing and reporter formatting can vary, but the two new rejection cases should be reported as passing.

Choose cases from the written contract, not from the current implementation. A test matrix asks: which categories of input can produce meaningfully different observable outcomes?

For totalSeats, the contract distinguishes an ordinary collection, one booking, and no bookings. For parseBooking, the valid seat range has endpoints and nearby invalid values. External data can also have the wrong shape before it has become a Booking.

A focused matrix uses representative examples. It gives useful evidence for the contract; it does not prove every possible input is correct.

it.each is useful when several examples exercise one behavioral rule and differ only in their data. Store each example in an object row, then use its fields in the test title and assertion.

Use descriptive label values so a failure report identifies the input category. Keep accepted and rejected parser rows in separate parameterized groups: accepted rows return a Booking to compare, while rejected rows must throw.

Rows are data, not automatic fresh setup. If a test changes an array or object from a row, create independent local values before changing them.

Replace the entire contents of src/booking.test.ts with this first segment. It keeps the ordinary total cases and gives the empty-collection behavior its own named test. The type-only import and Booking[] annotation ensure that the empty fixture remains valid under the project's strict type check. Then append the next two segments on this screen, in order.

Replace the file contents with this first segment.

Append these case arrays directly after segment 1. Their object rows use label, input, and expected where a returned value is compared.

Finally, append this parser suite after the case arrays. The two bodies remain short because each group has one assertion pattern.

A unit test should produce the same result when it runs alone or with the complete suite. A mutable array declared outside individual tests can couple cases: one test changes the data that another test assumes is unchanged.

Construct the bookings array and its booking objects inside each ordinary total test. If a parameterized test must change row data, make a fresh array and fresh booking objects first. Parameterization repeats a test pattern; it does not clone row objects or reset mutations for you.

The first pair is coupled because both cases use and change the same array. Replace that pattern with the second pair, which constructs inputs inside each test. No lifecycle hook is needed.

A failing unit test is evidence, not an instruction to edit the assertion. Reproduce the reported defect while keeping the named empty-input test unchanged: its contract says an empty booking collection has a total of 0.

In src/booking.ts, temporarily use the faulty revision below for totalSeats, then run the complete suite in single-run mode. This revision adds 1 to every result, including the empty collection.

Temporarily replace only the totalSeats function with this faulty revision. Leave parseBooking and the cumulative tests from the previous step in place.

Run the full local suite once. The faulty accumulator affects all three totalSeats cases; the parser cases still pass. Exact timing, Vitest version, and absolute paths can vary.

The interactive exercise does not edit your local project. Now replace the faulty totalSeats function in src/booking.ts with the corrected version below. Leave it('returns 0 for no bookings', ...) unchanged in src/booking.test.ts; it is the regression test that reproduces the defect if the accumulator is changed again.

In src/booking.ts, restore this implementation. Keep the existing Booking type and parseBooking export in the same file.

Save src/booking.ts, then rerun the complete suite in single-run mode. All 15 current tests should pass before you continue to the final review.

Treat this final review as an executable audit. Your completed src/booking.test.ts should contain three named totalSeats tests: the standard total of 5, one valid booking, and returns 0 for no bookings. Keep the empty-collection case unchanged: it is the regression test for the accumulator defect.

For parseBooking, retain accepted seat endpoints 1 and 6; rejected values 0, 7, and a non-integer; and representative malformed unknown inputs. Then add one new ordinary valid record and one new malformed record. The completed suite below has 17 tests: 3 total tests, 4 accepted parser cases, and 10 rejected parser cases.

Replace the existing acceptedCases declaration with this complete version. Keep the existing it.each(acceptedCases) test body below it; do not add another import or suite.

Replace the existing rejectedCases declaration with this complete version. It preserves every contract category and adds a malformed record not used earlier. The existing parameterized rejection test will run every row.

Save src/booking.ts and src/booking.test.ts, then run both checks from the vitest-booking-lab folder. With the three total tests and the case arrays on the previous screen, Vitest runs 17 tests.