From 9ffdc11da28d9787c92a525f12ac54c1143a2f1f Mon Sep 17 00:00:00 2001 From: Tom Mrazauskas Date: Sun, 17 Apr 2022 16:55:12 +0300 Subject: [PATCH 1/5] add upgrading guide --- docs/UpgradingToJest28.md | 185 ++++++++++++++++++++++++++++++++++++++ website/sidebars.json | 3 +- 2 files changed, 187 insertions(+), 1 deletion(-) create mode 100644 docs/UpgradingToJest28.md diff --git a/docs/UpgradingToJest28.md b/docs/UpgradingToJest28.md new file mode 100644 index 000000000000..6975edc62999 --- /dev/null +++ b/docs/UpgradingToJest28.md @@ -0,0 +1,185 @@ +--- +id: upgrading-to-jest28 +title: From v27 to v28 +--- + +Upgrading Jest from v27 to v28? This guide aims to help refactoring your configuration and tests. + +:::info + +See [changelog](https://github.com/facebook/jest/blob/main/CHANGELOG.md) for the full list of changes. + +::: + +## Compatibility + +The lowest supported versions are: + +- Node 12.13, 14.15, 16.13 or above +- TypeScript 4.3 + +## Configuration Options + +### `extraGlobals` + +The `extraGlobals` option was renamed to [`sandboxInjectedGlobals`](Configuration.md#sandboxinjectedglobals-arraystring): + +```diff +- extraGlobals: ['Math'] ++ sandboxInjectedGlobals: ['Math'] +``` + +### `timers` + +The `timers` option was renamed to [`fakeTimers`](Configuration.md#faketimers-object). See [Fake Timers](#fake-timers) section bellow for details. + +### `testURL` + +The `testURL` option is removed. Now you should use [`testEnvironmentOptions`](Configuration.md#testenvironmentoptions-object) to pass `url` option to JSDOM environment: + +```diff +- 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`](https://github.com/sinonjs/fake-timers). + +### `fakeTimers` + +The `timers` configuration option was renamed to [`fakeTimers`](Configuration.md#faketimers-object) and now takes an object with options: + +```diff +- timers: 'real' ++ fakeTimers: { ++ enableGlobally: false ++ } +``` + +```diff +- timers: 'fake' ++ fakeTimers: { ++ enableGlobally: true ++ } +``` + +```diff +- timers: 'modern' ++ fakeTimers: { ++ enableGlobally: true ++ } +``` + +```diff +- timers: 'legacy' ++ fakeTimers: { ++ enableGlobally: true, ++ legacyFakeTimers: true ++ } +``` + +### `jest.useFakeTimers()` + +An object with options now should be passed to [`jest.useFakeTimers()`](JestObjectAPI.md#jestusefaketimersfaketimersconfig) as well: + +```diff +- jest.useFakeTimers('modern') ++ jest.useFakeTimers() +``` + +```diff +- 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: + +```diff +- jest.useFakeTimers('modern') ++ jest.useFakeTimers({ ++ legacyFakeTimers: false ++ }) +``` + +## Test Environment + +### Custom Environment + +The constructor of [test environment](Configuration.md#testenvironment-string) class now receives an object with Jest's `globalConfig` and `projectConfig` as its first argument. The second argument is now mandatory. + +```diff + 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](Configuration.md#testenvironment-string), `jest-environment-jsdom` package now must be installed additionally: + +```bash npm2yarn +npm install --save-dev jest-environment-jsdom +``` + +## Test Runner + +If you are using Jasmine [test runner](Configuration.md#testrunner-string), `jest-jasmine2` package now must be installed additionally: + +```bash npm2yarn +npm install --save-dev jest-jasmine2 +``` + +## Transformer + +`process()` and `processAsync()` methods of a custom [transformer module](CodeTransformation.md) cannot return a string anymore. They must always return an object: + +```diff + 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'`: + +```ts +import {jest} from '@jest/globals'; +``` + +::: + +### `jest.fn()` + +`jest.fn()` now takes only one generic type argument. See [Mock Functions API](MockFunctionAPI.md) page for more usage examples. + +```diff + import add from './add'; +- const mockAdd = jest.fn, Parameters>(); ++ const mockAdd = jest.fn(); +``` + +```diff +- const mock = jest.fn() ++ const mock = jest.fn<() => number>() + .mockReturnValue(42) + .mockReturnValueOnce(12); + +- const asyncMock = jest.fn, []>() ++ const asyncMock = jest.fn<() => Promise>() + .mockResolvedValue('default') + .mockResolvedValueOnce('first call'); +``` diff --git a/website/sidebars.json b/website/sidebars.json index d40f62713a60..3f05a1a9c107 100644 --- a/website/sidebars.json +++ b/website/sidebars.json @@ -32,7 +32,8 @@ "tutorial-react", "tutorial-react-native", "testing-frameworks" - ] + ], + "Upgrade Guides": ["upgrading-to-jest28"] }, "api": [ "api", From 47935e265faff06946d8bd7b02734f52d9fd0e46 Mon Sep 17 00:00:00 2001 From: Tom Mrazauskas Date: Sun, 17 Apr 2022 17:15:10 +0300 Subject: [PATCH 2/5] add changelog entry --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index ce5503c5fcf3..9ef27d625f0e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -85,6 +85,7 @@ - `[docs, examples]` Update React examples to match with the new React guidelines for code examples ([#12217](https://github.com/facebook/jest/pull/12217)) - `[docs]` Add clarity for module factory hoisting limitations ([#12453](https://github.com/facebook/jest/pull/12453)) - `[docs]` Add more information about how code transformers work ([#12407](https://github.com/facebook/jest/pull/12407)) +- `[docs]` Add upgrading guide ([#12633](https://github.com/facebook/jest/pull/12407)) - `[expect]` [**BREAKING**] Remove support for importing `build/utils` ([#12323](https://github.com/facebook/jest/pull/12323)) - `[expect]` [**BREAKING**] Migrate to ESM ([#12344](https://github.com/facebook/jest/pull/12344)) - `[expect]` [**BREAKING**] Snapshot matcher types are moved to `@jest/expect` ([#12404](https://github.com/facebook/jest/pull/12404)) From 3a98b97e76e5b71ee88bcf04f6e099ae228d598e Mon Sep 17 00:00:00 2001 From: Tom Mrazauskas Date: Mon, 18 Apr 2022 11:07:47 +0300 Subject: [PATCH 3/5] fix changelog --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9ef27d625f0e..a0c9b6a7f6b8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -85,7 +85,7 @@ - `[docs, examples]` Update React examples to match with the new React guidelines for code examples ([#12217](https://github.com/facebook/jest/pull/12217)) - `[docs]` Add clarity for module factory hoisting limitations ([#12453](https://github.com/facebook/jest/pull/12453)) - `[docs]` Add more information about how code transformers work ([#12407](https://github.com/facebook/jest/pull/12407)) -- `[docs]` Add upgrading guide ([#12633](https://github.com/facebook/jest/pull/12407)) +- `[docs]` Add upgrading guide ([#12633](https://github.com/facebook/jest/pull/12633)) - `[expect]` [**BREAKING**] Remove support for importing `build/utils` ([#12323](https://github.com/facebook/jest/pull/12323)) - `[expect]` [**BREAKING**] Migrate to ESM ([#12344](https://github.com/facebook/jest/pull/12344)) - `[expect]` [**BREAKING**] Snapshot matcher types are moved to `@jest/expect` ([#12404](https://github.com/facebook/jest/pull/12404)) From 191f93747c8199d4953443d60336b33c680cd587 Mon Sep 17 00:00:00 2001 From: Tom Mrazauskas Date: Mon, 18 Apr 2022 14:25:15 +0300 Subject: [PATCH 4/5] fix: separately --- docs/UpgradingToJest28.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/UpgradingToJest28.md b/docs/UpgradingToJest28.md index 6975edc62999..263099e59f10 100644 --- a/docs/UpgradingToJest28.md +++ b/docs/UpgradingToJest28.md @@ -123,7 +123,7 @@ The constructor of [test environment](Configuration.md#testenvironment-string) c ### `jsdom` -If you are using JSDOM [test environment](Configuration.md#testenvironment-string), `jest-environment-jsdom` package now must be installed additionally: +If you are using JSDOM [test environment](Configuration.md#testenvironment-string), `jest-environment-jsdom` package now must be installed separately: ```bash npm2yarn npm install --save-dev jest-environment-jsdom @@ -131,7 +131,7 @@ npm install --save-dev jest-environment-jsdom ## Test Runner -If you are using Jasmine [test runner](Configuration.md#testrunner-string), `jest-jasmine2` package now must be installed additionally: +If you are using Jasmine [test runner](Configuration.md#testrunner-string), `jest-jasmine2` package now must be installed separately: ```bash npm2yarn npm install --save-dev jest-jasmine2 From 3041a432cf2111f05902abccf29bdbff85f597c2 Mon Sep 17 00:00:00 2001 From: Tom Mrazauskas Date: Mon, 18 Apr 2022 19:52:36 +0300 Subject: [PATCH 5/5] fix Compatibility --- docs/UpgradingToJest28.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/UpgradingToJest28.md b/docs/UpgradingToJest28.md index 263099e59f10..d6d682656687 100644 --- a/docs/UpgradingToJest28.md +++ b/docs/UpgradingToJest28.md @@ -13,10 +13,9 @@ See [changelog](https://github.com/facebook/jest/blob/main/CHANGELOG.md) for the ## Compatibility -The lowest supported versions are: +The supported Node versions are 12.13, 14.15, 16.13 and above. -- Node 12.13, 14.15, 16.13 or above -- TypeScript 4.3 +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