Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: mockClear, mockReset, mockRestore #6227

Merged
merged 2 commits into from
May 30, 2018
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -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))
9 changes: 3 additions & 6 deletions docs/JestObjectAPI.md
Original file line number Diff line number Diff line change
@@ -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();
});
```
6 changes: 3 additions & 3 deletions docs/MockFunctionAPI.md
Original file line number Diff line number Diff line change
@@ -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.

12 changes: 4 additions & 8 deletions packages/jest-mock/src/__tests__/jest_mock.test.js
Original file line number Diff line number Diff line change
@@ -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();
9 changes: 6 additions & 3 deletions packages/jest-mock/src/index.js
Original file line number Diff line number Diff line change
@@ -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;
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ideally I would like this to be return f, to be consistent with the other methods - but keeping the API exactly the same, this is the current behaviour.

};

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';