Unit testing with node:test and Vitest

The built-in runner: node:test and node:assert

Before you reach for a third-party runner, consider what you already have: since Node 18 (stable in Node 20) the built-in runner covers the whole unit-testing workflow with zero install cost, and that matters on a lean CI pipeline or a published library that can’t afford extra transitive deps.

Since Node 20 the test runner is stable and built in — no dependency, no config. You write tests with test() (or describe() / it()), assert with node:assert, and run them with node --test, which discovers files matching *.test.js, *-test.js, and files under test/ directories. Add --watch to re-run on change, and --experimental-test-coverage to get a coverage summary. Subtests nest with await t.test(...), and hooks (before, after, beforeEach, afterEach) set up and tear down state.

import { test, describe, it, beforeEach } from "node:test";
import assert from "node:assert/strict";
import { Cart } from "./cart.js";

describe("Cart", () => {
  let cart;
  beforeEach(() => { cart = new Cart(); }); // fresh state per test

  it("totals line items", () => {
    cart.add({ price: 10, qty: 2 });
    assert.strictEqual(cart.total(), 20);
  });

  it("rejects a negative quantity", () => {
    assert.throws(() => cart.add({ price: 10, qty: -1 }), /quantity/);
  });
});

The key with node:assert is to import the strict variant (node:assert/strict) so assert.equal means ===, not the loose == that quietly treats "2" and 2 as equal. assert.strictEqual compares primitives; assert.deepStrictEqual walks objects and arrays structurally; assert.match checks a string against a regex. For failures you expect, assert them directly: assert.throws(fn, /pattern/) for synchronous throws and await assert.rejects(promise, /pattern/) for rejected promises — a test that asserts the absence of an error where one should fire is a test that passes for the wrong reason.

Mocking at the boundaries

A unit test should exercise your logic, so you replace the slow or non-deterministic things at its edges — the network, the filesystem, the clock — and leave your own code real. node:test gives you mock.fn() for standalone spies, t.mock.method(obj, "name") to replace a method (auto-restored when the test ends), and t.mock.module() to swap a whole module. A spy records every call: mock.calls holds the arguments, return values, and call count, so you assert on how a collaborator was used.

import { test, mock } from "node:test";
import assert from "node:assert/strict";

test("charges the gateway once with the order total", () => {
  const gateway = { charge: mock.fn(() => ({ id: "ch_1" })) };
  const order = { total: 4200, gateway };

  checkout(order);

  assert.strictEqual(gateway.charge.mock.callCount(), 1);
  assert.deepStrictEqual(gateway.charge.mock.calls[0].arguments, [4200]);
});

The discipline that matters: mock at the boundary, not your own logic. If you mock the function under test, the test asserts your mock, not your code. Stub the payment gateway’s HTTP call; do not stub the checkout() you are trying to verify.

Choosing the runner: node:test vs Vitest vs Jest

node:test is the right default for a library or a backend with few dependencies: nothing to install, the fastest startup, and it speaks the core API. Reach for Vitest when you want Jest-style ergonomics — chainable expect matchers, inline snapshots, vi.mock, a jsdom/happy-dom environment for code that touches the DOM, TypeScript with no extra config, and a snappy HMR-powered watch that re-runs only the affected tests. Vitest is near-drop-in for Jest (vi.fn for jest.fn, vi.mock for jest.mock), so it is also the standard escape hatch from a slow Jest setup. Pick Jest itself mainly when you already have a Jest suite and plugins you do not want to migrate.

Principles that keep tests honest

When you see a test suite getting muted or skipped rather than fixed, these three rules are what was violated. Three rules separate a suite you trust from one you mute. Test behavior, not implementation: assert the observable outcome (the return value, the call to a collaborator) rather than private internals, so a refactor that keeps behavior identical does not turn the suite red. A test that breaks every time you rename a private method is testing the wrong thing. Arrange-Act-Assert: set up inputs, perform the one action, assert the one outcome — one logical assertion per test makes a failure point straight at its cause. Keep each test independent: no shared mutable state, no reliance on run order. Reset state in beforeEach; if test B only passes because test A ran first and left a row in a module-level array, you have an order-dependent suite that goes flaky the moment the runner parallelizes or shuffles.

// ❌ order-dependent: module-level state leaks between tests
const users = [];
test("a: adds a user", () => { users.push({ id: 1 }); assert.strictEqual(users.length, 1); });
test("b: starts empty", () => { assert.strictEqual(users.length, 0); }); // FAILS after a

// ✅ independent: fresh state each time
let store;
beforeEach(() => { store = new UserStore(); });