Handbooks / Node.js / Chapter 9

Testing Node Apps

7 pages · ~5 min✓ Reviewed

Builds on Authentication and Security Basics. Next up: Logging and Debugging.

Node.jsPage 1

Testing Node.js: Mental Model

1. Runner and assertions

describe/it/test register tests; the runner runs them
A thrown error marks the test failed
Runner: finds, runs, reports. assert/expect: only throw on mismatch

2. Arrange-Act-Assert

Set up inputs, call the unit once, assert the outcome
One behavior per test

javascript

import { test } from 'node:test';
import assert from 'node:assert/strict';
test('adds tax', () => {
  const price = 100;           // arrange
  const total = addTax(price); // act
  assert.equal(total, 120);    // assert
});

3. Unit vs integration

	Unit	Integration
Scope	One module	Real pieces wired
Deps	Test doubles	Real or in-memory DB
Example	Service + fake repo	HTTP layer + DB

Test behavior

Assert public output, not private calls. Internal assertions break on every refactor.

Node.jsPage 2

node:test and assert

1. Built In, No Install

import { test, describe, it, before, after, beforeEach, afterEach } from 'node:test'
Run with node --test: finds *.test.js and files under test/
Async test functions are awaited automatically

Flag	Does

Node.jsPage 3

Jest vs Vitest

1. Same API, different engine

Both ship describe/it/expect, matchers, mocks, snapshots, coverage
Vitest: Vite-powered, native ESM + TypeScript, fast watch
Jest: needs a transform (babel or ts-jest) for ESM/TS
Jest globals are automatic: jest.fn, jest.mock
Vitest needs globals: true in config, or an import
Vitest mock namespace is vi, not jest

Node.jsPage 4

Mocking Modules and Timers

1. Doubles

Double	Job
Spy	observes a real call
Stub	replaces the return value
Mock	adds call expectations

Node.jsPage 5

HTTP Handlers, Database Doubles and Coverage

1. Testing Handlers with supertest

Export app without listen(); supertest binds an ephemeral port itself
Assert status, headers, then check res.body
Test the 400, 401 and 404 paths, not only the happy path

javascript

const res = await request(app)
  .post('/users').send({ name: 'a' })
  .set('Authorization', 'Bearer t')
  .expect(201)
  .expect('Content-Type', /json/);
assert.equal(res.body.name, 'a');

Node.jsPage 6

Testing Cheat Sheet

1. Run and Assert

Runner	Run	Filter by name
node:test	`node --test`	`--test-name-pattern`
Jest	`npx jest`	`-t`
Vitest

Node.jsPage 7

Check yourself

This test stays green even when getUser(0) resolves instead of rejecting. Why?

assert.rejects returns a promise, and nothing awaits it.
The test ends first, so the check can't fail it.
Fix: make the test async and await the call.

test('bad id', () => {
  assert.rejects(getUser(0), TypeError);
});

Does expect({a:1}).toBe({a:1}) pass?

It fails: toBe uses Object.is, and these are two different objects.

`--watch`	re-run on file change
`--test-name-pattern='login'`	only matching names
`--experimental-test-coverage`	coverage report
`--test-reporter=spec`	readable output

Matcher	Checks
`toBe`	`Object.is` identity
`toEqual`	deep equality
`toStrictEqual`	deep + `undefined` props + class types
`toThrow`	call wrapped: `expect(() => fn()).toThrow()`

	Jest	Vitest
Watch	`npx jest --watch`	`npx vitest` (default in terminal)
Filter	`npx jest path -t 'name'`	`npx vitest path -t 'name'`
CI one-shot	`npx jest`	`npx vitest run`

Call	Effect
`useFakeTimers()`	fake clock on
`advanceTimersByTime(1000)`	fires due timers
`runAllTimers()`	fires all pending
`setSystemTime(date)`	sets `Date.now`

Double	Does	Example
Fake	keeps real behavior	in-memory repo, SQLite `:memory:`
Stub	returns canned rows	fixed list from `findAll`
Mock	verifies calls	`toHaveBeenCalledWith`

Testing Node Apps

Testing Node.js: Mental Model

1. Runner and assertions

2. Arrange-Act-Assert

3. Unit vs integration

node:test and assert

1. Built In, No Install

Jest vs Vitest

1. Same API, different engine

Mocking Modules and Timers

1. Doubles

HTTP Handlers, Database Doubles and Coverage

1. Testing Handlers with supertest

Testing Cheat Sheet

1. Run and Assert

Check yourself

2. Assertions

3. Spies and Fake Time

2. Matchers and async

3. Commands

2. Modules and Spies

3. Timers and Gotchas

2. Database Test Doubles

3. Real DB and Coverage

2. Mock and Time

3. HTTP, DB, Coverage

Runner	Coverage command
node:test	`node --test --experimental-test-coverage`
Jest	`jest --coverage`
Vitest	`vitest run --coverage` (v8 or istanbul)

	node:assert/strict	Jest / Vitest
Identity	`equal`	`toBe`
Deep	`deepEqual`	`toEqual`, `toStrictEqual`
Throws	`throws`	`toThrow`
Async	`await assert.rejects`	`await expect(p).rejects`