diff --git a/CHANGELOG.md b/CHANGELOG.md index 811f26e02d9c..7a4f8f0eef07 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,8 @@ ### Chore & Maintenance +* `[docs]` Improve documentation of `mockClear`, `mockReset`, and `mockRestore` ([#6227](https://github.com/facebook/jest/pull/6227/files)) +* `[jest-circus]` Add dependency on jest-each ([#6309](https://github.com/facebook/jest/pull/#6309)) * `[jest-each]` Refactor each to use shared implementation with core ([#6345](https://github.com/facebook/jest/pull/6345)) * `[jest-each]` Update jest-each docs for serialising values into titles ([#6337](https://github.com/facebook/jest/pull/6337)) * `[jest-circus]` Add dependency on jest-each ([#6309](https://github.com/facebook/jest/pull/6309)) diff --git a/docs/JestObjectAPI.md b/docs/JestObjectAPI.md index 122084920bbc..9afb5bf05914 100644 --- a/docs/JestObjectAPI.md +++ b/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(); }); ``` diff --git a/docs/MockFunctionAPI.md b/docs/MockFunctionAPI.md index 58de4698337d..dfdfb7672ac8 100644 --- a/docs/MockFunctionAPI.md +++ b/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. diff --git a/packages/jest-mock/src/__tests__/jest_mock.test.js b/packages/jest-mock/src/__tests__/jest_mock.test.js index 7964bd22a235..9c2f5bc8ac59 100644 --- a/packages/jest-mock/src/__tests__/jest_mock.test.js +++ b/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(); diff --git a/packages/jest-mock/src/index.js b/packages/jest-mock/src/index.js index db2e2134802f..9b679c73e4c3 100644 --- a/packages/jest-mock/src/index.js +++ b/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';