From v27 to v28

    info

    See changelog for the full list of changes.

    The supported Node versions are 12.13, 14.15, 16.10 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

    The extraGlobals option was renamed to sandboxInjectedGlobals:

    timers

    The timers option was renamed to fakeTimers. See section below for details.

    testURL

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

    1. - testURL: 'https://jestjs.io'
    2. + testEnvironmentOptions: {
    3. +   url: 'https://jestjs.io'
    4. + }

    expect

    In versions prior to Jest 28, toHaveProperty checked for equality instead of existence, which means that e.g. expect({}).toHaveProperty('a', undefined) is a passing test. This has been changed in Jest 28 to fail.

    Additionally, if you import expect directly, it has been changed from default export to a named export.

    1. - import expect from 'expect';
    2. + import {expect} from 'expect';
    1. - const expect = require('expect');
    2. + const {expect} = require('expect');

    Fake timers were refactored to allow passing options to the underlying .

    fakeTimers

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

    1. - timers: 'real'
    2. +   enableGlobally: false
    1. - timers: 'fake'
    2. + fakeTimers: {
    3. +   enableGlobally: true
    4. + }
    1. - timers: 'modern'
    2. + fakeTimers: {
    3. +   enableGlobally: true
    4. + }

    jest.useFakeTimers()

    An object with options now should be passed to as well:

    1. - jest.useFakeTimers('modern')
    2. + jest.useFakeTimers()
    1. - jest.useFakeTimers('legacy')
    2. + jest.useFakeTimers({
    3. +   legacyFakeTimers: true
    4. + })

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

    1. - jest.useFakeTimers('modern')
    2. + jest.useFakeTimers({
    3. +   legacyFakeTimers: false
    4. + })

    Test 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.

    1.   class CustomEnvironment extends NodeEnvironment {
    2. -   constructor(config) {
    3. -     super(config);
    4. +   constructor({globalConfig, projectConfig}, context) {
    5. +     super({globalConfig, projectConfig}, context);
    6. +     const config = projectConfig;
    1. - const TestEnvironment = require('jest-environment-node');
    3. - const TestEnvironment = require('jest-environment-jsdom');
    4. + const {TestEnvironment} = require('jest-environment-jsdom');

    jsdom

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

    • npm
    • Yarn
    1. 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
    • Yarn
    1. yarn add --dev jest-jasmine2

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

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

    package.json exports

    Jest now includes full support for package exports, which might mean that files you import are not resolved correctly.

    Additionally, Jest now supplies more conditions. jest-environment-node has node and node-addons, while jest-environment-jsdom has browser. As a result, you might e.g. get browser code which assumes ESM, when Jest provides ['require', 'browser']. You can either report a bug to the library (or Jest, the implementation is new and might have bugs!), override the conditions Jest passes (by passing the customExportConditions option to the test environment), or use a custom resolver or moduleMapper. Lots of options, and you’ll need to pick the correct one for your project.

    Known examples of packages that fails in Jest 28 are and nanoid when using the jest-environment-jsdom environment. For an analysis, and a potential workaround, see .

    TypeScript

    From v27 to v28 - 图2info

    1. 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.

    1.   import add from './add';
    2. - const mockAdd = jest.fn<ReturnType<typeof add>, Parameters<typeof add>>();
    3. + const mockAdd = jest.fn<typeof add>();
    1. - const mock = jest.fn<number, []>()
    2. + const mock = jest.fn<() => number>()
    3.     .mockReturnValue(42)
    4.     .mockReturnValueOnce(12);
    6. - const asyncMock = jest.fn<Promise<string>, []>()
    7. + const asyncMock = jest.fn<() => Promise<string>>()
    8.     .mockResolvedValueOnce('first call');