Introduction to Unit Testing and the Testing Pyramid

A unit test exercises the smallest testable piece of your codebase in isolation from all external dependencies — no database, no network, no filesystem, no random values, no real clock. In JavaScript and TypeScript a 'unit' is typically a pure function, a class method, or a composable hook.

The critical word is *isolation*. If a test fails, you should be able to pinpoint the broken logic without reading a stack trace that crosses three modules. That isolation is what makes unit tests run in under 10 milliseconds each, and what makes a suite of 1,000 tests complete in seconds.

1// Pure function — easiest to test; no dependencies to isolate
2export function calculateDiscount(price: number, percentOff: number): number {
3  if (percentOff < 0 || percentOff > 100) {
4    throw new RangeError(`percentOff must be 0-100, got ${percentOff}`);
5  }
6  return price * (1 - percentOff / 100);
7}
8
9// Unit test — no database, no HTTP, no file I/O
10import { calculateDiscount } from './pricing';
11
12test('applies 20% discount correctly', () => {
13  expect(calculateDiscount(100, 20)).toBe(80);
14});
15
16test('throws RangeError for negative discount', () => {
17  expect(() => calculateDiscount(100, -5)).toThrow(RangeError);
18});

Contrast this with an integration test that calls a real pricing API or reads from a database — that test is 100x slower and fails whenever the network is slow, even if your logic is correct. Unit tests never have that problem because they own all their inputs and outputs.

Mike Cohn's testing pyramid describes the optimal distribution of test types by count, speed, and cost. The pyramid has three layers:

Base — Unit Tests (70%): Hundreds or thousands of them. Each runs in under 5 ms. They test logic in isolation and give pinpoint failure messages. Cost per test: very low. Value per dollar: extremely high.

Middle — Integration Tests (20%): Dozens to hundreds. Each runs in 50–500 ms. They test how two or more modules cooperate — a service calling a real database, a controller parsing a real HTTP request. Cost per test: moderate.

Top — End-to-End Tests (10%): Tens, rarely hundreds. Each runs in 2–30 seconds. They test complete user flows through a real browser against a real backend. Cost per test: high. Fragile to environment changes.

1        /\
2       /  \   E2E (~10%)
3      /----\  - Real browser + real API
4     /      \ - Slow (seconds)
5    /--------\ Integration (~20%)
6   /          \ - Real DB / real HTTP
7  /------------\ Unit (~70%)
8 /              \ - Pure logic, fully mocked
9/________________\ - Milliseconds, thousands of them

The pyramid is not a rigid rule but a heuristic. A codebase with all E2E tests and no unit tests is an 'ice cream cone' anti-pattern: slow, expensive, and fragile. A codebase with only unit tests misses integration bugs.

For a typical Next.js + NestJS project, aim for: 500+ unit tests, 100+ integration tests, 30+ E2E tests. That ratio gives fast feedback locally (unit tests run on every file save) and high confidence on CI (integration + E2E run before merging).

Tim Ottinger and Brett Schuchert coined the FIRST acronym to describe properties every unit test must have:

F — Fast: A unit test must complete in milliseconds. A test that takes 2 seconds is not a unit test — something leaked in (database, HTTP call, filesystem). Fast tests run on every save, giving instant feedback.

I — Isolated / Independent: Tests must not share state. If test A stores data in a module-level variable that test B reads, running tests in a different order produces different results. Each test must set up its own state and tear it down.

R — Repeatable: Running the same test 100 times must produce the same result every time. Tests that call Date.now(), Math.random(), or real APIs are not repeatable. Mock or inject these values.

S — Self-Validating: The test must produce a clear pass or fail without a human reading output. expect(result).toBe(42) is self-validating. console.log(result) is not.

T — Timely: Tests should be written alongside or just before the code they test. Tests written months after the code skip known edge cases because the author has forgotten the intent.

