Update spyOn docs

CHANGELOG.md

@@ -13,6 +13,7 @@
 ### Chore & Maintenance
 
 - `[*]` Replace internal usage of `pretty-format/ConvertAnsi` with `jest-serializer-ansi-escapes` ([#12935](https://github.com/facebook/jest/pull/12935))
+- `[docs]` Update spyOn docs  ([#4828](https://github.com/facebook/jest/pull/4828))
 
 ### Performance
 

docs/JestObjectAPI.md

@@ -481,7 +481,13 @@ Determines if the given function is a mocked function.
 
 Creates a mock function similar to `jest.fn` but also tracks calls to `object[methodName]`. Returns a Jest [mock function](MockFunctionAPI.md).
 
-_Note: By default, `jest.spyOn` also calls the **spied** method. This is different behavior from most other test libraries. If you want to overwrite the original function, you can use `jest.spyOn(object, methodName).mockImplementation(() => customImplementation)` or `object[methodName] = jest.fn(() => customImplementation);`_
+:::note
+ By default, `jest.spyOn` also calls the **spied** method. This is different behavior from most other test libraries. If you want to overwrite the original function, you can use `jest.spyOn(object, methodName).mockImplementation(() => customImplementation)` or `object[methodName] = jest.fn(() => customImplementation);`
+:::
+
+:::tip
+Since `jest.spyOn` is a mock.  You could restore the initial state calling [jest.restoreAllMocks](#jestrestoreallmocks) on [afterEach](GlobalAPI.md#aftereachfn-timeout) method. 
+:::
 
 Example:
 
@@ -500,14 +506,16 @@ Example test:
 ```js
 const video = require('./video');
 
+afterEach(() => {
+  jest.restoreAllMocks();
+});
+
 test('plays video', () => {
   const spy = jest.spyOn(video, 'play');
   const isPlaying = video.play();
 
   expect(spy).toHaveBeenCalled();
-  expect(isPlaying).toBe(true);
-
-  spy.mockRestore();
+  expect(isPlaying).toBe(true);    
 });
 ```
 
@@ -547,24 +555,24 @@ Example test:
 const audio = require('./audio');
 const video = require('./video');
 
+afterEach(() => {
+  jest.restoreAllMocks();
+});
+
 test('plays video', () => {
   const spy = jest.spyOn(video, 'play', 'get'); // we pass 'get'
   const isPlaying = video.play;
 
   expect(spy).toHaveBeenCalled();
-  expect(isPlaying).toBe(true);
-
-  spy.mockRestore();
+  expect(isPlaying).toBe(true);    
 });
 
 test('plays audio', () => {
   const spy = jest.spyOn(audio, 'volume', 'set'); // we pass 'set'
   audio.volume = 100;
 
   expect(spy).toHaveBeenCalled();
-  expect(audio.volume).toBe(100);
-
-  spy.mockRestore();
+  expect(audio.volume).toBe(100);    
 });
 ```
 

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

@@ -470,8 +470,13 @@ Determines if the given function is a mocked function.
 ### `jest.spyOn(object, methodName)`
 
 Creates a mock function similar to `jest.fn` but also tracks calls to `object[methodName]`. Returns a Jest [mock function](MockFunctionAPI.md).
+:::note
+By default, `jest.spyOn` also calls the **spied** method. This is different behavior from most other test libraries. If you want to overwrite the original function, you can use `jest.spyOn(object, methodName).mockImplementation(() => customImplementation)` or `object[methodName] = jest.fn(() => customImplementation);`
+:::
 
-_Note: By default, `jest.spyOn` also calls the **spied** method. This is different behavior from most other test libraries. If you want to overwrite the original function, you can use `jest.spyOn(object, methodName).mockImplementation(() => customImplementation)` or `object[methodName] = jest.fn(() => customImplementation);`_
+:::tip
+Since `jest.spyOn` is a mock.  You could restore the initial state calling [jest.restoreAllMocks](#jestrestoreallmocks) on [afterEach](GlobalAPI.md#aftereachfn-timeout) method. 
+:::
 
 Example:
 
@@ -490,14 +495,17 @@ Example test:
 ```js
 const video = require('./video');
 
+afterEach(() => {
+  jest.restoreAllMocks();
+});
+
 test('plays video', () => {
   const spy = jest.spyOn(video, 'play');
   const isPlaying = video.play();
 
   expect(spy).toHaveBeenCalled();
   expect(isPlaying).toBe(true);
 
-  spy.mockRestore();
 });
 ```
 
@@ -537,14 +545,17 @@ Example test:
 const audio = require('./audio');
 const video = require('./video');
 
+afterEach(() => {
+  jest.restoreAllMocks();
+});
+
 test('plays video', () => {
   const spy = jest.spyOn(video, 'play', 'get'); // we pass 'get'
   const isPlaying = video.play;
 
   expect(spy).toHaveBeenCalled();
   expect(isPlaying).toBe(true);
 
-  spy.mockRestore();
 });
 
 test('plays audio', () => {
@@ -554,7 +565,6 @@ test('plays audio', () => {
   expect(spy).toHaveBeenCalled();
   expect(audio.volume).toBe(100);
 
-  spy.mockRestore();
 });
 ```
 

website/versioned_docs/version-26.x/JestObjectAPI.md

@@ -475,7 +475,13 @@ Determines if the given function is a mocked function.
 
 Creates a mock function similar to `jest.fn` but also tracks calls to `object[methodName]`. Returns a Jest [mock function](MockFunctionAPI.md).
 
-_Note: By default, `jest.spyOn` also calls the **spied** method. This is different behavior from most other test libraries. If you want to overwrite the original function, you can use `jest.spyOn(object, methodName).mockImplementation(() => customImplementation)` or `object[methodName] = jest.fn(() => customImplementation);`_
+:::note
+By default, `jest.spyOn` also calls the **spied** method. This is different behavior from most other test libraries. If you want to overwrite the original function, you can use `jest.spyOn(object, methodName).mockImplementation(() => customImplementation)` or `object[methodName] = jest.fn(() => customImplementation);`
+:::
+
+:::tip
+Since `jest.spyOn` is a mock.  You could restore the initial state calling [jest.restoreAllMocks](#jestrestoreallmocks) on [afterEach](GlobalAPI.md#aftereachfn-timeout) method. 
+:::
 
 Example:
 
@@ -494,14 +500,17 @@ Example test:
 ```js
 const video = require('./video');
 
+afterEach(() => {
+  jest.restoreAllMocks();
+});
+
 test('plays video', () => {
   const spy = jest.spyOn(video, 'play');
   const isPlaying = video.play();
 
   expect(spy).toHaveBeenCalled();
   expect(isPlaying).toBe(true);
 
-  spy.mockRestore();
 });
 ```
 
@@ -541,14 +550,17 @@ Example test:
 const audio = require('./audio');
 const video = require('./video');
 
+afterEach(() => {
+  jest.restoreAllMocks();
+});
+
 test('plays video', () => {
   const spy = jest.spyOn(video, 'play', 'get'); // we pass 'get'
   const isPlaying = video.play;
 
   expect(spy).toHaveBeenCalled();
   expect(isPlaying).toBe(true);
 
-  spy.mockRestore();
 });
 
 test('plays audio', () => {
@@ -558,7 +570,6 @@ test('plays audio', () => {
   expect(spy).toHaveBeenCalled();
   expect(audio.volume).toBe(100);
 
-  spy.mockRestore();
 });
 ```
 

website/versioned_docs/version-27.x/JestObjectAPI.md

@@ -475,7 +475,13 @@ Determines if the given function is a mocked function.
 
 Creates a mock function similar to `jest.fn` but also tracks calls to `object[methodName]`. Returns a Jest [mock function](MockFunctionAPI.md).
 
-_Note: By default, `jest.spyOn` also calls the **spied** method. This is different behavior from most other test libraries. If you want to overwrite the original function, you can use `jest.spyOn(object, methodName).mockImplementation(() => customImplementation)` or `object[methodName] = jest.fn(() => customImplementation);`_
+:::note
+By default, `jest.spyOn` also calls the **spied** method. This is different behavior from most other test libraries. If you want to overwrite the original function, you can use `jest.spyOn(object, methodName).mockImplementation(() => customImplementation)` or `object[methodName] = jest.fn(() => customImplementation);`
+:::
+
+:::tip
+Since `jest.spyOn` is a mock.  You could restore the initial state calling [jest.restoreAllMocks](#jestrestoreallmocks) on [afterEach](GlobalAPI.md#aftereachfn-timeout) method. 
+:::
 
 Example:
 
@@ -494,14 +500,17 @@ Example test:
 ```js
 const video = require('./video');
 
+afterEach(() => {
+  jest.restoreAllMocks();
+});
+
 test('plays video', () => {
   const spy = jest.spyOn(video, 'play');
   const isPlaying = video.play();
 
   expect(spy).toHaveBeenCalled();
   expect(isPlaying).toBe(true);
 
-  spy.mockRestore();
 });
 ```
 
@@ -541,14 +550,17 @@ Example test:
 const audio = require('./audio');
 const video = require('./video');
 
+afterEach(() => {
+  jest.restoreAllMocks();
+});
+
 test('plays video', () => {
   const spy = jest.spyOn(video, 'play', 'get'); // we pass 'get'
   const isPlaying = video.play;
 
   expect(spy).toHaveBeenCalled();
   expect(isPlaying).toBe(true);
 
-  spy.mockRestore();
 });
 
 test('plays audio', () => {
@@ -558,7 +570,6 @@ test('plays audio', () => {
   expect(spy).toHaveBeenCalled();
   expect(audio.volume).toBe(100);
 
-  spy.mockRestore();
 });
 ```
 

website/versioned_docs/version-28.0/JestObjectAPI.md

@@ -481,7 +481,13 @@ Determines if the given function is a mocked function.
 
 Creates a mock function similar to `jest.fn` but also tracks calls to `object[methodName]`. Returns a Jest [mock function](MockFunctionAPI.md).
 
-_Note: By default, `jest.spyOn` also calls the **spied** method. This is different behavior from most other test libraries. If you want to overwrite the original function, you can use `jest.spyOn(object, methodName).mockImplementation(() => customImplementation)` or `object[methodName] = jest.fn(() => customImplementation);`_
+:::note
+By default, `jest.spyOn` also calls the **spied** method. This is different behavior from most other test libraries. If you want to overwrite the original function, you can use `jest.spyOn(object, methodName).mockImplementation(() => customImplementation)` or `object[methodName] = jest.fn(() => customImplementation);`
+:::
+
+:::tip
+Since `jest.spyOn` is a mock.  You could restore the initial state calling [jest.restoreAllMocks](#jestrestoreallmocks) on [afterEach](GlobalAPI.md#aftereachfn-timeout) method. 
+:::
 
 Example:
 
@@ -500,14 +506,17 @@ Example test:
 ```js
 const video = require('./video');
 
+afterEach(() => {
+  jest.restoreAllMocks();
+});
+
 test('plays video', () => {
   const spy = jest.spyOn(video, 'play');
   const isPlaying = video.play();
 
   expect(spy).toHaveBeenCalled();
   expect(isPlaying).toBe(true);
 
-  spy.mockRestore();
 });
 ```
 
@@ -547,14 +556,17 @@ Example test:
 const audio = require('./audio');
 const video = require('./video');
 
+afterEach(() => {
+  jest.restoreAllMocks();
+});
+
 test('plays video', () => {
   const spy = jest.spyOn(video, 'play', 'get'); // we pass 'get'
   const isPlaying = video.play;
 
   expect(spy).toHaveBeenCalled();
   expect(isPlaying).toBe(true);
 
-  spy.mockRestore();
 });
 
 test('plays audio', () => {
@@ -564,7 +576,6 @@ test('plays audio', () => {
   expect(spy).toHaveBeenCalled();
   expect(audio.volume).toBe(100);
 
-  spy.mockRestore();
 });
 ```
 

website/versioned_docs/version-28.1/JestObjectAPI.md

@@ -481,7 +481,13 @@ Determines if the given function is a mocked function.
 
 Creates a mock function similar to `jest.fn` but also tracks calls to `object[methodName]`. Returns a Jest [mock function](MockFunctionAPI.md).
 
-_Note: By default, `jest.spyOn` also calls the **spied** method. This is different behavior from most other test libraries. If you want to overwrite the original function, you can use `jest.spyOn(object, methodName).mockImplementation(() => customImplementation)` or `object[methodName] = jest.fn(() => customImplementation);`_
+:::note
+By default, `jest.spyOn` also calls the **spied** method. This is different behavior from most other test libraries. If you want to overwrite the original function, you can use `jest.spyOn(object, methodName).mockImplementation(() => customImplementation)` or `object[methodName] = jest.fn(() => customImplementation);`
+:::
+
+:::tip
+Since `jest.spyOn` is a mock.  You could restore the initial state calling [jest.restoreAllMocks](#jestrestoreallmocks) on [afterEach](GlobalAPI.md#aftereachfn-timeout) method. 
+:::
 
 Example:
 
@@ -500,14 +506,18 @@ Example test:
 ```js
 const video = require('./video');
 
+afterEach(() => {
+  jest.restoreAllMocks();
+});
+
+
 test('plays video', () => {
   const spy = jest.spyOn(video, 'play');
   const isPlaying = video.play();
 
   expect(spy).toHaveBeenCalled();
   expect(isPlaying).toBe(true);
 
-  spy.mockRestore();
 });
 ```
 
@@ -547,14 +557,18 @@ Example test:
 const audio = require('./audio');
 const video = require('./video');
 
+afterEach(() => {
+  jest.restoreAllMocks();
+});
+
+
 test('plays video', () => {
   const spy = jest.spyOn(video, 'play', 'get'); // we pass 'get'
   const isPlaying = video.play;
 
   expect(spy).toHaveBeenCalled();
   expect(isPlaying).toBe(true);
 
-  spy.mockRestore();
 });
 
 test('plays audio', () => {
@@ -564,7 +578,6 @@ test('plays audio', () => {
   expect(spy).toHaveBeenCalled();
   expect(audio.volume).toBe(100);
 
-  spy.mockRestore();
 });
 ```