From 34308ae21827a44916471106b4e3afdb3779cbb1 Mon Sep 17 00:00:00 2001 From: John Undersander Date: Tue, 22 Feb 2022 02:10:45 -0600 Subject: [PATCH] docs(ES6ClassMocks): add clarity for module factory limitations (#12453) --- CHANGELOG.md | 1 + docs/Es6ClassMocks.md | 21 ++++++++++++++++++- .../version-25.x/Es6ClassMocks.md | 21 ++++++++++++++++++- .../version-26.x/Es6ClassMocks.md | 21 ++++++++++++++++++- .../version-27.0/Es6ClassMocks.md | 21 ++++++++++++++++++- .../version-27.1/Es6ClassMocks.md | 21 ++++++++++++++++++- .../version-27.2/Es6ClassMocks.md | 21 ++++++++++++++++++- .../version-27.4/Es6ClassMocks.md | 21 ++++++++++++++++++- .../version-27.5/Es6ClassMocks.md | 21 ++++++++++++++++++- 9 files changed, 161 insertions(+), 8 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d2b30e74466a..a456eb437b5d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -39,6 +39,7 @@ - `[*]` Use `globalThis` instead of `global` ([#12447](https://github.com/facebook/jest/pull/12447)) - `[docs]` Add note about not mixing `done()` with Promises ([#11077](https://github.com/facebook/jest/pull/11077)) - `[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)) - `[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)) diff --git a/docs/Es6ClassMocks.md b/docs/Es6ClassMocks.md index 3907980f80b2..ad2fe2103018 100644 --- a/docs/Es6ClassMocks.md +++ b/docs/Es6ClassMocks.md @@ -140,7 +140,13 @@ jest.mock('./sound-player', () => { }); ``` -A limitation with the factory parameter is that, since calls to `jest.mock()` are hoisted to the top of the file, it's not possible to first define a variable and then use it in the factory. An exception is made for variables that start with the word 'mock'. It's up to you to guarantee that they will be initialized on time! For example, the following will throw an out-of-scope error due to the use of 'fake' instead of 'mock' in the variable declaration: +:::caution + +Since calls to `jest.mock()` are hoisted to the top of the file, Jest prevents access to out-of-scope variables. By default, you cannot first define a variable and then use it in the factory. Jest will disable this check for variables that start with the word `mock`. However, it is still up to you to guarantee that they will be initialized on time. Be aware of [Temporal Dead Zone](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/let#temporal_dead_zone_tdz). + +::: + +For example, the following will throw an out-of-scope error due to the use of `fake` instead of `mock` in the variable declaration. ```javascript // Note: this will fail @@ -153,6 +159,19 @@ jest.mock('./sound-player', () => { }); ``` +The following will throw a `ReferenceError` despite using `mock` in the variable declaration, as the `mockSoundPlayer` is not wrapped in an arrow function and thus accessed before initialization after hoisting. + +```javascript +import SoundPlayer from './sound-player'; +const mockSoundPlayer = jest.fn().mockImplementation(() => { + return {playSoundFile: mockPlaySoundFile}; +}); +// results in a ReferenceError +jest.mock('./sound-player', () => { + return mockSoundPlayer; +}); +``` + ### Replacing the mock using [`mockImplementation()`](MockFunctionAPI.md#mockfnmockimplementationfn) or [`mockImplementationOnce()`](MockFunctionAPI.md#mockfnmockimplementationoncefn) You can replace all of the above mocks in order to change the implementation, for a single test or all tests, by calling `mockImplementation()` on the existing mock. diff --git a/website/versioned_docs/version-25.x/Es6ClassMocks.md b/website/versioned_docs/version-25.x/Es6ClassMocks.md index 3907980f80b2..ad2fe2103018 100644 --- a/website/versioned_docs/version-25.x/Es6ClassMocks.md +++ b/website/versioned_docs/version-25.x/Es6ClassMocks.md @@ -140,7 +140,13 @@ jest.mock('./sound-player', () => { }); ``` -A limitation with the factory parameter is that, since calls to `jest.mock()` are hoisted to the top of the file, it's not possible to first define a variable and then use it in the factory. An exception is made for variables that start with the word 'mock'. It's up to you to guarantee that they will be initialized on time! For example, the following will throw an out-of-scope error due to the use of 'fake' instead of 'mock' in the variable declaration: +:::caution + +Since calls to `jest.mock()` are hoisted to the top of the file, Jest prevents access to out-of-scope variables. By default, you cannot first define a variable and then use it in the factory. Jest will disable this check for variables that start with the word `mock`. However, it is still up to you to guarantee that they will be initialized on time. Be aware of [Temporal Dead Zone](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/let#temporal_dead_zone_tdz). + +::: + +For example, the following will throw an out-of-scope error due to the use of `fake` instead of `mock` in the variable declaration. ```javascript // Note: this will fail @@ -153,6 +159,19 @@ jest.mock('./sound-player', () => { }); ``` +The following will throw a `ReferenceError` despite using `mock` in the variable declaration, as the `mockSoundPlayer` is not wrapped in an arrow function and thus accessed before initialization after hoisting. + +```javascript +import SoundPlayer from './sound-player'; +const mockSoundPlayer = jest.fn().mockImplementation(() => { + return {playSoundFile: mockPlaySoundFile}; +}); +// results in a ReferenceError +jest.mock('./sound-player', () => { + return mockSoundPlayer; +}); +``` + ### Replacing the mock using [`mockImplementation()`](MockFunctionAPI.md#mockfnmockimplementationfn) or [`mockImplementationOnce()`](MockFunctionAPI.md#mockfnmockimplementationoncefn) You can replace all of the above mocks in order to change the implementation, for a single test or all tests, by calling `mockImplementation()` on the existing mock. diff --git a/website/versioned_docs/version-26.x/Es6ClassMocks.md b/website/versioned_docs/version-26.x/Es6ClassMocks.md index 3907980f80b2..ad2fe2103018 100644 --- a/website/versioned_docs/version-26.x/Es6ClassMocks.md +++ b/website/versioned_docs/version-26.x/Es6ClassMocks.md @@ -140,7 +140,13 @@ jest.mock('./sound-player', () => { }); ``` -A limitation with the factory parameter is that, since calls to `jest.mock()` are hoisted to the top of the file, it's not possible to first define a variable and then use it in the factory. An exception is made for variables that start with the word 'mock'. It's up to you to guarantee that they will be initialized on time! For example, the following will throw an out-of-scope error due to the use of 'fake' instead of 'mock' in the variable declaration: +:::caution + +Since calls to `jest.mock()` are hoisted to the top of the file, Jest prevents access to out-of-scope variables. By default, you cannot first define a variable and then use it in the factory. Jest will disable this check for variables that start with the word `mock`. However, it is still up to you to guarantee that they will be initialized on time. Be aware of [Temporal Dead Zone](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/let#temporal_dead_zone_tdz). + +::: + +For example, the following will throw an out-of-scope error due to the use of `fake` instead of `mock` in the variable declaration. ```javascript // Note: this will fail @@ -153,6 +159,19 @@ jest.mock('./sound-player', () => { }); ``` +The following will throw a `ReferenceError` despite using `mock` in the variable declaration, as the `mockSoundPlayer` is not wrapped in an arrow function and thus accessed before initialization after hoisting. + +```javascript +import SoundPlayer from './sound-player'; +const mockSoundPlayer = jest.fn().mockImplementation(() => { + return {playSoundFile: mockPlaySoundFile}; +}); +// results in a ReferenceError +jest.mock('./sound-player', () => { + return mockSoundPlayer; +}); +``` + ### Replacing the mock using [`mockImplementation()`](MockFunctionAPI.md#mockfnmockimplementationfn) or [`mockImplementationOnce()`](MockFunctionAPI.md#mockfnmockimplementationoncefn) You can replace all of the above mocks in order to change the implementation, for a single test or all tests, by calling `mockImplementation()` on the existing mock. diff --git a/website/versioned_docs/version-27.0/Es6ClassMocks.md b/website/versioned_docs/version-27.0/Es6ClassMocks.md index 3907980f80b2..ad2fe2103018 100644 --- a/website/versioned_docs/version-27.0/Es6ClassMocks.md +++ b/website/versioned_docs/version-27.0/Es6ClassMocks.md @@ -140,7 +140,13 @@ jest.mock('./sound-player', () => { }); ``` -A limitation with the factory parameter is that, since calls to `jest.mock()` are hoisted to the top of the file, it's not possible to first define a variable and then use it in the factory. An exception is made for variables that start with the word 'mock'. It's up to you to guarantee that they will be initialized on time! For example, the following will throw an out-of-scope error due to the use of 'fake' instead of 'mock' in the variable declaration: +:::caution + +Since calls to `jest.mock()` are hoisted to the top of the file, Jest prevents access to out-of-scope variables. By default, you cannot first define a variable and then use it in the factory. Jest will disable this check for variables that start with the word `mock`. However, it is still up to you to guarantee that they will be initialized on time. Be aware of [Temporal Dead Zone](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/let#temporal_dead_zone_tdz). + +::: + +For example, the following will throw an out-of-scope error due to the use of `fake` instead of `mock` in the variable declaration. ```javascript // Note: this will fail @@ -153,6 +159,19 @@ jest.mock('./sound-player', () => { }); ``` +The following will throw a `ReferenceError` despite using `mock` in the variable declaration, as the `mockSoundPlayer` is not wrapped in an arrow function and thus accessed before initialization after hoisting. + +```javascript +import SoundPlayer from './sound-player'; +const mockSoundPlayer = jest.fn().mockImplementation(() => { + return {playSoundFile: mockPlaySoundFile}; +}); +// results in a ReferenceError +jest.mock('./sound-player', () => { + return mockSoundPlayer; +}); +``` + ### Replacing the mock using [`mockImplementation()`](MockFunctionAPI.md#mockfnmockimplementationfn) or [`mockImplementationOnce()`](MockFunctionAPI.md#mockfnmockimplementationoncefn) You can replace all of the above mocks in order to change the implementation, for a single test or all tests, by calling `mockImplementation()` on the existing mock. diff --git a/website/versioned_docs/version-27.1/Es6ClassMocks.md b/website/versioned_docs/version-27.1/Es6ClassMocks.md index 3907980f80b2..ad2fe2103018 100644 --- a/website/versioned_docs/version-27.1/Es6ClassMocks.md +++ b/website/versioned_docs/version-27.1/Es6ClassMocks.md @@ -140,7 +140,13 @@ jest.mock('./sound-player', () => { }); ``` -A limitation with the factory parameter is that, since calls to `jest.mock()` are hoisted to the top of the file, it's not possible to first define a variable and then use it in the factory. An exception is made for variables that start with the word 'mock'. It's up to you to guarantee that they will be initialized on time! For example, the following will throw an out-of-scope error due to the use of 'fake' instead of 'mock' in the variable declaration: +:::caution + +Since calls to `jest.mock()` are hoisted to the top of the file, Jest prevents access to out-of-scope variables. By default, you cannot first define a variable and then use it in the factory. Jest will disable this check for variables that start with the word `mock`. However, it is still up to you to guarantee that they will be initialized on time. Be aware of [Temporal Dead Zone](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/let#temporal_dead_zone_tdz). + +::: + +For example, the following will throw an out-of-scope error due to the use of `fake` instead of `mock` in the variable declaration. ```javascript // Note: this will fail @@ -153,6 +159,19 @@ jest.mock('./sound-player', () => { }); ``` +The following will throw a `ReferenceError` despite using `mock` in the variable declaration, as the `mockSoundPlayer` is not wrapped in an arrow function and thus accessed before initialization after hoisting. + +```javascript +import SoundPlayer from './sound-player'; +const mockSoundPlayer = jest.fn().mockImplementation(() => { + return {playSoundFile: mockPlaySoundFile}; +}); +// results in a ReferenceError +jest.mock('./sound-player', () => { + return mockSoundPlayer; +}); +``` + ### Replacing the mock using [`mockImplementation()`](MockFunctionAPI.md#mockfnmockimplementationfn) or [`mockImplementationOnce()`](MockFunctionAPI.md#mockfnmockimplementationoncefn) You can replace all of the above mocks in order to change the implementation, for a single test or all tests, by calling `mockImplementation()` on the existing mock. diff --git a/website/versioned_docs/version-27.2/Es6ClassMocks.md b/website/versioned_docs/version-27.2/Es6ClassMocks.md index 3907980f80b2..ad2fe2103018 100644 --- a/website/versioned_docs/version-27.2/Es6ClassMocks.md +++ b/website/versioned_docs/version-27.2/Es6ClassMocks.md @@ -140,7 +140,13 @@ jest.mock('./sound-player', () => { }); ``` -A limitation with the factory parameter is that, since calls to `jest.mock()` are hoisted to the top of the file, it's not possible to first define a variable and then use it in the factory. An exception is made for variables that start with the word 'mock'. It's up to you to guarantee that they will be initialized on time! For example, the following will throw an out-of-scope error due to the use of 'fake' instead of 'mock' in the variable declaration: +:::caution + +Since calls to `jest.mock()` are hoisted to the top of the file, Jest prevents access to out-of-scope variables. By default, you cannot first define a variable and then use it in the factory. Jest will disable this check for variables that start with the word `mock`. However, it is still up to you to guarantee that they will be initialized on time. Be aware of [Temporal Dead Zone](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/let#temporal_dead_zone_tdz). + +::: + +For example, the following will throw an out-of-scope error due to the use of `fake` instead of `mock` in the variable declaration. ```javascript // Note: this will fail @@ -153,6 +159,19 @@ jest.mock('./sound-player', () => { }); ``` +The following will throw a `ReferenceError` despite using `mock` in the variable declaration, as the `mockSoundPlayer` is not wrapped in an arrow function and thus accessed before initialization after hoisting. + +```javascript +import SoundPlayer from './sound-player'; +const mockSoundPlayer = jest.fn().mockImplementation(() => { + return {playSoundFile: mockPlaySoundFile}; +}); +// results in a ReferenceError +jest.mock('./sound-player', () => { + return mockSoundPlayer; +}); +``` + ### Replacing the mock using [`mockImplementation()`](MockFunctionAPI.md#mockfnmockimplementationfn) or [`mockImplementationOnce()`](MockFunctionAPI.md#mockfnmockimplementationoncefn) You can replace all of the above mocks in order to change the implementation, for a single test or all tests, by calling `mockImplementation()` on the existing mock. diff --git a/website/versioned_docs/version-27.4/Es6ClassMocks.md b/website/versioned_docs/version-27.4/Es6ClassMocks.md index 3907980f80b2..ad2fe2103018 100644 --- a/website/versioned_docs/version-27.4/Es6ClassMocks.md +++ b/website/versioned_docs/version-27.4/Es6ClassMocks.md @@ -140,7 +140,13 @@ jest.mock('./sound-player', () => { }); ``` -A limitation with the factory parameter is that, since calls to `jest.mock()` are hoisted to the top of the file, it's not possible to first define a variable and then use it in the factory. An exception is made for variables that start with the word 'mock'. It's up to you to guarantee that they will be initialized on time! For example, the following will throw an out-of-scope error due to the use of 'fake' instead of 'mock' in the variable declaration: +:::caution + +Since calls to `jest.mock()` are hoisted to the top of the file, Jest prevents access to out-of-scope variables. By default, you cannot first define a variable and then use it in the factory. Jest will disable this check for variables that start with the word `mock`. However, it is still up to you to guarantee that they will be initialized on time. Be aware of [Temporal Dead Zone](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/let#temporal_dead_zone_tdz). + +::: + +For example, the following will throw an out-of-scope error due to the use of `fake` instead of `mock` in the variable declaration. ```javascript // Note: this will fail @@ -153,6 +159,19 @@ jest.mock('./sound-player', () => { }); ``` +The following will throw a `ReferenceError` despite using `mock` in the variable declaration, as the `mockSoundPlayer` is not wrapped in an arrow function and thus accessed before initialization after hoisting. + +```javascript +import SoundPlayer from './sound-player'; +const mockSoundPlayer = jest.fn().mockImplementation(() => { + return {playSoundFile: mockPlaySoundFile}; +}); +// results in a ReferenceError +jest.mock('./sound-player', () => { + return mockSoundPlayer; +}); +``` + ### Replacing the mock using [`mockImplementation()`](MockFunctionAPI.md#mockfnmockimplementationfn) or [`mockImplementationOnce()`](MockFunctionAPI.md#mockfnmockimplementationoncefn) You can replace all of the above mocks in order to change the implementation, for a single test or all tests, by calling `mockImplementation()` on the existing mock. diff --git a/website/versioned_docs/version-27.5/Es6ClassMocks.md b/website/versioned_docs/version-27.5/Es6ClassMocks.md index 3907980f80b2..ad2fe2103018 100644 --- a/website/versioned_docs/version-27.5/Es6ClassMocks.md +++ b/website/versioned_docs/version-27.5/Es6ClassMocks.md @@ -140,7 +140,13 @@ jest.mock('./sound-player', () => { }); ``` -A limitation with the factory parameter is that, since calls to `jest.mock()` are hoisted to the top of the file, it's not possible to first define a variable and then use it in the factory. An exception is made for variables that start with the word 'mock'. It's up to you to guarantee that they will be initialized on time! For example, the following will throw an out-of-scope error due to the use of 'fake' instead of 'mock' in the variable declaration: +:::caution + +Since calls to `jest.mock()` are hoisted to the top of the file, Jest prevents access to out-of-scope variables. By default, you cannot first define a variable and then use it in the factory. Jest will disable this check for variables that start with the word `mock`. However, it is still up to you to guarantee that they will be initialized on time. Be aware of [Temporal Dead Zone](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/let#temporal_dead_zone_tdz). + +::: + +For example, the following will throw an out-of-scope error due to the use of `fake` instead of `mock` in the variable declaration. ```javascript // Note: this will fail @@ -153,6 +159,19 @@ jest.mock('./sound-player', () => { }); ``` +The following will throw a `ReferenceError` despite using `mock` in the variable declaration, as the `mockSoundPlayer` is not wrapped in an arrow function and thus accessed before initialization after hoisting. + +```javascript +import SoundPlayer from './sound-player'; +const mockSoundPlayer = jest.fn().mockImplementation(() => { + return {playSoundFile: mockPlaySoundFile}; +}); +// results in a ReferenceError +jest.mock('./sound-player', () => { + return mockSoundPlayer; +}); +``` + ### Replacing the mock using [`mockImplementation()`](MockFunctionAPI.md#mockfnmockimplementationfn) or [`mockImplementationOnce()`](MockFunctionAPI.md#mockfnmockimplementationoncefn) You can replace all of the above mocks in order to change the implementation, for a single test or all tests, by calling `mockImplementation()` on the existing mock.