1// VIOLATES Isolated — uses module-level mutation
2let counter = 0;
3test('A', () => { counter++; expect(counter).toBe(1); });
4test('B', () => { expect(counter).toBe(0); }); // FAILS if A ran first
5
6// CORRECT — each test is independent
7test('A', () => { const c = 0 + 1; expect(c).toBe(1); });
8test('B', () => { const c = 0;     expect(c).toBe(0); });
9
10// VIOLATES Repeatable — real Date produces flaky results
11test('creates timestamp', () => {
12  const ts = createRecord();
13  expect(ts.createdAt).toBe(Date.now()); // fails by microseconds
14});
15
16// CORRECT — mock the system clock
17beforeEach(() => jest.useFakeTimers());
18afterEach(() => jest.useRealTimers());
19
20test('creates timestamp', () => {
21  jest.setSystemTime(new Date('2024-01-01T00:00:00Z'));
22  const ts = createRecord();
23  expect(ts.createdAt).toBe(1704067200000);
24});

The compounding cost of untested code is best understood through the concept of technical debt interest. When you add a feature without tests, you spend 30 minutes. Six months later, when you change a related function and accidentally break the feature, you spend 4 hours debugging because there is no test to immediately point at the regression. That 4-hour debugging session is the interest payment on the 30-minute debt.

Unit tests are executable documentation. They describe the expected behavior of a function in code that cannot lie. Comments go stale — they describe what the author intended but do not fail when the code diverges. Tests fail immediately when behavior changes unexpectedly.

1// 'Documentation' that can lie:
2/**
3 * Formats a price with currency symbol.
4 * Always returns 2 decimal places.
5 */
6export function formatPrice(amount: number, currency: string): string {
7  return `${currency}${amount}`; // BUG: no decimal rounding
8}
9
10// Tests that CANNOT lie — they break when the code is wrong:
11describe('formatPrice', () => {
12  it('formats USD with 2 decimal places', () => {
13    expect(formatPrice(9.9, '$')).toBe('$9.90'); // FAILS — reveals bug
14  });
15
16  it('formats zero amount correctly', () => {
17    expect(formatPrice(0, '€')).toBe('€0.00');
18  });
19
20  it('handles large amounts', () => {
21    expect(formatPrice(1000, '$')).toBe('$1,000.00');
22  });
23});

The test suite also enables fearless refactoring. When you rewrite formatPrice using Intl.NumberFormat, you run the tests and immediately know if the behavior changed. Without tests, you manually QA every entry point — a process that slows down and becomes less thorough as deadlines approach.

Jest is the dominant JavaScript test runner, used by React, NestJS, and most of the Node.js ecosystem. Configuring it with TypeScript via ts-jest takes under 5 minutes.

1# Install Jest + TypeScript support
2npm install --save-dev jest ts-jest @types/jest typescript

1// jest.config.ts (at project root)
2import type { Config } from 'jest';
3
4const config: Config = {
5  preset: 'ts-jest',
6  testEnvironment: 'node',
7  roots: ['<rootDir>/src'],
8  testMatch: ['**/__tests__/**/*.ts', '**/*.test.ts', '**/*.spec.ts'],
9  collectCoverageFrom: [
10    'src/**/*.ts',
11    '!src/**/*.d.ts',
12    '!src/**/index.ts',
13  ],
14  coverageThreshold: {
15    global: { branches: 80, functions: 80, lines: 80, statements: 80 },
16  },
17};
18
19export default config;

1// src/math.ts
2export function add(a: number, b: number): number {
3  return a + b;
4}
5
6export function divide(a: number, b: number): number {
7  if (b === 0) throw new Error('Division by zero');
8  return a / b;
9}
10
11// src/math.test.ts
12import { add, divide } from './math';
13
14describe('add', () => {
15  it('returns the sum of two positive numbers', () => {
16    expect(add(2, 3)).toBe(5);
17  });
18
19  it('handles negative numbers', () => {
20    expect(add(-1, 1)).toBe(0);
21  });
22});
23
24describe('divide', () => {
25  it('divides two numbers correctly', () => {
26    expect(divide(10, 2)).toBe(5);
27  });
28
29  it('throws on division by zero', () => {
30    expect(() => divide(5, 0)).toThrow('Division by zero');
31  });
32});

Run npx jest to confirm both tests pass. Then npx jest --coverage to see line-by-line coverage output in the terminal and a summary table.