fix(cli, config, docs): improve mock related cli messages, config template entries and documentation (#12047)

Author: mrazauskas

docs/CLI.md

@@ -138,6 +138,10 @@ When this option is provided, Jest will assume it is running in a CI environment
 
 Deletes the Jest cache directory and then exits without running tests. Will delete `cacheDirectory` if the option is passed, or Jest's default cache directory. The default cache directory can be found by calling `jest --showConfig`. _Note: clearing the cache will reduce performance._
 
+### `--clearMocks`
+
+Automatically clear mock calls, instances and results before every test. Equivalent to calling [`jest.clearAllMocks()`](JestObjectAPI.md#jestclearallmocks) before each test. This does not remove any mock implementation that may have been provided.
+
 ### `--collectCoverageFrom=<glob>`
 
 A glob pattern relative to `rootDir` matching the files that coverage info needs to be collected from.
@@ -272,6 +276,14 @@ Run tests with specified reporters. [Reporter options](configuration#reporters-a
 
 `jest --reporters="default" --reporters="jest-junit"`
 
+### `--resetMocks`
+
+Automatically reset mock state before every test. Equivalent to calling [`jest.resetAllMocks()`](JestObjectAPI.md#jestresetallmocks) before each test. This will lead to any mocks having their fake implementations removed but does not restore their initial implementation.
+
+### `--restoreMocks`
+
+Automatically restore mock state and implementation before every test. Equivalent to calling [`jest.restoreAllMocks()`](JestObjectAPI.md#jestrestoreallmocks) before each test. This will lead to any mocks having their fake implementations removed and restores their initial implementation.
+
 ### `--roots`
 
 A list of paths to directories that Jest should use to search for files in.

docs/Configuration.md

@@ -146,7 +146,7 @@ Jest attempts to scan your dependency tree once (up-front) and cache it in order
 
 Default: `false`
 
-Automatically clear mock calls and instances before every test. Equivalent to calling `jest.clearAllMocks()` before each test. This does not remove any mock implementation that may have been provided.
+Automatically clear mock calls, instances and results before every test. Equivalent to calling [`jest.clearAllMocks()`](JestObjectAPI.md#jestclearallmocks) before each test. This does not remove any mock implementation that may have been provided.
 
 ### `collectCoverage` \[boolean]
 
@@ -764,7 +764,7 @@ For the full list of methods and argument types see `Reporter` interface in [pac
 
 Default: `false`
 
-Automatically reset mock state before every test. Equivalent to calling `jest.resetAllMocks()` before each test. This will lead to any mocks having their fake implementations removed but does not restore their initial implementation.
+Automatically reset mock state before every test. Equivalent to calling [`jest.resetAllMocks()`](JestObjectAPI.md#jestresetallmocks) before each test. This will lead to any mocks having their fake implementations removed but does not restore their initial implementation.
 
 ### `resetModules` \[boolean]
 
@@ -849,7 +849,7 @@ While Jest does not support [package `exports`](https://nodejs.org/api/packages.
 
 Default: `false`
 
-Automatically restore mock state before every test. Equivalent to calling `jest.restoreAllMocks()` before each test. This will lead to any mocks having their fake implementations removed and restores their initial implementation.
+Automatically restore mock state and implementation before every test. Equivalent to calling [`jest.restoreAllMocks()`](JestObjectAPI.md#jestrestoreallmocks) before each test. This will lead to any mocks having their fake implementations removed and restores their initial implementation.
 
 ### `rootDir` \[string]
 

docs/MockFunctionAPI.md

@@ -81,16 +81,20 @@ mockFn.mock.instances[1] === b; // true
 
 ### `mockFn.mockClear()`
 
-Resets all information stored in the [`mockFn.mock.calls`](#mockfnmockcalls), [`mockFn.mock.instances`](#mockfnmockinstances) and [`mockFn.mock.results`](#mockfnmockresults) arrays. Often this is useful when you want to clean up a mocks usage data between two assertions.
+Clears all information stored in the [`mockFn.mock.calls`](#mockfnmockcalls), [`mockFn.mock.instances`](#mockfnmockinstances) and [`mockFn.mock.results`](#mockfnmockresults) arrays. Often this is useful when you want to clean up a mocks usage data between two assertions.
 
-Beware that `mockClear` will replace `mockFn.mock`, not just these three properties! You should, therefore, avoid assigning `mockFn.mock` to other variables, temporary or not, to make sure you don't access stale data. The [`clearMocks`](configuration#clearmocks-boolean) configuration option is available to clear mocks automatically between tests.
+Beware that `mockClear` will replace `mockFn.mock`, not just these three properties! You should, therefore, avoid assigning `mockFn.mock` to other variables, temporary or not, to make sure you don't access stale data.
+
+The [`clearMocks`](configuration#clearmocks-boolean) configuration option is available to clear mocks automatically before each tests.
 
 ### `mockFn.mockReset()`
 
 Does everything that [`mockFn.mockClear()`](#mockfnmockclear) does, and also removes any mocked return values or implementations.
 
 This is useful when you want to completely reset a _mock_ back to its initial state. (Note that resetting a _spy_ will result in a function with no return value).
 
+The [`mockReset`](configuration#resetmocks-boolean) configuration option is available to reset mocks automatically before each test.
+
 ### `mockFn.mockRestore()`
 
 Does everything that [`mockFn.mockReset()`](#mockfnmockreset) does, and also restores the original (non-mocked) implementation.
@@ -99,7 +103,7 @@ This is useful when you want to mock functions in certain test cases and restore
 
 Beware that `mockFn.mockRestore` only works when the mock was created with `jest.spyOn`. Thus you have to take care of restoration yourself when manually assigning `jest.fn()`.
 
-The [`restoreMocks`](configuration#restoremocks-boolean) configuration option is available to restore mocks automatically between tests.
+The [`restoreMocks`](configuration#restoremocks-boolean) configuration option is available to restore mocks automatically before each test.
 
 ### `mockFn.mockImplementation(fn)`
 

packages/jest-cli/src/cli/args.ts

@@ -148,8 +148,8 @@ export const options = {
   },
   clearMocks: {
     description:
-      'Automatically clear mock calls and instances between every ' +
-      'test. Equivalent to calling jest.clearAllMocks() between each test.',
+      'Automatically clear mock calls, instances and results before every test. ' +
+      'Equivalent to calling jest.clearAllMocks() before each test.',
     type: 'boolean',
   },
   collectCoverage: {
@@ -440,8 +440,8 @@ export const options = {
   },
   resetMocks: {
     description:
-      'Automatically reset mock state between every test. ' +
-      'Equivalent to calling jest.resetAllMocks() between each test.',
+      'Automatically reset mock state before every test. ' +
+      'Equivalent to calling jest.resetAllMocks() before each test.',
     type: 'boolean',
   },
   resetModules: {
@@ -456,8 +456,8 @@ export const options = {
   },
   restoreMocks: {
     description:
-      'Automatically restore mock state and implementation between every test. ' +
-      'Equivalent to calling jest.restoreAllMocks() between each test.',
+      'Automatically restore mock state and implementation before every test. ' +
+      'Equivalent to calling jest.restoreAllMocks() before each test.',
     type: 'boolean',
   },
   rootDir: {

packages/jest-cli/src/init/__tests__/__snapshots__/init.test.js.snap

@@ -108,7 +108,7 @@ Array [
   },
   Object {
     "initial": false,
-    "message": "Automatically clear mock calls and instances between every test?",
+    "message": "Automatically clear mock calls, instances and results before every test?",
     "name": "clearMocks",
     "type": "confirm",
   },
@@ -131,7 +131,7 @@ module.exports = {
   // The directory where Jest should store its cached dependency information
   // cacheDirectory: \\"/tmp/jest\\",
 
-  // Automatically clear mock calls and instances between every test
+  // Automatically clear mock calls, instances and results before every test
   // clearMocks: false,
 
   // Indicates whether the coverage information should be collected while executing the test
@@ -219,7 +219,7 @@ module.exports = {
   // Use this configuration option to add custom reporters to Jest
   // reporters: undefined,
 
-  // Automatically reset mock state between every test
+  // Automatically reset mock state before every test
   // resetMocks: false,
 
   // Reset the module registry before running each individual test
@@ -228,7 +228,7 @@ module.exports = {
   // A path to a custom resolver
   // resolver: undefined,
 
-  // Automatically restore mock state between every test
+  // Automatically restore mock state and implementation before every test
   // restoreMocks: false,
 
   // The root directory that Jest should scan for tests and modules within

packages/jest-cli/src/init/questions.ts

@@ -42,7 +42,8 @@ const defaultQuestions: Array<PromptObject> = [
   },
   {
     initial: false,
-    message: 'Automatically clear mock calls and instances between every test?',
+    message:
+      'Automatically clear mock calls, instances and results before every test?',
     name: 'clearMocks',
     type: 'confirm',
   },

packages/jest-config/src/Descriptions.ts

@@ -12,7 +12,8 @@ const descriptions: {[key in keyof Config.InitialOptions]: string} = {
   bail: 'Stop running tests after `n` failures',
   cacheDirectory:
     'The directory where Jest should store its cached dependency information',
-  clearMocks: 'Automatically clear mock calls and instances between every test',
+  clearMocks:
+    'Automatically clear mock calls, instances and results before every test',
   collectCoverage:
     'Indicates whether the coverage information should be collected while executing the test',
   collectCoverageFrom:
@@ -53,10 +54,11 @@ const descriptions: {[key in keyof Config.InitialOptions]: string} = {
   preset: "A preset that is used as a base for Jest's configuration",
   projects: 'Run tests from one or more projects',
   reporters: 'Use this configuration option to add custom reporters to Jest',
-  resetMocks: 'Automatically reset mock state between every test',
+  resetMocks: 'Automatically reset mock state before every test',
   resetModules: 'Reset the module registry before running each individual test',
   resolver: 'A path to a custom resolver',
-  restoreMocks: 'Automatically restore mock state between every test',
+  restoreMocks:
+    'Automatically restore mock state and implementation before every test',
   rootDir:
     'The root directory that Jest should scan for tests and modules within',
   roots:

website/versioned_docs/version-25.x/CLI.md

@@ -138,6 +138,10 @@ When this option is provided, Jest will assume it is running in a CI environment
 
 Deletes the Jest cache directory and then exits without running tests. Will delete `cacheDirectory` if the option is passed, or Jest's default cache directory. The default cache directory can be found by calling `jest --showConfig`. _Note: clearing the cache will reduce performance._
 
+### `--clearMocks`
+
+Automatically clear mock calls, instances and results before every test. Equivalent to calling [`jest.clearAllMocks()`](JestObjectAPI.md#jestclearallmocks) before each test. This does not remove any mock implementation that may have been provided.
+
 ### `--collectCoverageFrom=<glob>`
 
 A glob pattern relative to `rootDir` matching the files that coverage info needs to be collected from.
@@ -260,6 +264,14 @@ Run tests with specified reporters. [Reporter options](configuration#reporters-a
 
 `jest --reporters="default" --reporters="jest-junit"`
 
+### `--resetMocks`
+
+Automatically reset mock state before every test. Equivalent to calling [`jest.resetAllMocks()`](JestObjectAPI.md#jestresetallmocks) before each test. This will lead to any mocks having their fake implementations removed but does not restore their initial implementation.
+
+### `--restoreMocks`
+
+Automatically restore mock state and implementation before every test. Equivalent to calling [`jest.restoreAllMocks()`](JestObjectAPI.md#jestrestoreallmocks) before each test. This will lead to any mocks having their fake implementations removed and restores their initial implementation.
+
 ### `--roots`
 
 A list of paths to directories that Jest should use to search for files in.

website/versioned_docs/version-25.x/Configuration.md

@@ -125,7 +125,7 @@ Jest attempts to scan your dependency tree once (up-front) and cache it in order
 
 Default: `false`
 
-Automatically clear mock calls and instances before every test. Equivalent to calling `jest.clearAllMocks()` before each test. This does not remove any mock implementation that may have been provided.
+Automatically clear mock calls, instances and results before every test. Equivalent to calling [`jest.clearAllMocks()`](JestObjectAPI.md#jestclearallmocks) before each test. This does not remove any mock implementation that may have been provided.
 
 ### `collectCoverage` \[boolean]
 
@@ -702,7 +702,7 @@ For the full list of methods and argument types see `Reporter` interface in [pac
 
 Default: `false`
 
-Automatically reset mock state before every test. Equivalent to calling `jest.resetAllMocks()` before each test. This will lead to any mocks having their fake implementations removed but does not restore their initial implementation.
+Automatically reset mock state before every test. Equivalent to calling [`jest.resetAllMocks()`](JestObjectAPI.md#jestresetallmocks) before each test. This will lead to any mocks having their fake implementations removed but does not restore their initial implementation.
 
 ### `resetModules` \[boolean]
 
@@ -736,7 +736,7 @@ Note: the defaultResolver passed as an option is the Jest default resolver which
 
 Default: `false`
 
-Automatically restore mock state before every test. Equivalent to calling `jest.restoreAllMocks()` before each test. This will lead to any mocks having their fake implementations removed and restores their initial implementation.
+Automatically restore mock state and implementation before every test. Equivalent to calling [`jest.restoreAllMocks()`](JestObjectAPI.md#jestrestoreallmocks) before each test. This will lead to any mocks having their fake implementations removed and restores their initial implementation.
 
 ### `rootDir` \[string]
 

website/versioned_docs/version-25.x/MockFunctionAPI.md

@@ -81,16 +81,20 @@ mockFn.mock.instances[1] === b; // true
 
 ### `mockFn.mockClear()`
 
-Resets all information stored in the [`mockFn.mock.calls`](#mockfnmockcalls), [`mockFn.mock.instances`](#mockfnmockinstances) and [`mockFn.mock.results`](#mockfnmockresults) arrays. Often this is useful when you want to clean up a mocks usage data between two assertions.
+Clears all information stored in the [`mockFn.mock.calls`](#mockfnmockcalls), [`mockFn.mock.instances`](#mockfnmockinstances) and [`mockFn.mock.results`](#mockfnmockresults) arrays. Often this is useful when you want to clean up a mocks usage data between two assertions.
 
-Beware that `mockClear` will replace `mockFn.mock`, not just these three properties! You should, therefore, avoid assigning `mockFn.mock` to other variables, temporary or not, to make sure you don't access stale data. The [`clearMocks`](configuration#clearmocks-boolean) configuration option is available to clear mocks automatically between tests.
+Beware that `mockClear` will replace `mockFn.mock`, not just these three properties! You should, therefore, avoid assigning `mockFn.mock` to other variables, temporary or not, to make sure you don't access stale data.
+
+The [`clearMocks`](configuration#clearmocks-boolean) configuration option is available to clear mocks automatically before each tests.
 
 ### `mockFn.mockReset()`
 
 Does everything that [`mockFn.mockClear()`](#mockfnmockclear) does, and also removes any mocked return values or implementations.
 
 This is useful when you want to completely reset a _mock_ back to its initial state. (Note that resetting a _spy_ will result in a function with no return value).
 
+The [`mockReset`](configuration#resetmocks-boolean) configuration option is available to reset mocks automatically before each test.
+
 ### `mockFn.mockRestore()`
 
 Does everything that [`mockFn.mockReset()`](#mockfnmockreset) does, and also restores the original (non-mocked) implementation.
@@ -99,7 +103,7 @@ This is useful when you want to mock functions in certain test cases and restore
 
 Beware that `mockFn.mockRestore` only works when the mock was created with `jest.spyOn`. Thus you have to take care of restoration yourself when manually assigning `jest.fn()`.
 
-The [`restoreMocks`](configuration#restoremocks-boolean) configuration option is available to restore mocks automatically between tests.
+The [`restoreMocks`](configuration#restoremocks-boolean) configuration option is available to restore mocks automatically before each test.
 
 ### `mockFn.mockImplementation(fn)`