Eric Campbell 5 min read Engineering

JavaScript Jest: Complete Testing Framework

Jest emerged from Facebook's need for a testing framework that actually worked without hours of configuration. Before Jest, JavaScript testing meant cobbling together Mocha, Chai, Sinon, and...

Key Insights

  • Jest’s zero-configuration philosophy means you can start testing immediately, but understanding its configuration options unlocks powerful customization for complex projects
  • Effective mocking is the difference between brittle, slow tests and fast, isolated unit tests—master jest.fn() and jest.mock() early
  • Code coverage metrics are useful guardrails, not goals; 100% coverage doesn’t mean bug-free code, but strategic coverage thresholds catch regressions

Introduction to Jest

Jest emerged from Facebook’s need for a testing framework that actually worked without hours of configuration. Before Jest, JavaScript testing meant cobbling together Mocha, Chai, Sinon, and Istanbul—each with its own documentation, configuration, and quirks. Jest unified everything into a single package with sensible defaults.

Today, Jest dominates JavaScript testing. It’s the default for Create React App, Vue CLI, and most modern JavaScript tooling. The reasons are straightforward: it’s fast (parallel test execution), it’s complete (assertions, mocking, coverage built-in), and it works out of the box.

But “zero-config” doesn’t mean “no learning required.” Understanding Jest deeply transforms your testing from checkbox compliance to genuine quality assurance.

Setup and Configuration

Start with installation:

npm install --save-dev jest

For TypeScript projects, add the necessary dependencies:

npm install --save-dev jest @types/jest ts-jest

Add test scripts to your package.json:

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

For most projects, you’ll want a jest.config.js file. Here’s a practical configuration for a TypeScript Node.js project:

/** @type {import('jest').Config} */
module.exports = {
  preset: 'ts-jest',
  testEnvironment: 'node',
  roots: ['<rootDir>/src'],
  testMatch: ['**/*.test.ts'],
  collectCoverageFrom: [
    'src/**/*.ts',
    '!src/**/*.d.ts',
    '!src/index.ts'
  ],
  coverageThreshold: {
    global: {
      branches: 80,
      functions: 80,
      lines: 80,
      statements: 80
    }
  },
  clearMocks: true,
  resetMocks: true
};

For React projects with JSX, adjust the environment and add transform rules:

module.exports = {
  testEnvironment: 'jsdom',
  setupFilesAfterEnv: ['<rootDir>/src/setupTests.ts'],
  moduleNameMapper: {
    '\\.(css|less|scss)$': 'identity-obj-proxy',
    '^@/(.*)$': '<rootDir>/src/$1'
  }
};

The clearMocks and resetMocks options are crucial. They ensure each test starts with fresh mock state, preventing the nightmare of tests that pass individually but fail when run together.

Writing Your First Tests

Jest uses a familiar structure. The describe block groups related tests, while it or test (they’re identical) defines individual test cases:

// src/utils/math.ts
export function add(a: number, b: number): number {
  return a + b;
}

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

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

