Jest Testing Framework

Overview

Jest is a delightful JavaScript testing framework with a focus on simplicity. It works with projects using Babel, TypeScript, Node, React, Angular, Vue, and more.

Quick Start

Installation:

npm install --save-dev jest

Add to package.json:

{
  "scripts": {
    "test": "jest"
  }
}

First test (sum.test.js):

const sum = require('./sum');

test('adds 1 + 2 to equal 3', () => {
  expect(sum(1, 2)).toBe(3);
});

Run tests:

npm test

Basic Test Structure

Test Blocks

• test(name, fn) - Single test
• describe(name, fn) - Groups related tests
• only - Run only this test: test.only(), describe.only()
• skip - Skip this test: test.skip(), describe.skip()

describe('Math operations', () => {
  test('adds 1 + 2 to equal 3', () => {
    expect(sum(1, 2)).toBe(3);
  });

  test('multiplies 3 * 4 to equal 12', () => {
    expect(multiply(3, 4)).toBe(12);
  });
});

Common Matchers

Exact Equality

// Primitive values
expect(2 + 2).toBe(4);

// Objects and arrays (deep equality)
expect({ one: 1, two: 2 }).toEqual({ one: 1, two: 2 });

Truthiness

toBeNull()           // matches only null
toBeUndefined()      // matches only undefined
toBeDefined()        // opposite of toBeUndefined
toBeTruthy()        // matches if statement truthy
toBeFalsy()          // matches if statement falsy

Numbers

toBeGreaterThan(3)
toBeGreaterThanOrEqual(3.5)
toBeLessThan(5)
toBeLessThanOrEqual(4.5)
toBeCloseTo(0.3)     // floating point

Strings

toMatch(/stop/)

Arrays

toContain('milk')

Negation

expect(2 + 2).not.toBe(5);

Testing Async Code

Promises

// Return the promise
test('the data is peanut butter', () => {
  return fetchData().then(data => {
    expect(data).toBe('peanut butter');
  });
});

// Use .resolves
test('the data is peanut butter', () => {
  return expect(fetchData()).resolves.toBe('peanut butter');
});

// Use .rejects
test('the fetch fails', () => {
  return expect(fetchData()).rejects.toMatch('error');
});

Async/Await

test('the data is peanut butter', async () => {
  const data = await fetchData();
  expect(data).toBe('peanut butter');
});

test('the fetch fails', async () => {
  await expect(fetchData()).rejects.toMatch('error');
});

Callbacks

test('the data is peanut butter', done => {
  function callback(data) {
    expect(data).toBe('peanut butter');
    done();
  }
  fetchDataCallback(callback);
});

Setup and Teardown

Repeating Setup (Each Test)

beforeEach(() => {
  initializeCityDatabase();
});

afterEach(() => {
  clearCityDatabase();
});

One-Time Setup

beforeAll(() => {
  return initializeCityDatabase();
});

afterAll(() => {
  return clearCityDatabase();
});

Scoping

Hooks in describe blocks apply only to tests within that block. Outer hooks run before inner hooks.

describe('outer', () => {
  beforeAll(() => { /* runs first */ });
  beforeEach(() => { /* runs before each test */ });

  describe('inner', () => {
    beforeAll(() => { /* runs second */ });
    beforeEach(() => { /* runs before each test in inner */ });
  });
});

Mocking

Mock Functions

const mockFn = jest.fn(x => 42 + x);

// Inspect calls
expect(mockFn.mock.calls.length).toBe(2);
expect(mockFn.mock.calls[0][0]).toBe(0);

// Return values
mockFn.mockReturnValueOnce(10).mockReturnValue(true);

// Implementation
mockFn.mockImplementation(() => 'default');

Module Mocking

import axios from 'axios';
jest.mock('axios');

// Mock resolved value
axios.get.mockResolvedValue({ data: users });

// Mock implementation
axios.get.mockImplementation(() => Promise.resolve(resp));

Mock Matchers

expect(mockFunc).toHaveBeenCalled();
expect(mockFunc).toHaveBeenCalledWith(arg1, arg2);
expect(mockFunc).toHaveBeenLastCalledWith(arg1, arg2);

Snapshot Testing

Basic Snapshot

test('renders correctly', () => {
  const tree = renderer.create(<Link />).toJSON();
  expect(tree).toMatchSnapshot();
});

Update Snapshots

jest --updateSnapshot
# or
jest -u

Inline Snapshots

test('renders correctly', () => {
  const tree = renderer.create(<Link />).toJSON();
  expect(tree).toMatchInlineSnapshot();
});

Property Matchers

expect(user).toMatchSnapshot({
  createdAt: expect.any(Date),
  id: expect.any(Number),
});

