🧪 Introduction to Jest

The Safety Net

Picture a trapeze artist working high above the crowd. The daring flips only look effortless because there is a net below — one that turns a potential disaster into a harmless bounce. In software, automated tests are that net. They let you refactor boldly, ship on Friday, and sleep on the weekend, because the moment a change breaks something, a test goes red and tells you exactly where.

Testing is not one single activity. It comes in layers, each answering a different question about your code. Today's lesson lives in the bottom, widest layer — unit tests — but it helps to see the whole pyramid first.

A healthy project has many fast unit tests at the base, fewer integration tests in the middle, and a handful of slow end-to-end tests at the top. Jest is the tool we'll use for the base, and the same skills carry upward into the other layers.

Why Jest?

Jest is an open-source testing framework maintained by Meta and now stewarded by the OpenJS Foundation. Think of it as a Swiss Army knife: instead of gluing together a test runner, an assertion library, and a mocking tool, you get all three in one install that "just works" for most JavaScript projects.

Key features

• Zero configuration: point it at a project and it runs — no config file required to start
• Fast & parallel: test files run in parallel worker processes
• Rich matchers: a large, readable vocabulary of assertions
• Built-in mocking: jest.fn(), module mocks, and fake timers, no add-ons
• Code coverage: a coverage report with a single flag
• Watch mode: re-runs only the tests affected by your last edit
• Helpful failures: colored diffs that point straight at the mismatch

Installing & Configuring Jest

Jest is a development-only dependency — you need it while building, not when your app runs in production. Install it with the --save-dev flag inside any project that already has a package.json.

# Install Jest as a dev dependency
npm install --save-dev jest

# Verify the install
npx jest --version

Add npm scripts

Typing npx jest works, but a script is friendlier for your team. Add these to package.json:

{
  "scripts": {
    "test": "jest",
    "test:watch": "jest --watch",
    "test:coverage": "jest --coverage"
  }
}

Now npm test runs the whole suite once, npm run test:watch keeps it running as you code, and npm run test:coverage tells you which lines your tests actually touched.

A config file (only when you need one)

Jest runs with sensible defaults, so you often need no config at all. When you do — for example, to test browser-style code that expects a document — add a jest.config.js file:

// jest.config.js
/** @type {import('jest').Config} */
module.exports = {
  // 'node' for backend code; 'jsdom' simulates a browser DOM.
  // (For jsdom you must also: npm install --save-dev jest-environment-jsdom)
  testEnvironment: 'node',

  // Which files count as tests. This is the default — shown for clarity.
  testMatch: ['**/__tests__/**/*.[jt]s', '**/?(*.)+(spec|test).[jt]s'],

  // Collect coverage from your source, but ignore entry points.
  collectCoverageFrom: ['src/**/*.js', '!src/index.js'],
};

Your First Test

Let's test something tiny and real. Create a module with a few pure math functions, then a test file that proves they behave. Jest automatically finds any file ending in .test.js.

The code under test

// math.js
export function add(a, b) {
  return a + b;
}

export function divide(a, b) {
  if (b === 0) {
    throw new Error('Cannot divide by zero');
  }
  return a / b;
}

The test file

// math.test.js
import { add, divide } from './math';

// describe() groups related tests and names the "unit" under test.
describe('math', () => {
  // Each test() (alias: it()) is one specific expectation.
  test('adds two positive numbers', () => {
    expect(add(1, 2)).toBe(3);
  });

  test('adds negative numbers correctly', () => {
    expect(add(-1, -1)).toBe(-2);
  });

  test('divides evenly', () => {
    expect(divide(6, 2)).toBe(3);
  });

  test('throws when dividing by zero', () => {
    // Note: pass a FUNCTION to expect, so Jest can call it and catch the throw.
    expect(() => divide(5, 0)).toThrow('Cannot divide by zero');
  });
});

Run it with npm test and you'll see something like:

PASS  ./math.test.js
  math
    ✓ adds two positive numbers (2 ms)
    ✓ adds negative numbers correctly
    ✓ divides evenly
    ✓ throws when dividing by zero (1 ms)

Test Suites: 1 passed, 1 total
Tests:       4 passed, 4 total

Read the anatomy of that first test out loud: "expect the result of add(1, 2) toBe 3." That readability is the whole point — a good test doubles as documentation.

Test Structure & the AAA Pattern

Well-written tests share a shape, like chapters in a book. Inside every test body, most people follow Arrange, Act, Assert — set up the world, do the thing, then check the result. Separating those three phases (even with blank lines) makes a test instantly scannable.

test('updating a name leaves the email untouched', () => {
  // Arrange — set up the test data and conditions
  const user = { id: 1, name: 'John Doe', email: 'john@example.com' };

  // Act — execute the code being tested
  const updated = updateProfile(user, { name: 'John Smith' });

  // Assert — check the results
  expect(updated.name).toBe('John Smith');
  expect(updated.email).toBe('john@example.com');
});

Matchers

A matcher is the part after expect(value) that describes what you expect. Each one is like a different lens for inspecting a result. Here are the ones you'll use constantly.

Equality: toBe vs toEqual

// toBe uses Object.is — great for numbers, strings, booleans (primitives).
expect(2 + 2).toBe(4);

// toEqual recursively compares the CONTENTS of objects and arrays.
expect({ name: 'John' }).toEqual({ name: 'John' });
expect([1, 2, 3]).toEqual([1, 2, 3]);

// This is the classic beginner bug:
// expect({ name: 'John' }).toBe({ name: 'John' }); // ❌ FAILS — different objects in memory

