Skip to content

Commit

Permalink
docs: use admonitions in Jest object page (#13277)
Browse files Browse the repository at this point in the history
  • Loading branch information
mrazauskas committed Sep 17, 2022
1 parent 3e359a2 commit f988721
Showing 1 changed file with 57 additions and 22 deletions.
79 changes: 57 additions & 22 deletions docs/JestObjectAPI.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,19 +23,32 @@ 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

After this method is called, all `require()`s will return the real versions of each module (rather than a mocked version).
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.

Jest configuration:
```js tab
/** @type {import('jest').Config} */
const config = {
automock: true,
};

```json
{
"automock": true
}
module.exports = config;
```

Example:
```ts tab
import type {Config} from 'jest';

const config: Config = {
automock: true,
};

export default config;
```

:::

After `disableAutomock()` is called, all `require()`s will return the real versions of each module (rather than a mocked version).

```js title="utils.js"
export default {
Expand All @@ -59,19 +72,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/lo-dash, 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`, `lo-dash`, 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:

Expand All @@ -96,7 +115,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.createMockFromModule(moduleName)`

Expand Down Expand Up @@ -307,7 +332,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.

Expand Down Expand Up @@ -444,7 +473,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)`

Expand Down Expand Up @@ -877,20 +910,22 @@ This function is not available when using legacy fake timers implementation.

### `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.

:::

### `jest.retryTimes(numRetries, options)`

Runs failed tests n-times until they pass or until the max number of retries is exhausted. `options` are optional. This only works with the default [jest-circus](https://github.com/facebook/jest/tree/main/packages/jest-circus) runner! This must live at the top-level of a test file or in a describe block. Retries _will not_ work if `jest.retryTimes()` is called in a `beforeEach` or a `test` block.
Expand Down

0 comments on commit f988721

Please sign in to comment.