Configuration

Generate Config

npm init jest@latest

Config File (jest.config.js)

module.exports = {
  // Test environment
  testEnvironment: 'node', // or 'jsdom' for React

  // Test file patterns
  testMatch: [
    '**/__tests__/**/*.[jt]s?(x)',
    '**/?(*.)+(spec|test).[jt]s?(x)'
  ],

  // Coverage
  collectCoverageFrom: ['src/**/*.{js,jsx}'],
  coverageDirectory: 'coverage',

  // Setup files
  setupFilesAfterEnv: ['<rootDir>/src/setupTests.js'],

  // Transforms (Babel, TypeScript)
  transform: {
    '^.+\\.(js|jsx)$': 'babel-jest',
  },

  // Module mocking
  moduleNameMapper: {
    '\\.(css|less)$': 'identity-obj-proxy',
  },
};

TypeScript

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

// jest.config.js
module.exports = {
  preset: 'ts-jest',
};

React

npm install --save-dev @testing-library/react @testing-library/jest-dom jest-environment-jsdom

// jest.config.js
module.exports = {
  testEnvironment: 'jsdom',
  setupFilesAfterEnv: ['<rootDir>/src/setupTests.js'],
};

// src/setupTests.js
import '@testing-library/jest-dom';

CLI Options

jest                    # Run all tests
jest --watch            # Watch mode
jest --coverage         # Generate coverage
jest --updateSnapshot   # Update snapshots
jest --verbose          # Detailed output
jest --findRelatedTests # Test changed files

Framework-Specific Testing

React (see TutorialReact.md)

import { render, screen } from '@testing-library/react';

test('renders button', () => {
  render(<Button>Click me</Button>);
  expect(screen.getByText('Click me')).toBeInTheDocument();
});

React Native (see TutorialReactNative.md)

Use react-test-renderer for snapshot testing.

Async Patterns (see TutorialAsync.md)

Comprehensive examples for promises, async/await, callbacks, and timers.

Best Practices

1. Descriptive test names - "should return user when id exists" vs "returns user"
2. One assertion per test - Keep tests focused
3. Arrange-Act-Assert - Structure tests clearly
4. Mock external dependencies - Don't make real API calls
5. Test behavior, not implementation - Focus on what, not how
6. Use setup/teardown - Avoid code duplication
7. Keep tests deterministic - No random data or dates (mock them)

Resources

Setup & Configuration

• GettingStarted.md - Installation, Babel, TypeScript, ESLint setup
• Configuration.md - Complete config options reference
• CLI.md - All command-line options
• EnvironmentVariables.md - Environment setup
• TestingFrameworks.md - Framework-specific setup guides

Core Testing

• UsingMatchers.md - Common matchers (toBe, toEqual, truthiness, numbers, arrays)
• TestingAsyncCode.md - Promises, async/await, callbacks, timers
• SetupAndTeardown.md - beforeEach, afterEach, beforeAll, afterAll, scoping

Mocking

• MockFunctions.md - Mock functions, .mock property, return values
• MockFunctionAPI.md - Complete mock API reference
• ManualMocks.md - Manual module mocks
• Es6ClassMocks.md - ES6 class mocking
• BypassingModuleMocks.md - Bypassing module mocks

API References

• ExpectAPI.md - Complete expect() matcher reference (63k+ bytes)
• GlobalAPI.md - describe, test, it, skip, only, etc. (35k+ bytes)
• JestObjectAPI.md - Jest object API (36k+ bytes)

Advanced Features

• SnapshotTesting.md - Snapshot testing, inline snapshots, property matchers
• TimerMocks.md - Fake timers, timer mocking APIs
• CodeTransformation.md - Custom transforms
• ECMAScriptModules.md - ESM support
• WatchPlugins.md - Custom watch plugins

Framework Tutorials

• TutorialReact.md - React testing with @testing-library/react
• TutorialReactNative.md - React Native testing
• TutorialAsync.md - Async patterns and examples
• TutorialjQuery.md - jQuery testing

Integration Guides

• Webpack.md - Webpack integration
• Puppeteer.md - Puppeteer integration
• DynamoDB.md - DynamoDB testing
• MongoDB.md - MongoDB testing

Meta & Support

• Architecture.md - Jest architecture
• Troubleshooting.md - Common issues and solutions
• MigrationGuide.md - Upgrading guide
• JestPlatform.md - Jest platform packages
• JestCommunity.md - Community resources
• MoreResources.md - Additional learning resources

Assets

• assets/configs/ - Configuration templates (basic, TypeScript, Babel, React, package.json)
• assets/test-templates/ - Test file templates (basic, async, mock, snapshot, setup, react)