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

…re` (especially surrounding `spyOn` behaviour)

CHANGELOG.md

@@ -121,6 +121,7 @@
 
 ### Chore & Maintenance
 
+* `[docs]` Improve documentation of `mockClear`, `mockReset`, and `mockRestore` ([#6227](https://github.com/facebook/jest/pull/6227/files))
 * `[jest-runner]` Move sourcemap installation from `jest-jasmine2` to `jest-runner` ([#6176](https://github.com/facebook/jest/pull/6176))
 * `[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

@@ -265,19 +265,19 @@ 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.
+Clears the `mock.calls` and `mock.instances` properties of all mocks. Equivalent 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.
+Restores all mocks back to their original value. Equivalent to calling [`.mockRestore()`](MockFunctionAPI.md#mockfnmockrestore) 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.
 
 ### `jest.resetModules()`
 
@@ -412,7 +412,6 @@ test('plays video', () => {
   expect(spy).toHaveBeenCalled();
   expect(isPlaying).toBe(true);
 
-  spy.mockReset();
   spy.mockRestore();
 });
 ```
@@ -459,7 +458,6 @@ test('plays video', () => {
   expect(spy).toHaveBeenCalled();
   expect(isPlaying).toBe(true);
 
-  spy.mockReset();
   spy.mockRestore();
 });
 
@@ -472,7 +470,6 @@ test('plays audio', () => {
   expect(spy).toHaveBeenCalled();
   expect(audio.volume).toBe(100);
 
-  spy.mockReset();
   spy.mockRestore();
 });
 ```

docs/MockFunctionAPI.md

@@ -80,15 +80,15 @@ The [`clearMocks`](configuration.html#clearmocks-boolean) configuration option i
 
 ### `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 [`mockFn.mock.instances`](#mockfn-mock-instances). You should therefore avoid assigning `mockFn.mock` to other variables, temporary or not, to make sure you 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

@@ -266,19 +266,19 @@ 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.
+Clears the `mock.calls` and `mock.instances` properties of all mocks. Equivalent 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.
+Restores all mocks back to their original value. Equivalent to calling [`.mockRestore()`](MockFunctionAPI.md#mockfnmockrestore) 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.
 
 ### `jest.resetModules()`
 
@@ -413,7 +413,6 @@ test('plays video', () => {
   expect(spy).toHaveBeenCalled();
   expect(isPlaying).toBe(true);
 
-  spy.mockReset();
   spy.mockRestore();
 });
 ```
@@ -460,7 +459,6 @@ test('plays video', () => {
   expect(spy).toHaveBeenCalled();
   expect(isPlaying).toBe(true);
 
-  spy.mockReset();
   spy.mockRestore();
 });
 
@@ -471,7 +469,6 @@ test('plays audio', () => {
   expect(spy).toHaveBeenCalled();
   expect(video.volume).toBe(100);
 
-  spy.mockReset();
   spy.mockRestore();
 });
 ```