UpgradingToJest28.md

id	title
upgrading-to-jest28	From v27 to v28

Upgrading Jest from v27 to v28? This guide aims to help refactoring your configuration and tests.

:::info

See changelog for the full list of changes.

:::

Compatibility

The supported Node versions are 12.13, 14.15, 16.13 and above.

If you plan to use type definitions of Jest (or any of its packages), make sure to install TypeScript version 4.3 or above.

Configuration Options

extraGlobals

The extraGlobals option was renamed to sandboxInjectedGlobals:

- extraGlobals: ['Math']
+ sandboxInjectedGlobals: ['Math']

timers

The timers option was renamed to fakeTimers. See Fake Timers section bellow for details.

testURL

The testURL option is removed. Now you should use testEnvironmentOptions to pass url option to JSDOM environment:

- testURL: 'https://jestjs.io'
+ testEnvironmentOptions: {
+   url: 'https://jestjs.io'
+ }

Fake Timers

Fake timers were refactored to allow passing options to the underlying @sinonjs/fake-timers.

fakeTimers

The timers configuration option was renamed to fakeTimers and now takes an object with options:

- timers: 'real'
+ fakeTimers: {
+   enableGlobally: false
+ }

- timers: 'fake'
+ fakeTimers: {
+   enableGlobally: true
+ }

- timers: 'modern'
+ fakeTimers: {
+   enableGlobally: true
+ }

- timers: 'legacy'
+ fakeTimers: {
+   enableGlobally: true,
+   legacyFakeTimers: true
+ }

jest.useFakeTimers()

An object with options now should be passed to jest.useFakeTimers() as well:

- jest.useFakeTimers('modern')
+ jest.useFakeTimers()

- jest.useFakeTimers('legacy')
+ jest.useFakeTimers({
+   legacyFakeTimers: true
+ })

If legacy fake timers are enabled in Jest config file, but you would like to disable them in a particular test file:

- jest.useFakeTimers('modern')
+ jest.useFakeTimers({
+   legacyFakeTimers: false
+ })

Test Environment

Custom Environment

The constructor of test environment class now receives an object with Jest's globalConfig and projectConfig as its first argument. The second argument is now mandatory.

  class CustomEnvironment extends NodeEnvironment {
-   constructor(config) {
-     super(config);
+   constructor({globalConfig, projectConfig}, context) {
+     super({globalConfig, projectConfig}, context);
+     const config = projectConfig;

jsdom

If you are using JSDOM test environment, jest-environment-jsdom package now must be installed separately:

npm install --save-dev jest-environment-jsdom

Test Runner

If you are using Jasmine test runner, jest-jasmine2 package now must be installed separately:

npm install --save-dev jest-jasmine2

Transformer

process() and processAsync() methods of a custom transformer module cannot return a string anymore. They must always return an object:

  process(sourceText, sourcePath, options) {
-   return `module.exports = ${JSON.stringify(path.basename(sourcePath))};`;
+   return {
+     code: `module.exports = ${JSON.stringify(path.basename(sourcePath))};`,
+   };
  }

TypeScript

:::info

The TypeScript examples from this page will only work as document if you import jest from '@jest/globals':

import {jest} from '@jest/globals';

:::

jest.fn()

jest.fn() now takes only one generic type argument. See Mock Functions API page for more usage examples.

  import add from './add';
- const mockAdd = jest.fn<ReturnType<typeof add>, Parameters<typeof add>>();
+ const mockAdd = jest.fn<typeof add>();

- const mock = jest.fn<number, []>()
+ const mock = jest.fn<() => number>()
    .mockReturnValue(42)
    .mockReturnValueOnce(12);

- const asyncMock = jest.fn<Promise<string>, []>()
+ const asyncMock = jest.fn<() => Promise<string>>()
    .mockResolvedValue('default')
    .mockResolvedValueOnce('first call');