diff --git a/website/versioned_docs/version-25.x/JestObjectAPI.md b/website/versioned_docs/version-25.x/JestObjectAPI.md index 99cf074366cb..0590a21cbd8d 100644 --- a/website/versioned_docs/version-25.x/JestObjectAPI.md +++ b/website/versioned_docs/version-25.x/JestObjectAPI.md @@ -19,9 +19,11 @@ import TOCInline from '@theme/TOCInline'; Disables automatic mocking in the module loader. -> See `automock` section of [configuration](Configuration.md#automock-boolean) for more information +:::info + +Automatic mocking should be enabled via [`automock`](Configuration.md#automock-boolean) configuration option for this method to have any effect. Also see documentation of the configuration option for more details. -After this method is called, all `require()`s will return the real versions of each module (rather than a mocked version). +::: Jest configuration: @@ -55,19 +57,25 @@ test('original implementation', () => { This is usually useful when you have a scenario where the number of dependencies you want to mock is far less than the number of dependencies that you don't. For example, if you're writing a test for a module that uses a large number of dependencies that can be reasonably classified as "implementation details" of the module, then you likely do not want to mock them. -Examples of dependencies that might be considered "implementation details" are things ranging from language built-ins (e.g. Array.prototype methods) to highly common utility methods (e.g. underscore/lodash, array utilities, etc) and entire libraries like React.js. +Examples of dependencies that might be considered "implementation details" are things ranging from language built-ins (e.g. `Array.prototype` methods) to highly common utility methods (e.g. `underscore`, `lodash`, array utilities, etc) and entire libraries like `React.js`. Returns the `jest` object for chaining. -_Note: this method was previously called `autoMockOff`. When using `babel-jest`, calls to `disableAutomock` will automatically be hoisted to the top of the code block. Use `autoMockOff` if you want to explicitly avoid this behavior._ +:::tip + +When using `babel-jest`, calls to `disableAutomock()` will automatically be hoisted to the top of the code block. Use `autoMockOff()` if you want to explicitly avoid this behavior. + +::: ### `jest.enableAutomock()` Enables automatic mocking in the module loader. -Returns the `jest` object for chaining. +:::info -> See `automock` section of [configuration](Configuration.md#automock-boolean) for more information +For more details on automatic mocking see documentation of [`automock`](Configuration.md#automock-boolean) configuration option. + +::: Example: @@ -92,7 +100,13 @@ test('original implementation', () => { }); ``` -_Note: this method was previously called `autoMockOn`. When using `babel-jest`, calls to `enableAutomock` will automatically be hoisted to the top of the code block. Use `autoMockOn` if you want to explicitly avoid this behavior._ +Returns the `jest` object for chaining. + +:::tip + +When using `babel-jest`, calls to `enableAutomock` will automatically be hoisted to the top of the code block. Use `autoMockOn` if you want to explicitly avoid this behavior. + +::: ### `jest.genMockFromModule(moduleName)` @@ -103,7 +117,7 @@ This is useful when you want to create a [manual mock](ManualMocks.md) that exte Example: ```js title="utils.js" -export default { +module.exports = { authorize: () => { return 'token'; }, @@ -112,11 +126,12 @@ export default { ``` ```js title="__tests__/genMockFromModule.test.js" -const utils = jest.genMockFromModule('../utils').default; +const utils = jest.genMockFromModule('../utils'); + utils.isAuthorized = jest.fn(secret => secret === 'not wizard'); test('implementation created by jest.genMockFromModule', () => { - expect(utils.authorize.mock).toBeTruthy(); + expect(jest.isMockFunction(utils.authorize)).toBe(true); expect(utils.isAuthorized('not wizard')).toBe(true); }); ``` @@ -176,7 +191,7 @@ module.exports = { ``` ```js title="__tests__/example.test.js" -const example = jest.genMockFromModule('./example'); +const example = jest.genMockFromModule('../example'); test('should run example code', () => { // creates a new mocked function with no formal arguments. @@ -272,7 +287,11 @@ jest.mock( ); ``` -> **Warning:** Importing a module in a setup file (as specified by `setupFilesAfterEnv`) will prevent mocking for the module in question, as well as all the modules that it imports. +:::caution + +Importing a module in a setup file (as specified by [`setupFilesAfterEnv`](Configuration.md#setupfilesafterenv-array)) will prevent mocking for the module in question, as well as all the modules that it imports. + +::: Modules that are mocked with `jest.mock` are mocked only for the file that calls `jest.mock`. Another file that imports the module will get the original implementation even if it runs after the test file that mocks the module. @@ -378,7 +397,11 @@ In these rare scenarios you can use this API to manually fill the slot in the mo Returns the `jest` object for chaining. -_Note It is recommended to use [`jest.mock()`](#jestmockmodulename-factory-options) instead. The `jest.mock` API's second argument is a module factory instead of the expected exported module object._ +:::info + +It is recommended to use [`jest.mock()`](#jestmockmodulename-factory-options) instead. The `jest.mock` API's second argument is a module factory instead of the expected exported module object. + +::: ### `jest.requireActual(moduleName)` @@ -455,7 +478,7 @@ const otherCopyOfMyModule = require('myModule'); ## Mock Functions -### `jest.fn(implementation)` +### `jest.fn(implementation?)` Returns a new, unused [mock function](MockFunctionAPI.md). Optionally takes a mock implementation. @@ -628,10 +651,6 @@ Exhausts all tasks queued by `setImmediate()`. ### `jest.advanceTimersByTime(msToRun)` -##### renamed in Jest **22.0.0+** - -Also under the alias: `.runTimersToTime()` - Executes only the macro task queue (i.e. all tasks queued by `setTimeout()` or `setInterval()` and `setImmediate()`). When this API is called, all timers are advanced by `msToRun` milliseconds. All pending "macro-tasks" that have been queued via `setTimeout()` or `setInterval()`, and would be executed within this time frame will be executed. Additionally, if those macro-tasks schedule new macro-tasks that would be executed within the same time frame, those will be executed until there are no more macro-tasks remaining in the queue, that should be run within `msToRun` milliseconds. @@ -688,16 +707,18 @@ This function is only available with the default [jest-circus](https://github.co ### `jest.setTimeout(timeout)` -Set the default timeout interval (in milliseconds) for all tests and before/after hooks in the test file. This only affects the test file from which this function is called. - -To set timeout intervals on different tests in the same file, use the [`timeout` option on each individual test](GlobalAPI.md#testname-fn-timeout). - -_Note: The default timeout interval is 5 seconds if this method is not called._ - -_Note: If you want to set the timeout for all test files, a good place to do this is in `setupFilesAfterEnv`._ +Set the default timeout interval (in milliseconds) for all tests and before/after hooks in the test file. This only affects the test file from which this function is called. The default timeout interval is 5 seconds if this method is not called. Example: ```js jest.setTimeout(1000); // 1 second ``` + +:::tip + +To set timeout intervals on different tests in the same file, use the [`timeout` option on each individual test](GlobalAPI.md#testname-fn-timeout). + +If you want to set the timeout for all test files, use [`testTimeout`](Configuration.md#testtimeout-number) configuration option. + +::: diff --git a/website/versioned_docs/version-26.x/JestObjectAPI.md b/website/versioned_docs/version-26.x/JestObjectAPI.md index 5ae88c7fafc7..bce3a5dddf6a 100644 --- a/website/versioned_docs/version-26.x/JestObjectAPI.md +++ b/website/versioned_docs/version-26.x/JestObjectAPI.md @@ -19,9 +19,11 @@ import TOCInline from '@theme/TOCInline'; Disables automatic mocking in the module loader. -> See `automock` section of [configuration](Configuration.md#automock-boolean) for more information +:::info + +Automatic mocking should be enabled via [`automock`](Configuration.md#automock-boolean) configuration option for this method to have any effect. Also see documentation of the configuration option for more details. -After this method is called, all `require()`s will return the real versions of each module (rather than a mocked version). +::: Jest configuration: @@ -55,19 +57,25 @@ test('original implementation', () => { This is usually useful when you have a scenario where the number of dependencies you want to mock is far less than the number of dependencies that you don't. For example, if you're writing a test for a module that uses a large number of dependencies that can be reasonably classified as "implementation details" of the module, then you likely do not want to mock them. -Examples of dependencies that might be considered "implementation details" are things ranging from language built-ins (e.g. Array.prototype methods) to highly common utility methods (e.g. underscore/lodash, array utilities, etc) and entire libraries like React.js. +Examples of dependencies that might be considered "implementation details" are things ranging from language built-ins (e.g. `Array.prototype` methods) to highly common utility methods (e.g. `underscore`, `lodash`, array utilities, etc) and entire libraries like `React.js`. Returns the `jest` object for chaining. -_Note: this method was previously called `autoMockOff`. When using `babel-jest`, calls to `disableAutomock` will automatically be hoisted to the top of the code block. Use `autoMockOff` if you want to explicitly avoid this behavior._ +:::tip + +When using `babel-jest`, calls to `disableAutomock()` will automatically be hoisted to the top of the code block. Use `autoMockOff()` if you want to explicitly avoid this behavior. + +::: ### `jest.enableAutomock()` Enables automatic mocking in the module loader. -Returns the `jest` object for chaining. +:::info -> See `automock` section of [configuration](Configuration.md#automock-boolean) for more information +For more details on automatic mocking see documentation of [`automock`](Configuration.md#automock-boolean) configuration option. + +::: Example: @@ -92,13 +100,21 @@ test('original implementation', () => { }); ``` -_Note: this method was previously called `autoMockOn`. When using `babel-jest`, calls to `enableAutomock` will automatically be hoisted to the top of the code block. Use `autoMockOn` if you want to explicitly avoid this behavior._ +Returns the `jest` object for chaining. + +:::tip + +When using `babel-jest`, calls to `enableAutomock` will automatically be hoisted to the top of the code block. Use `autoMockOn` if you want to explicitly avoid this behavior. + +::: ### `jest.createMockFromModule(moduleName)` -##### renamed in Jest **26.0.0+** +:::tip -Also under the alias: `.genMockFromModule(moduleName)` +Renamed from `.genMockFromModule(moduleName)` in Jest 26. + +::: Given the name of a module, use the automatic mocking system to generate a mocked version of the module for you. @@ -107,7 +123,7 @@ This is useful when you want to create a [manual mock](ManualMocks.md) that exte Example: ```js title="utils.js" -export default { +module.exports = { authorize: () => { return 'token'; }, @@ -116,11 +132,12 @@ export default { ``` ```js title="__tests__/createMockFromModule.test.js" -const utils = jest.createMockFromModule('../utils').default; +const utils = jest.createMockFromModule('../utils'); + utils.isAuthorized = jest.fn(secret => secret === 'not wizard'); test('implementation created by jest.createMockFromModule', () => { - expect(utils.authorize.mock).toBeTruthy(); + expect(jest.isMockFunction(utils.authorize)).toBe(true); expect(utils.isAuthorized('not wizard')).toBe(true); }); ``` @@ -180,7 +197,7 @@ module.exports = { ``` ```js title="__tests__/example.test.js" -const example = jest.createMockFromModule('./example'); +const example = jest.createMockFromModule('../example'); test('should run example code', () => { // creates a new mocked function with no formal arguments. @@ -276,7 +293,11 @@ jest.mock( ); ``` -> **Warning:** Importing a module in a setup file (as specified by `setupFilesAfterEnv`) will prevent mocking for the module in question, as well as all the modules that it imports. +:::caution + +Importing a module in a setup file (as specified by [`setupFilesAfterEnv`](Configuration.md#setupfilesafterenv-array)) will prevent mocking for the module in question, as well as all the modules that it imports. + +::: Modules that are mocked with `jest.mock` are mocked only for the file that calls `jest.mock`. Another file that imports the module will get the original implementation even if it runs after the test file that mocks the module. @@ -382,7 +403,11 @@ In these rare scenarios you can use this API to manually fill the slot in the mo Returns the `jest` object for chaining. -_Note It is recommended to use [`jest.mock()`](#jestmockmodulename-factory-options) instead. The `jest.mock` API's second argument is a module factory instead of the expected exported module object._ +:::info + +It is recommended to use [`jest.mock()`](#jestmockmodulename-factory-options) instead. The `jest.mock` API's second argument is a module factory instead of the expected exported module object. + +::: ### `jest.requireActual(moduleName)` @@ -459,7 +484,7 @@ const otherCopyOfMyModule = require('myModule'); ## Mock Functions -### `jest.fn(implementation)` +### `jest.fn(implementation?)` Returns a new, unused [mock function](MockFunctionAPI.md). Optionally takes a mock implementation. @@ -632,13 +657,13 @@ This is often useful for synchronously executing setTimeouts during a test in or Exhausts all tasks queued by `setImmediate()`. -> Note: This function is not available when using modern fake timers implementation +:::info -### `jest.advanceTimersByTime(msToRun)` +This function is not available when using modern fake timers implementation. -##### renamed in Jest **22.0.0+** +::: -Also under the alias: `.runTimersToTime()` +### `jest.advanceTimersByTime(msToRun)` Executes only the macro task queue (i.e. all tasks queued by `setTimeout()` or `setInterval()` and `setImmediate()`). @@ -670,13 +695,21 @@ Returns the number of fake timers still left to run. Set the current system time used by fake timers. Simulates a user changing the system clock while your program is running. It affects the current time but it does not in itself cause e.g. timers to fire; they will fire exactly as they would have done without the call to `jest.setSystemTime()`. -> Note: This function is only available when using modern fake timers implementation +:::info + +This function is only available when using modern fake timers implementation. + +::: ### `jest.getRealSystemTime()` When mocking time, `Date.now()` will also be mocked. If you for some reason need access to the real current time, you can invoke this function. -> Note: This function is only available when using modern fake timers implementation +:::info + +This function is only available when using modern fake timers implementation. + +::: ## Misc @@ -708,16 +741,18 @@ This function is only available with the default [jest-circus](https://github.co ### `jest.setTimeout(timeout)` -Set the default timeout interval (in milliseconds) for all tests and before/after hooks in the test file. This only affects the test file from which this function is called. - -To set timeout intervals on different tests in the same file, use the [`timeout` option on each individual test](GlobalAPI.md#testname-fn-timeout). - -_Note: The default timeout interval is 5 seconds if this method is not called._ - -_Note: If you want to set the timeout for all test files, a good place to do this is in `setupFilesAfterEnv`._ +Set the default timeout interval (in milliseconds) for all tests and before/after hooks in the test file. This only affects the test file from which this function is called. The default timeout interval is 5 seconds if this method is not called. Example: ```js jest.setTimeout(1000); // 1 second ``` + +:::tip + +To set timeout intervals on different tests in the same file, use the [`timeout` option on each individual test](GlobalAPI.md#testname-fn-timeout). + +If you want to set the timeout for all test files, use [`testTimeout`](Configuration.md#testtimeout-number) configuration option. + +::: diff --git a/website/versioned_docs/version-27.x/JestObjectAPI.md b/website/versioned_docs/version-27.x/JestObjectAPI.md index b38d312e9981..25a665116f18 100644 --- a/website/versioned_docs/version-27.x/JestObjectAPI.md +++ b/website/versioned_docs/version-27.x/JestObjectAPI.md @@ -19,9 +19,11 @@ import TOCInline from '@theme/TOCInline'; Disables automatic mocking in the module loader. -> See `automock` section of [configuration](Configuration.md#automock-boolean) for more information +:::info + +Automatic mocking should be enabled via [`automock`](Configuration.md#automock-boolean) configuration option for this method to have any effect. Also see documentation of the configuration option for more details. -After this method is called, all `require()`s will return the real versions of each module (rather than a mocked version). +::: Jest configuration: @@ -55,19 +57,25 @@ test('original implementation', () => { This is usually useful when you have a scenario where the number of dependencies you want to mock is far less than the number of dependencies that you don't. For example, if you're writing a test for a module that uses a large number of dependencies that can be reasonably classified as "implementation details" of the module, then you likely do not want to mock them. -Examples of dependencies that might be considered "implementation details" are things ranging from language built-ins (e.g. Array.prototype methods) to highly common utility methods (e.g. underscore/lodash, array utilities, etc) and entire libraries like React.js. +Examples of dependencies that might be considered "implementation details" are things ranging from language built-ins (e.g. `Array.prototype` methods) to highly common utility methods (e.g. `underscore`, `lodash`, array utilities, etc) and entire libraries like `React.js`. Returns the `jest` object for chaining. -_Note: this method was previously called `autoMockOff`. When using `babel-jest`, calls to `disableAutomock` will automatically be hoisted to the top of the code block. Use `autoMockOff` if you want to explicitly avoid this behavior._ +:::tip + +When using `babel-jest`, calls to `disableAutomock()` will automatically be hoisted to the top of the code block. Use `autoMockOff()` if you want to explicitly avoid this behavior. + +::: ### `jest.enableAutomock()` Enables automatic mocking in the module loader. -Returns the `jest` object for chaining. +:::info + +For more details on automatic mocking see documentation of [`automock`](Configuration.md#automock-boolean) configuration option. -> See `automock` section of [configuration](Configuration.md#automock-boolean) for more information +::: Example: @@ -92,13 +100,21 @@ test('original implementation', () => { }); ``` -_Note: this method was previously called `autoMockOn`. When using `babel-jest`, calls to `enableAutomock` will automatically be hoisted to the top of the code block. Use `autoMockOn` if you want to explicitly avoid this behavior._ +Returns the `jest` object for chaining. + +:::tip + +When using `babel-jest`, calls to `enableAutomock` will automatically be hoisted to the top of the code block. Use `autoMockOn` if you want to explicitly avoid this behavior. + +::: ### `jest.createMockFromModule(moduleName)` -##### renamed in Jest **26.0.0+** +:::tip -Also under the alias: `.genMockFromModule(moduleName)` +Renamed from `.genMockFromModule(moduleName)` in Jest 26. + +::: Given the name of a module, use the automatic mocking system to generate a mocked version of the module for you. @@ -107,7 +123,7 @@ This is useful when you want to create a [manual mock](ManualMocks.md) that exte Example: ```js title="utils.js" -export default { +module.exports = { authorize: () => { return 'token'; }, @@ -116,11 +132,12 @@ export default { ``` ```js title="__tests__/createMockFromModule.test.js" -const utils = jest.createMockFromModule('../utils').default; +const utils = jest.createMockFromModule('../utils'); + utils.isAuthorized = jest.fn(secret => secret === 'not wizard'); test('implementation created by jest.createMockFromModule', () => { - expect(utils.authorize.mock).toBeTruthy(); + expect(jest.isMockFunction(utils.authorize)).toBe(true); expect(utils.isAuthorized('not wizard')).toBe(true); }); ``` @@ -180,7 +197,7 @@ module.exports = { ``` ```js title="__tests__/example.test.js" -const example = jest.createMockFromModule('./example'); +const example = jest.createMockFromModule('../example'); test('should run example code', () => { // creates a new mocked function with no formal arguments. @@ -276,7 +293,11 @@ jest.mock( ); ``` -> **Warning:** Importing a module in a setup file (as specified by `setupFilesAfterEnv`) will prevent mocking for the module in question, as well as all the modules that it imports. +:::caution + +Importing a module in a setup file (as specified by [`setupFilesAfterEnv`](Configuration.md#setupfilesafterenv-array)) will prevent mocking for the module in question, as well as all the modules that it imports. + +::: Modules that are mocked with `jest.mock` are mocked only for the file that calls `jest.mock`. Another file that imports the module will get the original implementation even if it runs after the test file that mocks the module. @@ -382,7 +403,11 @@ In these rare scenarios you can use this API to manually fill the slot in the mo Returns the `jest` object for chaining. -_Note It is recommended to use [`jest.mock()`](#jestmockmodulename-factory-options) instead. The `jest.mock` API's second argument is a module factory instead of the expected exported module object._ +:::info + +It is recommended to use [`jest.mock()`](#jestmockmodulename-factory-options) instead. The `jest.mock` API's second argument is a module factory instead of the expected exported module object. + +::: ### `jest.requireActual(moduleName)` @@ -459,7 +484,7 @@ const otherCopyOfMyModule = require('myModule'); ## Mock Functions -### `jest.fn(implementation)` +### `jest.fn(implementation?)` Returns a new, unused [mock function](MockFunctionAPI.md). Optionally takes a mock implementation. @@ -602,12 +627,15 @@ Restores all mocks back to their original value. Equivalent to calling [`.mockRe The `mocked` test helper provides typings on your mocked modules and even their deep methods, based on the typing of its source. It makes use of the latest TypeScript feature, so you even have argument types completion in the IDE (as opposed to `jest.MockInstance`). -_Note: while it needs to be a function so that input type is changed, the helper itself does nothing else than returning the given input value._ +:::note + +While it needs to be a function so that input type is changed, the helper itself does nothing else than returning the given input value. + +::: Example: -```ts -// foo.ts +```ts title="foo.ts" export const foo = { a: { b: { @@ -620,8 +648,7 @@ export const foo = { }; ``` -```ts -// foo.spec.ts +```ts title="foo.test.ts" import {foo} from './foo'; jest.mock('./foo'); @@ -676,7 +703,11 @@ This is often useful for synchronously executing setTimeouts during a test in or Exhausts all tasks queued by `setImmediate()`. -> Note: This function is not available when using modern fake timers implementation +:::info + +This function is not available when using modern fake timers implementation. + +::: ### `jest.advanceTimersByTime(msToRun)` @@ -710,13 +741,21 @@ Returns the number of fake timers still left to run. Set the current system time used by fake timers. Simulates a user changing the system clock while your program is running. It affects the current time but it does not in itself cause e.g. timers to fire; they will fire exactly as they would have done without the call to `jest.setSystemTime()`. -> Note: This function is only available when using modern fake timers implementation +:::info + +This function is only available when using modern fake timers implementation. + +::: ### `jest.getRealSystemTime()` When mocking time, `Date.now()` will also be mocked. If you for some reason need access to the real current time, you can invoke this function. -> Note: This function is only available when using modern fake timers implementation +:::info + +This function is only available when using modern fake timers implementation. + +::: ## Misc @@ -748,16 +787,18 @@ This function is only available with the default [jest-circus](https://github.co ### `jest.setTimeout(timeout)` -Set the default timeout interval (in milliseconds) for all tests and before/after hooks in the test file. This only affects the test file from which this function is called. - -To set timeout intervals on different tests in the same file, use the [`timeout` option on each individual test](GlobalAPI.md#testname-fn-timeout). - -_Note: The default timeout interval is 5 seconds if this method is not called._ - -_Note: If you want to set the timeout for all test files, a good place to do this is in `setupFilesAfterEnv`._ +Set the default timeout interval (in milliseconds) for all tests and before/after hooks in the test file. This only affects the test file from which this function is called. The default timeout interval is 5 seconds if this method is not called. Example: ```js jest.setTimeout(1000); // 1 second ``` + +:::tip + +To set timeout intervals on different tests in the same file, use the [`timeout` option on each individual test](GlobalAPI.md#testname-fn-timeout). + +If you want to set the timeout for all test files, use [`testTimeout`](Configuration.md#testtimeout-number) configuration option. + +::: diff --git a/website/versioned_docs/version-28.x/JestObjectAPI.md b/website/versioned_docs/version-28.x/JestObjectAPI.md index 36df9dfaa6dc..2d40fe820a86 100644 --- a/website/versioned_docs/version-28.x/JestObjectAPI.md +++ b/website/versioned_docs/version-28.x/JestObjectAPI.md @@ -19,7 +19,11 @@ import TOCInline from '@theme/TOCInline'; Disables automatic mocking in the module loader. -> See `automock` section of [configuration](Configuration.md#automock-boolean) for more information +:::info + +Automatic mocking should be enabled via [`automock`](Configuration.md#automock-boolean) configuration option for this method to have any effect. Also see documentation of the configuration option for more details. + +::: After this method is called, all `require()`s will return the real versions of each module (rather than a mocked version). @@ -55,19 +59,25 @@ test('original implementation', () => { This is usually useful when you have a scenario where the number of dependencies you want to mock is far less than the number of dependencies that you don't. For example, if you're writing a test for a module that uses a large number of dependencies that can be reasonably classified as "implementation details" of the module, then you likely do not want to mock them. -Examples of dependencies that might be considered "implementation details" are things ranging from language built-ins (e.g. Array.prototype methods) to highly common utility methods (e.g. underscore/lodash, array utilities, etc) and entire libraries like React.js. +Examples of dependencies that might be considered "implementation details" are things ranging from language built-ins (e.g. `Array.prototype` methods) to highly common utility methods (e.g. `underscore`, `lodash`, array utilities, etc) and entire libraries like `React.js`. Returns the `jest` object for chaining. -_Note: this method was previously called `autoMockOff`. When using `babel-jest`, calls to `disableAutomock` will automatically be hoisted to the top of the code block. Use `autoMockOff` if you want to explicitly avoid this behavior._ +:::tip + +When using `babel-jest`, calls to `disableAutomock()` will automatically be hoisted to the top of the code block. Use `autoMockOff()` if you want to explicitly avoid this behavior. + +::: ### `jest.enableAutomock()` Enables automatic mocking in the module loader. -Returns the `jest` object for chaining. +:::info + +For more details on automatic mocking see documentation of [`automock`](Configuration.md#automock-boolean) configuration option. -> See `automock` section of [configuration](Configuration.md#automock-boolean) for more information +::: Example: @@ -92,13 +102,15 @@ test('original implementation', () => { }); ``` -_Note: this method was previously called `autoMockOn`. When using `babel-jest`, calls to `enableAutomock` will automatically be hoisted to the top of the code block. Use `autoMockOn` if you want to explicitly avoid this behavior._ +Returns the `jest` object for chaining. -### `jest.createMockFromModule(moduleName)` +:::tip -##### renamed in Jest **26.0.0+** +When using `babel-jest`, calls to `enableAutomock` will automatically be hoisted to the top of the code block. Use `autoMockOn` if you want to explicitly avoid this behavior. -Also under the alias: `.genMockFromModule(moduleName)` +::: + +### `jest.createMockFromModule(moduleName)` Given the name of a module, use the automatic mocking system to generate a mocked version of the module for you. @@ -107,7 +119,7 @@ This is useful when you want to create a [manual mock](ManualMocks.md) that exte Example: ```js title="utils.js" -export default { +module.exports = { authorize: () => { return 'token'; }, @@ -116,11 +128,11 @@ export default { ``` ```js title="__tests__/createMockFromModule.test.js" -const utils = jest.createMockFromModule('../utils').default; +const utils = jest.createMockFromModule('../utils'); utils.isAuthorized = jest.fn(secret => secret === 'not wizard'); test('implementation created by jest.createMockFromModule', () => { - expect(utils.authorize.mock).toBeTruthy(); + expect(jest.isMockFunction(utils.authorize)).toBe(true); expect(utils.isAuthorized('not wizard')).toBe(true); }); ``` @@ -180,7 +192,7 @@ module.exports = { ``` ```js title="__tests__/example.test.js" -const example = jest.createMockFromModule('./example'); +const example = jest.createMockFromModule('../example'); test('should run example code', () => { // creates a new mocked function with no formal arguments. @@ -276,7 +288,11 @@ jest.mock( ); ``` -> **Warning:** Importing a module in a setup file (as specified by `setupFilesAfterEnv`) will prevent mocking for the module in question, as well as all the modules that it imports. +:::caution + +Importing a module in a setup file (as specified by [`setupFilesAfterEnv`](Configuration.md#setupfilesafterenv-array)) will prevent mocking for the module in question, as well as all the modules that it imports. + +::: Modules that are mocked with `jest.mock` are mocked only for the file that calls `jest.mock`. Another file that imports the module will get the original implementation even if it runs after the test file that mocks the module. @@ -382,7 +398,11 @@ In these rare scenarios you can use this API to manually fill the slot in the mo Returns the `jest` object for chaining. -_Note It is recommended to use [`jest.mock()`](#jestmockmodulename-factory-options) instead. The `jest.mock` API's second argument is a module factory instead of the expected exported module object._ +:::info + +It is recommended to use [`jest.mock()`](#jestmockmodulename-factory-options) instead. The `jest.mock` API's second argument is a module factory instead of the expected exported module object. + +::: ### `jest.requireActual(moduleName)` @@ -473,7 +493,7 @@ const returnsTrue = jest.fn(() => true); console.log(returnsTrue()); // true; ``` -:::note +:::tip See the [Mock Functions](MockFunctionAPI.md#jestfnimplementation) page for details on TypeScript usage. @@ -608,12 +628,15 @@ Restores all mocks back to their original value. Equivalent to calling [`.mockRe The `mocked` test helper provides typings on your mocked modules and even their deep methods, based on the typing of its source. It makes use of the latest TypeScript feature, so you even have argument types completion in the IDE (as opposed to `jest.MockInstance`). -_Note: while it needs to be a function so that input type is changed, the helper itself does nothing else than returning the given input value._ +:::note + +While it needs to be a function so that input type is changed, the helper itself does nothing else than returning the given input value. + +::: Example: -```ts -// foo.ts +```ts title="foo.ts" export const foo = { a: { b: { @@ -626,8 +649,7 @@ export const foo = { }; ``` -```ts -// foo.spec.ts +```ts title="foo.test.ts" import {foo} from './foo'; jest.mock('./foo'); @@ -875,16 +897,18 @@ This function is only available with the default [jest-circus](https://github.co ### `jest.setTimeout(timeout)` -Set the default timeout interval (in milliseconds) for all tests and before/after hooks in the test file. This only affects the test file from which this function is called. - -To set timeout intervals on different tests in the same file, use the [`timeout` option on each individual test](GlobalAPI.md#testname-fn-timeout). - -_Note: The default timeout interval is 5 seconds if this method is not called._ - -_Note: If you want to set the timeout for all test files, a good place to do this is in `setupFilesAfterEnv`._ +Set the default timeout interval (in milliseconds) for all tests and before/after hooks in the test file. This only affects the test file from which this function is called. The default timeout interval is 5 seconds if this method is not called. Example: ```js jest.setTimeout(1000); // 1 second ``` + +:::tip + +To set timeout intervals on different tests in the same file, use the [`timeout` option on each individual test](GlobalAPI.md#testname-fn-timeout). + +If you want to set the timeout for all test files, use [`testTimeout`](Configuration.md#testtimeout-number) configuration option. + +:::