Improve the documentation of mockClear, mockReset, and `mockResto…

…re` (especially surrounding `spyOn` behaviour)

CHANGELOG.md

@@ -169,6 +169,8 @@
 
 ### Chore & Maintenance
 
+* `[docs]` Improve documentation of `mockClear`, `mockReset`, and `mockRestore`
+  ([#6227](https://github.com/facebook/jest/pull/6227/files))
 * `[jest-cli]` Use yargs's built-in `version` instead of rolling our own
   ([#6215](https://github.com/facebook/jest/pull/6215))
 * `[docs]` Add explanation on how to mock methods not implemented in JSDOM

docs/JestObjectAPI.md

@@ -301,23 +301,25 @@ Returns the `jest` object for chaining.
 ### `jest.clearAllMocks()`
 
 Clears the `mock.calls` and `mock.instances` properties of all mocks. Equivalent
-to calling `.mockClear()` on every mocked function.
+to calling [`.mockClear()`](MockFunctionAPI.md#mockfnmockclear) on every mocked
+function.
 
 Returns the `jest` object for chaining.
 
 ### `jest.resetAllMocks()`
 
-Resets the state of all mocks. Equivalent to calling `.mockReset()` on every
-mocked function.
+Resets the state of all mocks. Equivalent to calling
+[`.mockReset()`](MockFunctionAPI.md#mockfnmockreset) on every mocked function.
 
 Returns the `jest` object for chaining.
 
 ### `jest.restoreAllMocks()`
 
 Restores all mocks back to their original value. Equivalent to calling
-`.mockRestore` on every mocked function. Beware that `jest.restoreAllMocks()`
-only works when mock was created with `jest.spyOn`; other mocks will require you
-to manually restore them.
+`.mockRestore` on every mocked function. Beware that
+[`jest.restoreAllMocks()`](MockFunctionAPI.md#mockfnmockrestore) only works when
+mock was created with `jest.spyOn`; other mocks will require you to manually
+restore them.
 
 ### `jest.resetModules()`
 
@@ -495,7 +497,6 @@ test('plays video', () => {
   expect(spy).toHaveBeenCalled();
   expect(isPlaying).toBe(true);
 
-  spy.mockReset();
   spy.mockRestore();
 });
 ```
@@ -544,7 +545,6 @@ test('plays video', () => {
   expect(spy).toHaveBeenCalled();
   expect(isPlaying).toBe(true);
 
-  spy.mockReset();
   spy.mockRestore();
 });
 
@@ -557,7 +557,6 @@ test('plays audio', () => {
   expect(spy).toHaveBeenCalled();
   expect(audio.volume).toBe(100);
 
-  spy.mockReset();
   spy.mockRestore();
 });
 ```

docs/MockFunctionAPI.md

@@ -102,11 +102,12 @@ is available to clear mocks automatically between tests.
 
 ### `mockFn.mockReset()`
 
-Resets all information stored in the mock, including any initial implementation
-and mock name given.
+Does everything that [`mockFn.mockClear()`](#mockfnmockclear) does, and also
+removes any mocked return values or implementations.
 
-This is useful when you want to completely restore a mock back to its initial
-state.
+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).
 
 Beware that `mockReset` will replace `mockFn.mock`, not just
 [`mockFn.mock.calls`](#mockfn-mock-calls) and
@@ -116,7 +117,8 @@ don't access stale data.
 
 ### `mockFn.mockRestore()`
 
-Removes the mock and restores the initial implementation.
+Does everything that [`mockFn.mockReset()`](#mockfnmockreset) does, and also
+restores the original (non-mocked) implementation.
 
 This is useful when you want to mock functions in certain test cases and restore
 the original implementation in others.

packages/jest-mock/src/__tests__/jest_mock.test.js

@@ -737,12 +737,13 @@ describe('moduleMocker', () => {
     expect(fn.getMockName()).toBe('jest.fn()');
   });
 
-  test('mockName is not reset by mockRestore', () => {
-    const fn = jest.fn(() => false);
+  test('mockName gets reset by mockRestore', () => {
+    const fn = jest.fn();
+    expect(fn.getMockName()).toBe('jest.fn()');
     fn.mockName('myMockFn');
     expect(fn.getMockName()).toBe('myMockFn');
     fn.mockRestore();
-    expect(fn.getMockName()).toBe('myMockFn');
+    expect(fn.getMockName()).toBe('jest.fn()');
   });
 
   test('mockName is not reset by mockClear', () => {
@@ -782,7 +783,6 @@ describe('moduleMocker', () => {
       isOriginalCalled = false;
       originalCallThis = null;
       originalCallArguments = null;
-      spy.mockReset();
       spy.mockRestore();
       obj.method.call(thisArg, firstArg, secondArg);
       expect(isOriginalCalled).toBe(true);
@@ -873,7 +873,6 @@ describe('moduleMocker', () => {
       isOriginalCalled = false;
       originalCallThis = null;
       originalCallArguments = null;
-      spy.mockReset();
       spy.mockRestore();
       obj.method.call(thisArg, firstArg, secondArg);
       expect(isOriginalCalled).toBe(true);
@@ -900,7 +899,6 @@ describe('moduleMocker', () => {
       expect(spy).toHaveBeenCalled();
       expect(obj.property).toBe(true);
       obj.property = false;
-      spy.mockReset();
       spy.mockRestore();
       obj.property = true;
       expect(spy).not.toHaveBeenCalled();
@@ -990,7 +988,6 @@ describe('moduleMocker', () => {
       isOriginalCalled = false;
       originalCallThis = null;
       originalCallArguments = null;
-      spy.mockReset();
       spy.mockRestore();
       obj.method.call(thisArg, firstArg, secondArg);
       expect(isOriginalCalled).toBe(true);
@@ -1018,7 +1015,6 @@ describe('moduleMocker', () => {
       expect(spy).toHaveBeenCalled();
       expect(obj.property).toBe(true);
       obj.property = false;
-      spy.mockReset();
       spy.mockRestore();
       obj.property = true;
       expect(spy).not.toHaveBeenCalled();

packages/jest-mock/src/index.js

@@ -456,11 +456,16 @@ class ModuleMockerClass {
       };
 
       f.mockReset = () => {
-        this._mockState.delete(f);
+        f.mockClear();
         this._mockConfigRegistry.delete(f);
         return f;
       };
 
+      f.mockRestore = () => {
+        f.mockReset();
+        return restore ? restore() : undefined;
+      };
+
       f.mockReturnValueOnce = value => {
         // next function call will return this value or default return value
         const mockConfig = this._ensureMockConfig(f);
@@ -528,8 +533,6 @@ class ModuleMockerClass {
         f.mockImplementation(metadata.mockImpl);
       }
 
-      f.mockRestore = restore ? restore : () => {};
-
       return f;
     } else {
       const unknownType = metadata.type || 'undefined type';

website/versioned_docs/version-22.4/JestObjectAPI.md

@@ -302,23 +302,25 @@ Returns the `jest` object for chaining.
 ### `jest.clearAllMocks()`
 
 Clears the `mock.calls` and `mock.instances` properties of all mocks. Equivalent
-to calling `.mockClear()` on every mocked function.
+to calling [`.mockClear()`](MockFunctionAPI.md#mockfnmockclear) on every mocked
+function.
 
 Returns the `jest` object for chaining.
 
 ### `jest.resetAllMocks()`
 
-Resets the state of all mocks. Equivalent to calling `.mockReset()` on every
-mocked function.
+Resets the state of all mocks. Equivalent to calling
+[`.mockReset()`](MockFunctionAPI.md#mockfnmockreset) on every mocked function.
 
 Returns the `jest` object for chaining.
 
 ### `jest.restoreAllMocks()`
 
 Restores all mocks back to their original value. Equivalent to calling
-`.mockRestore` on every mocked function. Beware that `jest.restoreAllMocks()`
-only works when mock was created with `jest.spyOn`; other mocks will require you
-to manually restore them.
+`.mockRestore` on every mocked function. Beware that
+[`jest.restoreAllMocks()`](MockFunctionAPI.md#mockfnmockrestore) only works when
+mock was created with `jest.spyOn`; other mocks will require you to manually
+restore them.
 
 ### `jest.resetModules()`
 
@@ -496,7 +498,6 @@ test('plays video', () => {
   expect(spy).toHaveBeenCalled();
   expect(isPlaying).toBe(true);
 
-  spy.mockReset();
   spy.mockRestore();
 });
 ```
@@ -545,7 +546,6 @@ test('plays video', () => {
   expect(spy).toHaveBeenCalled();
   expect(isPlaying).toBe(true);
 
-  spy.mockReset();
   spy.mockRestore();
 });
 
@@ -556,7 +556,6 @@ test('plays audio', () => {
   expect(spy).toHaveBeenCalled();
   expect(video.volume).toBe(100);
 
-  spy.mockReset();
   spy.mockRestore();
 });
 ```