Jest Testing Guide

The definitive reference for Jest — JavaScript's most-used testing framework. Covers matchers, mocking, snapshots, async patterns, coverage configuration, and TypeScript integration.

What is Jest?

Jest is a delightful JavaScript testing framework created by Meta and open-sourced to the community. Unlike older frameworks that required assembling a separate test runner (Mocha), assertion library (Chai), and mocking library (Sinon), Jest ships all three in a single, coherent package. This zero-configuration philosophy — combined with excellent watch mode, parallel test execution, and built-in code coverage — made Jest the dominant choice for React, Node.js, and TypeScript projects alike.

Jest uses jsdom as a simulated browser environment by default, making it ideal for testing React components without a real browser. For Node.js-only code, you can set testEnvironment: 'node' for better performance. With over 40 million weekly npm downloads, Jest has shaped how an entire generation of JavaScript developers thinks about testing.

Installation & Basic Setup

# Install Jest
npm install --save-dev jest

# With TypeScript support
npm install --save-dev jest ts-jest @types/jest typescript

# jest.config.ts
export default {
  preset: 'ts-jest',
  testEnvironment: 'node',
  coverageDirectory: 'coverage',
  collectCoverageFrom: ['src/**/*.ts'],
};

Core Test Structure: describe / it / expect

Jest tests are organised into suites (describe blocks) and individual test cases (it or test). The expect() function chains to matchers like toBe, toEqual, toThrow, and many more.

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

describe('add()', () => {
  it('returns the sum of two positive numbers', () => {
    expect(add(2, 3)).toBe(5);
  });

  it('handles negative numbers', () => {
    expect(add(-1, 1)).toBe(0);
  });
});

describe('divide()', () => {
  it('divides correctly', () => {
    expect(divide(10, 2)).toBeCloseTo(5);
  });

  it('throws on division by zero', () => {
    expect(() => divide(10, 0)).toThrow('Cannot divide by zero');
  });
});

Lifecycle Hooks: beforeEach / afterEach / beforeAll / afterAll

describe('DatabaseService', () => {
  let db: DatabaseService;

  beforeAll(async () => {
    // Runs once before all tests in this describe block
    await setupTestDatabase();
  });

  beforeEach(() => {
    // Runs before each individual test
    db = new DatabaseService({ url: 'sqlite::memory:' });
  });

  afterEach(async () => {
    // Clean up state between tests
    await db.clearAll();
    jest.clearAllMocks();
  });

  afterAll(async () => {
    // Runs once after all tests complete
    await teardownTestDatabase();
  });

  it('inserts a record', async () => {
    const id = await db.insert({ name: 'Alice' });
    expect(id).toBeDefined();
  });
});

Mocking: jest.fn(), jest.spyOn(), jest.mock()

// 1. Standalone mock function
const mockFetch = jest.fn().mockResolvedValue({ json: () => ({ id: 1 }) });

// 2. Spy on an existing method (original still runs)
const consoleSpy = jest.spyOn(console, 'error').mockImplementation(() => {});

// 3. Mock an entire module
jest.mock('./emailService', () => ({
  sendEmail: jest.fn().mockResolvedValue({ messageId: 'abc123' }),
}));

import { sendEmail } from './emailService';

it('calls sendEmail with correct args', async () => {
  await notifyUser('[email protected]', 'Hello');
  expect(sendEmail).toHaveBeenCalledWith('[email protected]', expect.stringContaining('Hello'));
  expect(sendEmail).toHaveBeenCalledTimes(1);
});

Async Testing

// Async/await (preferred)
it('fetches user data', async () => {
  const user = await fetchUser(42);
  expect(user).toMatchObject({ id: 42, name: expect.any(String) });
});

// Testing rejection
it('throws on 404', async () => {
  await expect(fetchUser(9999)).rejects.toThrow('User not found');
});

// Using resolves/rejects matchers
it('resolves to a valid token', () => {
  return expect(generateToken()).resolves.toMatch(/^[A-Za-z0-9._-]+$/);
});

Key Features

• Snapshot Testing — serialise component output and detect regressions automatically
• Coverage Reports — built-in Istanbul coverage with HTML, LCOV, and text outputs
• Watch Mode — re-run only changed tests on every file save for rapid feedback
• Parallel Workers — tests run in isolated worker processes for speed and isolation
• Timer Mocking — jest.useFakeTimers() controls setTimeout, setInterval, and Date
• Global Setup/Teardown — globalSetup and globalTeardown for database migrations before the full suite
• Custom Matchers — extend expect with project-specific assertions via expect.extend()

Use Cases

• React component testing — with React Testing Library for user-centric assertions
• Node.js API unit tests — mock dependencies, test route handlers and service layers
• Utility library testing — pure function suites with high coverage targets
• Regression prevention — snapshot tests catch unintended UI or JSON output changes
• TDD workflows — watch mode makes red-green-refactor cycles instant

Comparison: Jest vs Alternatives

Pros & Cons