Jest Globals

Reference for all global functions and objects available in tests.

Test Structure

describe(name, fn)

Create a test suite:

describe('Math operations', () => {
  // tests go here
});

Nested describes:

describe('Calculator', () => {
  describe('add', () => {
    test('adds positive numbers', () => {});
  });

  describe('subtract', () => {
    test('subtracts numbers', () => {});
  });
});

test(name, fn, timeout?)

Define a test:

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

// With custom timeout (milliseconds)
test('slow operation', async () => {
  await slowOperation();
}, 10000);

it(name, fn, timeout?)

Alias for test:

it('should add numbers', () => {
  expect(1 + 2).toBe(3);
});

test.skip(name, fn) / it.skip(name, fn)

Skip a test:

test.skip('not implemented yet', () => {
  // This test won't run
});

test.only(name, fn) / it.only(name, fn)

Run only this test:

test.only('focus on this test', () => {
  // Only this test runs
});

test.todo(name)

Mark a test as todo:

test.todo('implement error handling');

Lifecycle Hooks

beforeAll(fn, timeout?)

Run once before all tests in a describe block:

describe('database tests', () => {
  beforeAll(async () => {
    await db.connect();
  });

  // tests...
});

afterAll(fn, timeout?)

Run once after all tests in a describe block:

describe('database tests', () => {
  afterAll(async () => {
    await db.disconnect();
  });

  // tests...
});

beforeEach(fn, timeout?)

Run before each test:

describe('user tests', () => {
  let user;

  beforeEach(() => {
    user = createTestUser();
  });

  test('user has name', () => {
    expect(user.name).toBeDefined();
  });
});

afterEach(fn, timeout?)

Run after each test:

describe('file tests', () => {
  afterEach(() => {
    cleanup();
  });

  // tests...
});

Expect

expect(value)

Create an expectation:

expect(2 + 2).toBe(4);
expect({ a: 1 }).toEqual({ a: 1 });

See Matchers Guide for all available matchers.

Jest Object

jest.fn(implementation?)

Create a mock function:

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

jest.spyOn(object, method)

Spy on an object method:

const spy = jest.spyOn(console, 'log');
console.log('hello');
expect(spy).toHaveBeenCalledWith('hello');
spy.mockRestore();

jest.mock(moduleName, factory?)

Mock a module:

jest.mock('./utils', () => ({
  calculate: jest.fn(() => 42),
}));

jest.unmock(moduleName)

Remove a module mock:

jest.unmock('./utils');

jest.useFakeTimers()

Enable fake timers:

jest.useFakeTimers();

setTimeout(() => callback(), 1000);
jest.advanceTimersByTime(1000);

expect(callback).toHaveBeenCalled();

jest.useRealTimers()

Restore real timers:

jest.useRealTimers();

jest.advanceTimersByTime(ms)

Advance fake timers:

jest.advanceTimersByTime(1000); // Advance 1 second

jest.runAllTimers()

Run all pending timers:

jest.runAllTimers();

jest.clearAllMocks()

Clear all mock call history:

jest.clearAllMocks();

jest.resetAllMocks()

Reset all mocks to initial state:

jest.resetAllMocks();

jest.restoreAllMocks()

Restore all mocks to original implementations:

jest.restoreAllMocks();

Mock Function Methods

mockFn.mockReturnValue(value)

Set return value:

const mock = jest.fn().mockReturnValue(42);
expect(mock()).toBe(42);

mockFn.mockReturnValueOnce(value)

Set return value for next call only:

const mock = jest.fn()
  .mockReturnValueOnce(1)
  .mockReturnValueOnce(2)
  .mockReturnValue(3);

expect(mock()).toBe(1);
expect(mock()).toBe(2);
expect(mock()).toBe(3);
expect(mock()).toBe(3);

mockFn.mockResolvedValue(value)

Return a resolved promise:

const mock = jest.fn().mockResolvedValue('data');
await expect(mock()).resolves.toBe('data');

mockFn.mockRejectedValue(error)

Return a rejected promise:

const mock = jest.fn().mockRejectedValue(new Error('fail'));
await expect(mock()).rejects.toThrow('fail');

mockFn.mockImplementation(fn)

Set mock implementation:

const mock = jest.fn().mockImplementation((x) => x * 2);
expect(mock(5)).toBe(10);

mockFn.mockClear()

Clear call history:

mock();
mock();
expect(mock).toHaveBeenCalledTimes(2);
mock.mockClear();
expect(mock).toHaveBeenCalledTimes(0);

mockFn.mockReset()

Clear calls and reset return value:

mock.mockReset();

mockFn.mockRestore()

Restore original (for spies):

const spy = jest.spyOn(obj, 'method');
spy.mockRestore();

mockFn.mock.calls

Array of call arguments:

mock('a', 'b');
mock('c');
console.log(mock.mock.calls);
// [['a', 'b'], ['c']]

mockFn.mock.results

Array of return values:

mock.mockReturnValue(42);
mock();
console.log(mock.mock.results);
// [{ type: 'return', value: 42 }]