Jest v29-v30 Matcher Migration

• Jest 30 Announcement
• Official migration guide

Overview

The jest30-matcher-upgrade codemod is designed to assist developers in updating their test codebases by transforming deprecated Jest matchers to their newer counterparts in Jest version 30. This is particularly useful as Jest has deprecated several older matchers, and using the updated ones ensures compatibility and takes advantage of any bug fixes or improvements in the newer API.

Purpose

This codemod identifies and replaces deprecated Jest matchers with the new recommended matchers. With the release of Jest 30, some matchers have been renamed to provide consistency and clarity in testing assertions. This codemod automates the transformation process, saving developers time and reducing the potential for errors during manual updates.

Before and After Examples

Before

Consider a test file that uses the older matcher names:

// Example test file

test('example test', () => {
  const mockFn = jest.fn();
  mockFn();

  expect(mockFn).toBeCalled();
  expect(mockFn).toBeCalledTimes(1);
  expect(mockFn).toBeCalledWith('arg1');
  expect(mockFn).lastCalledWith('arg2');
  expect(mockFn).nthCalledWith(1, 'arg3');
  expect(mockFn).toReturn();
  expect(mockFn).toReturnTimes(1);
  expect(mockFn).toReturnWith('value');
  expect(mockFn).lastReturnedWith('lastValue');
  expect(mockFn).nthReturnedWith(1, 'nthValue');
  expect(() => danger()).toThrowError('boom');
});

After

After running the codemod, the test file will be transformed to:

// Example test file

test('example test', () => {
  const mockFn = jest.fn();
  mockFn();

  expect(mockFn).toHaveBeenCalled();
  expect(mockFn).toHaveBeenCalledTimes(1);
  expect(mockFn).toHaveBeenCalledWith('arg1');
  expect(mockFn).toHaveBeenLastCalledWith('arg2');
  expect(mockFn).toHaveBeenNthCalledWith(1, 'arg3');
  expect(mockFn).toHaveReturned();
  expect(mockFn).toHaveReturnedTimes(1);
  expect(mockFn).toHaveReturnedWith('value');
  expect(mockFn).toHaveLastReturnedWith('lastValue');
  expect(mockFn).toHaveNthReturnedWith(1, 'nthValue');
  expect(() => danger()).toThrow('boom');
});

Usage

Use this codemod to upgrade your test files seamlessly, ensuring they are compatible with Jest 30 matcher updates.

By applying these transformations, developers can maintain up-to-date test suites that align with the latest Jest practices, which ultimately contributes to more robust and future-proof testing strategies.