Unit testing

Why professional code gets tests

Automated tests are executable expectations. They give you confidence before a release, protect regressions after a bug fix, document how code should behave, and make refactoring less scary because a machine checks the important promises every time.

A unit is the smallest useful behavior boundary you can test quickly. It may be one pure function, a module, or a class method with its dependencies kept small. The point is not isolation for its own sake; the point is fast feedback about one behavior.

This module stays in lanes. Here we focus on unit tests and TDD. The next lessons on the Testing & debugging path go deeper on mocks and fakes, async code, UI/end-to-end tests, and advanced debugging. For background, review pure functions, try/catch, error strategies, browser debugging, and npm scripts.

Test frameworks look large, but the core loop is small: collect named functions, run each one, catch assertion failures, and print useful results. Building a tiny runner makes the moving parts visible before you meet real tools.

Read the source line by line. The test(name, fn) helper registers behavior. equal, deepEqual, and throws turn wrong behavior into errors. run() catches those errors so the suite can report every pass and fail instead of stopping at the first problem.

1function createTinyRunner() {2  const cases = [];Run3  function test(name, fn) {4    cases.push({ name, fn });5  }6  function equal(actual, expected, message) {7    if (!Object.is(actual, expected)) {8      throw new Error(message ?? `expected ${JSON.stringify(actual)} to equal ${JSON.stringify(expected)}`);9    }10  }11  function deepEqual(actual, expected, message) {12    if (JSON.stringify(actual) !== JSON.stringify(expected)) {13      throw new Error(message ?? `expected ${JSON.stringify(actual)} to deepEqual ${JSON.stringify(expected)}`);14    }15  }16  function throws(fn, messageIncludes) {17    try {18      fn();19    } catch (error) {20      if (messageIncludes && !String(error.message).includes(messageIncludes)) {21        throw new Error(`expected error message to include ${messageIncludes}`);22      }23      return;24    }25    throw new Error("expected function to throw");26  }27  function run() {28    return cases.map(({ name, fn }) => {29      try {30        fn();31        return { name, status: "pass" };32      } catch (error) {33        return { name, status: "fail", message: error.message };34      }35    });36  }37  return { test, equal, deepEqual, throws, run };38}39 40function cartTotal(items, code = "") {41  let total = 0;42  for (const item of items) {43    if (item.price < 0) throw new Error("negative prices are invalid");44    total += item.price;45  }46  if (code === "SAVE10") return total; // bug: discount ignored47  return total;48}49function discountLabels(items) {50  return items.flatMap((item) => item.discounts ?? []);51}52function formatResults(results) {53  return results.map((result) => result.status === "pass"54    ? `PASS ${result.name}`55    : `FAIL ${result.name}: ${result.message}`).join("\n");56}57 58const { test, equal, deepEqual, throws, run } = createTinyRunner();59test("totals item prices", () => {60  equal(cartTotal([{ name: "Book", price: 20 }, { name: "Pen", price: 5 }]), 25);61});62test("treats an empty cart as 0", () => {63  equal(cartTotal([]), 0);64});65test("collects discount labels", () => {66  deepEqual(discountLabels([{ name: "Book", price: 20, discounts: ["SAVE10"] }]), ["SAVE10"]);67});68test("rejects negative prices", () => {69  throws(() => cartTotal([{ name: "Bug", price: -1 }]), "negative");70});71test("applies SAVE10 discount", () => {72  equal(cartTotal([{ name: "Book", price: 20 }, { name: "Pen", price: 5 }], "SAVE10"), 15, "SAVE10 removes 10 dollars");73});74 75console.log(formatResults(run()));

The default suite has one failing behavior: the cart ignores SAVE10. That is a useful failure because it names the broken behavior and includes the message SAVE10 removes 10 dollars. Switch to the fixed implementation and replay the same suite to see all tests pass.

An assertion is the sentence that can fail. Use strict equality for primitives and exact references, deep equality for arrays and objects, and error assertions when invalid input should throw. Prefer one behavior per test so a failure points to one promise.

1function equal(actual, expected) {2  if (!Object.is(actual, expected)) {3    throw new Error(`expected ${JSON.stringify(actual)} to strictly equal ${JSON.stringify(expected)}`);4  }5}6function check(name, fn) {7  try { fn(); return "PASS " + name; }8  catch (error) { return "FAIL " + name + ": " + error.message; }9}10console.log(check("0 is not false", () => equal(0, false)));

Strict comparisons avoid the trap of loose equality. 0 == false is true in JavaScript, but a test should normally use Object.is, assert.equal from node:assert/strict, or expect(value).toBe(expected). Deep equality is for structure; it should not hide which behavior matters. Error assertions should check the message or error class so any random throw does not pass.

import assert from "node:assert/strict";

await assert.rejects(
  () => loadUser("offline"),
  /offline/,
  "offline users should reject with a clear message",
);

Promise rejection tests use the same idea, but the assertion must be awaited. The async testing lesson will cover promises, timers, and flaky tests in depth.

Arrange-Act-Assert keeps tests readable. Arrange prepares inputs and expected values. Act calls the unit once. Assert compares the actual behavior to the expected behavior. Behavior-driven teams often say the same pattern as Given-When-Then.

1// Arrange: prepare the input and expected behavior.2const cart = [{ price: 20 }, { price: 5 }];3const expected = 25;4 5// Act: call the unit once.6const actual = cart.reduce((total, item) => total + item.price, 0);7 8// Assert: compare behavior, not implementation details.9console.log(actual === expected ? "PASS cart totals prices" : "FAIL cart totals prices");

Line 2 is arranged input. Line 6 is the action. Line 9 is the assertion. The test name should read like a sentence, such as “returns 0 for an empty cart.” Avoid names like “line 7 works” because implementation lines change during refactors.

Choose edge cases before production users do: empty arrays, boundary values, duplicate values, invalid input, and the smallest or largest values your unit promises to handle. A unit test is most valuable when it catches a real mistake without requiring a browser or a database.

Real projects use a runner instead of a tiny hand-written loop. Node 18+ and current Node 20/22 include node:test and node:assert. Run tests with node --test. Node 22 also supports watch mode with --watch, coverage with --experimental-test-coverage, and --test-only for tests marked .only.

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

function formatPrice(cents) {
  if (!Number.isInteger(cents) || cents < 0) {
    throw new RangeError("cents must be a non-negative integer");
  }
  return "$" + (cents / 100).toFixed(2);
}

describe("formatPrice", () => {
  it("formats cents as dollars", () => {
    assert.equal(formatPrice(1299), "$12.99");
  });

  it("rejects negative cents", () => {
    assert.throws(() => formatPrice(-1), /non-negative/);
  });
});

TAP version 13
# Subtest: formatPrice
    # Subtest: formats cents as dollars
    ok 1 - formats cents as dollars
    # Subtest: rejects negative cents
    ok 2 - rejects negative cents
    1..2
ok 1 - formatPrice
1..1
# tests 2
# suites 1
# pass 2
# fail 0
# cancelled 0
# skipped 0
# todo 0

That output is a trimmed TAP report generated from the file above during this lesson’s test suite. Durations are omitted so the lesson stays stable, but the pass/fail lines are real.

node --test
node --test tests/price.test.mjs
node --test --watch
node --test --experimental-test-coverage
node --test-only

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

describe("slugify", () => {
  it("lowercases and hyphenates words", () => {
    assert.equal(slugify("Hello Tests"), "hello-tests");
  });

  test.skip("documents a skipped behavior", () => {});
  test.todo("supports non-Latin characters");
  test.only("run this with node --test-only", () => {});
});

Vitest is Vite-native and offers a Jest-compatible expect API, fast watch mode, and in-source tests with import.meta.vitest. Jest is a mature framework with a large ecosystem, snapshots, jsdom test environments for UI code, and a history of working through CommonJS, Babel, and TypeScript transforms.

import { describe, expect, test } from "vitest";
import { slugify } from "./slugify";

describe("slugify", () => {
  test("lowercases and hyphenates words", () => {
    expect(slugify("Hello Tests")).toBe("hello-tests");
  });
});

// In-source testing is also possible with Vitest:
if (import.meta.vitest) {
  const { expect, test } = import.meta.vitest;
  test("keeps numbers", () => {
    expect(slugify("Release 22")).toBe("release-22");
  });
}

import { describe, expect, test } from "@jest/globals";
import { render } from "@testing-library/react";

test("button keeps its accessible name", () => {
  const { container } = render(<button>Save</button>);
  expect(container.firstChild).toMatchSnapshot();
});

describe("price math", () => {
  test("formats cents", () => {
    expect(formatPrice(1299)).toBe("$12.99");
  });
});

This repository’s client tests use node:test. Look in apps/client-ui/tests and you will see files importing test from node:test and assertions from node:assert/strict. The lesson test you are reading follows the same pattern.

// apps/client-ui/tests/lesson-unit-testing.test.mjs
import assert from "node:assert/strict";
import { test } from "node:test";
import { article } from "../src/components/courses/javascript/unit-testing/unit-testing-lesson.ts";

test("the article definition is valid", () => {
  assert.equal(article.curriculum?.lesson, "unit-testing");
});

Test-driven development turns tests into a design tool. Write a test that fails for the next behavior you want. Make it pass with the smallest change. Then refactor names, structure, and duplication while the tests stay green.

1const allTests = [Run2  { name: "trims spaces and joins words", input: " Hello Tests ", expected: "hello-tests" },3  { name: "removes punctuation", input: "Red, green, refactor!", expected: "red-green-refactor" },4  { name: "keeps numbers", input: "Release 22", expected: "release-22" },5];6const activeTests = allTests.slice(0, 1);7 8function slugify(title) {9  return title;10}11 12function check({ name, input, expected }) {13  const actual = slugify(input);14  return actual === expected15    ? `PASS ${name}`16    : `FAIL ${name}: expected ${expected}, got ${actual}`;17}18 19console.log(activeTests.map(check).join("\n"));

The slugify feature starts with a simple behavior: trim spaces and join words. The next test adds punctuation removal. The refactor keeps the behavior green while the implementation becomes a more general rule. The test list grows because each new example describes a behavior, not a private implementation step.

In production code, unit tests help most when they describe stable behavior: parsing a price, formatting a slug, selecting a discount, choosing a validation error, or preserving a public function contract. They should not fail because you renamed a private variable.

1function total(items, code = "") {2  if (items.length === 0) return 0;3  const sum = items.reduce((amount, item) => amount + item, 0);4  if (code === "SAVE10") return sum; // bug5  return sum;6}7 8const checks = [9  { name: "empty cart is zero", actual: total([]), expected: 0 },10  { name: "adds item prices", actual: total([20, 5]), expected: 25 },11  { name: "SAVE10 removes ten dollars", actual: total([20, 5], "SAVE10"), expected: 15 },12];13 14console.log(checks.map(({ name, actual, expected }) =>15  actual === expected16    ? `PASS ${name}`17    : `FAIL ${name}: expected ${expected}, got ${actual}`18).join("\n"));

Write tests for the behavior that would worry you during a refactor. If changing a loop to reduce breaks a test, the test probably knows too much about implementation. If changing discount math breaks the “SAVE10 removes ten dollars” test, the test protected the right promise.

Common misconceptions

• “A unit is always one function.” A unit is a useful behavior boundary. Sometimes that is a function; sometimes it is a module with a small public API.
• “More mocks mean better unit tests.” Mocks can isolate, but too many mocks test implementation wiring instead of behavior. The next lesson covers mocks and fakes.
• “Snapshots are unit tests by default.” Snapshots can catch UI output changes, but they need review and intent. Jest popularized them; use them carefully.
• “One huge test gives more confidence.” Smaller tests usually fail with a clearer message. Put one behavior in each test when you can.
• “A passing suite proves there are no bugs.” Tests only prove the cases you wrote. Keep adding tests when bugs escape.

Key takeaways

• Unit tests describe fast, focused behavior and make regressions visible.
• A runner collects named tests; assertions throw failures; reports turn failures into feedback.
• Use strict equality, deep equality, throws, and awaited rejects for the behavior being checked.
• Arrange inputs, act once, and assert one behavior with a useful test name.
• node:test is built into Node; Vitest and Jest add different ecosystems and ergonomics.
• TDD is red, green, refactor: one failing behavior, one passing change, one safe cleanup.

Up next in this module: mocks, spies, and fakes show how to isolate time, randomness, storage, and network boundaries without turning every test into an implementation script.