describe('math utilities', () => {
  describe('add', () => {
    it('adds two positive numbers', () => {
      expect(add(2, 3)).toBe(5);
    });

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

    it('handles zero', () => {
      expect(add(5, 0)).toBe(5);
    });
  });

  describe('divide', () => {
    it('divides two numbers', () => {
      expect(divide(10, 2)).toBe(5);
    });

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

Name your tests as specifications. Reading “add adds two positive numbers” tells you exactly what the function should do. Avoid vague names like “works correctly” or “handles edge cases.”

Place test files next to the code they test. math.ts and math.test.ts in the same directory makes navigation trivial and keeps related code together.

Matchers and Assertions

Jest’s matchers are expressive and cover virtually every assertion you’ll need.

Equality matchers are the foundation:

// toBe uses Object.is (strict equality)
expect(2 + 2).toBe(4);
expect('hello').toBe('hello');

// toEqual recursively checks object equality
expect({ name: 'Alice' }).toEqual({ name: 'Alice' });
expect([1, 2, 3]).toEqual([1, 2, 3]);

// toStrictEqual also checks for undefined properties
expect({ a: undefined }).not.toStrictEqual({});

Truthiness matchers handle null, undefined, and boolean logic:

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

Collection matchers work with arrays and objects:

const shoppingList = ['milk', 'bread', 'eggs'];

expect(shoppingList).toContain('milk');
expect(shoppingList).toHaveLength(3);

const user = { name: 'Alice', age: 30, email: 'alice@example.com' };

expect(user).toHaveProperty('name');
expect(user).toHaveProperty('age', 30);
expect(user).toMatchObject({ name: 'Alice' });

String matchers support regex:

expect('team').not.toMatch(/I/);
expect('Christoph').toMatch(/stop/);

For custom assertions you use repeatedly, create custom matchers:

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

expect(100).toBeWithinRange(90, 110);

Mocking and Spies

Mocking isolates the code under test from its dependencies. Without mocking, a test for your user service would hit the actual database, making tests slow, flaky, and dependent on external state.

Mock functions with jest.fn():

const mockCallback = jest.fn((x: number) => x + 1);

[1, 2, 3].forEach(mockCallback);

expect(mockCallback).toHaveBeenCalledTimes(3);
expect(mockCallback).toHaveBeenCalledWith(1);
expect(mockCallback).toHaveBeenLastCalledWith(3);
expect(mockCallback.mock.results[0].value).toBe(2);

Module mocking replaces entire imports:

// src/services/userService.ts
import { db } from './database';

export async function getUser(id: string) {
  return db.users.findById(id);
}

// src/services/userService.test.ts
import { getUser } from './userService';
import { db } from './database';

jest.mock('./database');

const mockDb = db as jest.Mocked<typeof db>;

describe('userService', () => {
  beforeEach(() => {
    jest.clearAllMocks();
  });

  it('fetches user by id', async () => {
    const mockUser = { id: '1', name: 'Alice' };
    mockDb.users.findById.mockResolvedValue(mockUser);

    const result = await getUser('1');

    expect(mockDb.users.findById).toHaveBeenCalledWith('1');
    expect(result).toEqual(mockUser);
  });
});

Spying on methods lets you track calls without replacing implementation:

const video = {
  play() {
    return true;
  }
};

const spy = jest.spyOn(video, 'play');
video.play();

expect(spy).toHaveBeenCalled();
spy.mockRestore(); // Restore original implementation

Async Testing Patterns

Modern JavaScript is asynchronous. Jest handles this elegantly.

Async/await is the cleanest approach:

async function fetchUserData(userId: string): Promise<User> {
  const response = await fetch(`/api/users/${userId}`);
  if (!response.ok) {
    throw new Error('User not found');
  }
  return response.json();
}

// Test file
import { fetchUserData } from './api';

global.fetch = jest.fn();

describe('fetchUserData', () => {
  it('returns user data on success', async () => {
    const mockUser = { id: '1', name: 'Alice' };
    (fetch as jest.Mock).mockResolvedValue({
      ok: true,
      json: () => Promise.resolve(mockUser)
    });

    const result = await fetchUserData('1');

    expect(result).toEqual(mockUser);
    expect(fetch).toHaveBeenCalledWith('/api/users/1');
  });

  it('throws on failure', async () => {
    (fetch as jest.Mock).mockResolvedValue({ ok: false });

    await expect(fetchUserData('1')).rejects.toThrow('User not found');
  });
});

Fake timers control time-based code:

function debounce<T extends (...args: unknown[]) => void>(
  fn: T,
  delay: number
): T {
  let timeoutId: NodeJS.Timeout;
  return ((...args: unknown[]) => {
    clearTimeout(timeoutId);
    timeoutId = setTimeout(() => fn(...args), delay);
  }) as T;
}

describe('debounce', () => {
  beforeEach(() => {
    jest.useFakeTimers();
  });

  afterEach(() => {
    jest.useRealTimers();
  });

  it('delays function execution', () => {
    const fn = jest.fn();
    const debounced = debounce(fn, 1000);

    debounced();
    expect(fn).not.toHaveBeenCalled();

    jest.advanceTimersByTime(1000);
    expect(fn).toHaveBeenCalledTimes(1);
  });
});

Code Coverage and Best Practices

Generate coverage reports with:

jest --coverage

Configure meaningful thresholds in jest.config.js:

coverageThreshold: {
  global: {
    branches: 80,
    functions: 80,
    lines: 80,
    statements: 80
  },
  './src/utils/': {
    branches: 100,
    functions: 100
  }
}

For CI integration, add coverage to your workflow:

# .github/workflows/test.yml
name: Test
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm test -- --coverage --ci
      - uses: codecov/codecov-action@v3

Best practices I’ve learned from maintaining large test suites:

Treat test code like production code. Refactor duplicated setup into helper functions. Name things clearly. Delete tests that no longer provide value.

Test behavior, not implementation. If you refactor a function’s internals without changing its contract, tests shouldn’t break.

Keep tests fast. Mock external dependencies. Use fake timers. Run tests in parallel. A slow test suite is a test suite that developers skip.

Write tests that fail meaningfully. When a test fails, the error message should tell you what went wrong without digging through code.

Jest is a tool. Like any tool, its value comes from how you use it. Start simple, add complexity only when needed, and always ask: does this test help me ship better software?

Liked this? There's more.

Every week: one practical technique, explained simply, with code you can use immediately.