Truthiness & numbers

expect(true).toBeTruthy();
expect(0).toBeFalsy();
expect(null).toBeNull();
expect(undefined).toBeUndefined();
expect('hi').toBeDefined();

expect(10).toBeGreaterThan(5);
expect(5).toBeLessThanOrEqual(5);
// Floating point? Use toBeCloseTo, never toBe:
expect(0.1 + 0.2).toBeCloseTo(0.3); // ✅ (0.1 + 0.2 is 0.30000000000000004)

Strings, arrays & errors

expect('Hello World').toMatch(/World/);       // regex or substring
expect(['apple', 'banana']).toContain('banana');
expect([1, 2, 3]).toHaveLength(3);

// Testing that code throws — pass a function wrapper:
expect(() => {
  throw new Error('Invalid input');
}).toThrow('Invalid input');

Negation with .not

expect('team').not.toMatch(/I/);
expect([1, 2]).not.toContain(3);

expect.extend({
  toBeWithinRange(received, floor, ceiling) {
    const pass = received >= floor && received <= ceiling;
    return {
      pass,
      message: () =>
        `expected ${received} ${pass ? 'not ' : ''}to be within ${floor}–${ceiling}`,
    };
  },
});

test('score is in range', () => {
  expect(100).toBeWithinRange(90, 110);
  expect(101).not.toBeWithinRange(0, 100);
});

Testing Asynchronous Code

Most real code waits on something — a network request, a database, a timer. Testing async code is like ordering a pizza: you have to actually wait for delivery before you check the order. The golden rule is to return or await the promise so Jest knows to wait too.

// A function that resolves or rejects a promise:
function fetchUser(id) {
  return new Promise((resolve, reject) => {
    setTimeout(() => {
      id === 1
        ? resolve({ id: 1, name: 'John Doe' })
        : reject(new Error('User not found'));
    }, 50);
  });
}

// Cleanest style: async/await
test('fetches a user by id', async () => {
  const user = await fetchUser(1);
  expect(user.name).toBe('John Doe');
});

// The .resolves / .rejects helpers read nicely too:
test('resolves to the right object', async () => {
  await expect(fetchUser(1)).resolves.toEqual({ id: 1, name: 'John Doe' });
});

test('rejects for a missing user', async () => {
  await expect(fetchUser(999)).rejects.toThrow('User not found');
});

Running Tests & Watch Mode

Once tests exist, you'll run them constantly. Three commands cover almost everything.

Watch mode is your day-to-day companion. It watches for file changes and, by default, only re-runs tests related to what you edited. Inside watch mode you can press keys to filter:

 › Press a to run all tests.
 › Press f to run only failed tests.
 › Press p to filter by a filename regex pattern.
 › Press t to filter by a test-name regex pattern.
 › Press q to quit watch mode.
 › Press Enter to trigger a test run.

A coverage report shows the percentage of statements, branches, functions, and lines your tests exercised — and, crucially, the line numbers they missed:

--------------------|---------|----------|---------|---------|-------------------
File                | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
--------------------|---------|----------|---------|---------|-------------------
All files           |   85.71 |      100 |   83.33 |   85.71 |
 math.js            |     100 |      100 |     100 |     100 |
 userService.js     |   71.43 |      100 |      50 |   71.43 | 7-9
--------------------|---------|----------|---------|---------|-------------------

Practice & Quiz

// calc.js
export function multiply(a, b) {
  return a * b;
}
export function percentOf(part, whole) {
  if (whole === 0) throw new Error('whole cannot be zero');
  return (part / whole) * 100;
}

import { multiply, percentOf } from './calc';

describe('calc', () => {
  test('multiplies two numbers', () => {
    expect(multiply(3, 4)).toBe(12);
  });

  test('computes a percentage', () => {
    expect(percentOf(25, 200)).toBe(12.5);
  });

  test('throws when whole is zero', () => {
    expect(() => percentOf(1, 0)).toThrow('whole cannot be zero');
  });
});

// title.js
export async function getTitle(api, id) {
  const post = await api.fetchPost(id);
  return post.title.toUpperCase();
}

import { getTitle } from './title';

test('uppercases the fetched title', async () => {
  const api = { fetchPost: jest.fn().mockResolvedValue({ title: 'hello' }) };
  await expect(getTitle(api, 1)).resolves.toBe('HELLO');
  expect(api.fetchPost).toHaveBeenCalledWith(1);
});

test('propagates a fetch error', async () => {
  const api = { fetchPost: jest.fn().mockRejectedValue(new Error('boom')) };
  await expect(getTitle(api, 1)).rejects.toThrow('boom');
});

Best Practices & Pitfalls

✅ Do

• Name tests as behavior sentences: 'throws when dividing by zero'
• Keep each test focused on one assertion of behavior
• Use toEqual for objects/arrays, toBe for primitives
• Always await (or return) async expectations
• Run watch mode while coding so feedback is instant

❌ Don't

• Write test('test 1', ...) — a failing name should explain itself
• Compare floats with toBe — use toBeCloseTo
• Call a throwing function directly inside expect()
• Chase 100% coverage at the cost of meaningful assertions

Summary

📚 Additional Resources

• Jest — Getting Started
• Jest — Expect & the full matcher list
• Jest — Testing Asynchronous Code
• MDN — Tools and testing

🚀 What's Next?

You can now write and run a test. Next we go deeper into the craft: what makes a unit test good — fast, isolated, repeatable — and how to test pure functions, classes, and error paths with confidence. That's Writing Unit Tests.