docs(jest-mock): Add example for ES6 modules (#8550)

* docs(JestObjectAPI jest-mock): Add example for ES6 modules

Issue #8543

* chore(CHANGELOG): Update CHANGELOG

* docs(JestObjectAPI jest-mock): Add explanation for __esModule: true

Issue #8543

* docs(JestObjectAPI jest-mock): Update versioned_docs

Issue #8543

* Revert "docs(JestObjectAPI jest-mock): Update versioned_docs"

This reverts commit ba17c08.

Updating the versioned_docs for version 24.6 is not necessary as we can
update an earlier version and the changes will propagate to the new
version.

* docs(JestObjectAPI jest-mock): Update previous versioned_docs

The example for using __esModule: true is also relevant for those
versions, so it should be present.

CHANGELOG.md

@@ -17,6 +17,7 @@
 
 - `[jest-leak-detector]` remove code repeat ([#8438](https://github.com/facebook/jest/pull/8438)
 - `[docs]` Add example to `jest.requireActual` ([#8482](https://github.com/facebook/jest/pull/8482)
+- `[docs]` Add example to `jest.mock` for mocking ES6 modules with the `factory` parameter ([#8550](https://github.com/facebook/jest/pull/8550))
 
 ### Performance
 

docs/JestObjectAPI.md

@@ -240,6 +240,23 @@ const moduleName = require('../moduleName');
 moduleName(); // Will return '42';
 ```
 
+When using the `factory` parameter for an ES6 module with a default export, the `__esModule: true` property needs to be specified. This property is normally generated by Babel / TypeScript, but here it needs to be set manually. When importing a default export, it's an instruction to import the property named `default` from the export object:
+
+```js
+import moduleName, {foo} from '../moduleName';
+
+jest.mock('../moduleName', () => {
+  return {
+    __esModule: true,
+    default: jest.fn(() => 42),
+    foo: jest.fn(() => 43),
+  };
+});
+
+moduleName(); // Will return 42
+foo(); // Will return 43
+```
+
 The third argument can be used to create virtual mocks – mocks of modules that don't exist anywhere in the system:
 
 ```js

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

@@ -294,6 +294,23 @@ const moduleName = require('../moduleName');
 moduleName(); // Will return '42';
 ```
 
+When using the `factory` parameter for an ES6 module with a default export, the `__esModule: true` property needs to be specified. This property is normally generated by Babel / TypeScript, but here it needs to be set manually. When importing a default export, it's an instruction to import the property named `default` from the export object:
+
+```js
+import moduleName, {foo} from '../moduleName';
+
+jest.mock('../moduleName', () => {
+  return {
+    __esModule: true,
+    default: jest.fn(() => 42),
+    foo: jest.fn(() => 43),
+  };
+});
+
+moduleName(); // Will return 42
+foo(); // Will return 43
+```
+
 The third argument can be used to create virtual mocks – mocks of modules that don't exist anywhere in the system:
 
 ```js

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

@@ -295,6 +295,23 @@ const moduleName = require('../moduleName');
 moduleName(); // Will return '42';
 ```
 
+When using the `factory` parameter for an ES6 module with a default export, the `__esModule: true` property needs to be specified. This property is normally generated by Babel / TypeScript, but here it needs to be set manually. When importing a default export, it's an instruction to import the property named `default` from the export object:
+
+```js
+import moduleName, {foo} from '../moduleName';
+
+jest.mock('../moduleName', () => {
+  return {
+    __esModule: true,
+    default: jest.fn(() => 42),
+    foo: jest.fn(() => 43),
+  };
+});
+
+moduleName(); // Will return 42
+foo(); // Will return 43
+```
+
 The third argument can be used to create virtual mocks – mocks of modules that don't exist anywhere in the system:
 
 ```js

website/versioned_docs/version-24.0/JestObjectAPI.md

@@ -241,6 +241,23 @@ const moduleName = require('../moduleName');
 moduleName(); // Will return '42';
 ```
 
+When using the `factory` parameter for an ES6 module with a default export, the `__esModule: true` property needs to be specified. This property is normally generated by Babel / TypeScript, but here it needs to be set manually. When importing a default export, it's an instruction to import the property named `default` from the export object:
+
+```js
+import moduleName, {foo} from '../moduleName';
+
+jest.mock('../moduleName', () => {
+  return {
+    __esModule: true,
+    default: jest.fn(() => 42),
+    foo: jest.fn(() => 43),
+  };
+});
+
+moduleName(); // Will return 42
+foo(); // Will return 43
+```
+
 The third argument can be used to create virtual mocks – mocks of modules that don't exist anywhere in the system:
 
 ```js