docs(jest.doMock): Add information for using ES6 modules with doMock

CHANGELOG.md

@@ -20,6 +20,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))
+- `[docs]` Add information about using `jest.doMock` with ES6 imports ([#8573](https://github.com/facebook/jest/pull/8573))
 
 ### Performance
 

docs/JestObjectAPI.md

@@ -314,6 +314,46 @@ test('moduleName 2', () => {
 });
 ```
 
+Using `jest.doMock()` with ES6 imports requires additional steps. Follow these if you don't want to use `require` in your tests:
+
+- We have to specify the `__esModule: true` property (see the [`jest.mock()`](#jestmockmodulename-factory-options) API for more information).
+- Static ES6 module imports are hoisted to the top of the file, so instead we have to import them dynamically using `import()`.
+- Finally, we need an environment which supports dynamic importing. Please see [Using Babel](GettingStarted.md#using-babel) for the initial setup. Then add the plugin [babel-plugin-dynamic-import-node](https://www.npmjs.com/package/babel-plugin-dynamic-import-node), or an equivalent, to your Babel config to enable dynamic importing in Node.
+
+```js
+beforeEach(() => {
+  jest.resetModules();
+});
+
+test('moduleName 1', () => {
+  jest.doMock('../moduleName', () => {
+    return {
+      __esModule: true,
+      default: 'default1',
+      foo: 'foo1',
+    };
+  });
+  return import('../moduleName').then(moduleName => {
+    expect(moduleName.default).toEqual('default1');
+    expect(moduleName.foo).toEqual('foo1');
+  });
+});
+
+test('moduleName 2', () => {
+  jest.doMock('../moduleName', () => {
+    return {
+      __esModule: true,
+      default: 'default2',
+      foo: 'foo2',
+    };
+  });
+  return import('../moduleName').then(moduleName => {
+    expect(moduleName.default).toEqual('default2');
+    expect(moduleName.foo).toEqual('foo2');
+  });
+});
+```
+
 Returns the `jest` object for chaining.
 
 ### `jest.dontMock(moduleName)`

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

@@ -368,6 +368,46 @@ test('moduleName 2', () => {
 });
 ```
 
+Using `jest.doMock()` with ES6 imports requires additional steps. Follow these if you don't want to use `require` in your tests:
+
+- We have to specify the `__esModule: true` property (see the [`jest.mock()`](#jestmockmodulename-factory-options) API for more information).
+- Static ES6 module imports are hoisted to the top of the file, so instead we have to import them dynamically using `import()`.
+- Finally, we need an environment which supports dynamic importing. Please see [Using Babel](GettingStarted.md#using-babel) for the initial setup. Then add the plugin [babel-plugin-dynamic-import-node](https://www.npmjs.com/package/babel-plugin-dynamic-import-node), or an equivalent, to your Babel config to enable dynamic importing in Node.
+
+```js
+beforeEach(() => {
+  jest.resetModules();
+});
+
+test('moduleName 1', () => {
+  jest.doMock('../moduleName', () => {
+    return {
+      __esModule: true,
+      default: 'default1',
+      foo: 'foo1',
+    };
+  });
+  return import('../moduleName').then(moduleName => {
+    expect(moduleName.default).toEqual('default1');
+    expect(moduleName.foo).toEqual('foo1');
+  });
+});
+
+test('moduleName 2', () => {
+  jest.doMock('../moduleName', () => {
+    return {
+      __esModule: true,
+      default: 'default2',
+      foo: 'foo2',
+    };
+  });
+  return import('../moduleName').then(moduleName => {
+    expect(moduleName.default).toEqual('default2');
+    expect(moduleName.foo).toEqual('foo2');
+  });
+});
+```
+
 Returns the `jest` object for chaining.
 
 ### `jest.dontMock(moduleName)`

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

@@ -369,6 +369,46 @@ test('moduleName 2', () => {
 });
 ```
 
+Using `jest.doMock()` with ES6 imports requires additional steps. Follow these if you don't want to use `require` in your tests:
+
+- We have to specify the `__esModule: true` property (see the [`jest.mock()`](#jestmockmodulename-factory-options) API for more information).
+- Static ES6 module imports are hoisted to the top of the file, so instead we have to import them dynamically using `import()`.
+- Finally, we need an environment which supports dynamic importing. Please see [Using Babel](GettingStarted.md#using-babel) for the initial setup. Then add the plugin [babel-plugin-dynamic-import-node](https://www.npmjs.com/package/babel-plugin-dynamic-import-node), or an equivalent, to your Babel config to enable dynamic importing in Node.
+
+```js
+beforeEach(() => {
+  jest.resetModules();
+});
+
+test('moduleName 1', () => {
+  jest.doMock('../moduleName', () => {
+    return {
+      __esModule: true,
+      default: 'default1',
+      foo: 'foo1',
+    };
+  });
+  return import('../moduleName').then(moduleName => {
+    expect(moduleName.default).toEqual('default1');
+    expect(moduleName.foo).toEqual('foo1');
+  });
+});
+
+test('moduleName 2', () => {
+  jest.doMock('../moduleName', () => {
+    return {
+      __esModule: true,
+      default: 'default2',
+      foo: 'foo2',
+    };
+  });
+  return import('../moduleName').then(moduleName => {
+    expect(moduleName.default).toEqual('default2');
+    expect(moduleName.foo).toEqual('foo2');
+  });
+});
+```
+
 Returns the `jest` object for chaining.
 
 ### `jest.dontMock(moduleName)`

website/versioned_docs/version-24.0/JestObjectAPI.md

@@ -315,6 +315,46 @@ test('moduleName 2', () => {
 });
 ```
 
+Using `jest.doMock()` with ES6 imports requires additional steps. Follow these if you don't want to use `require` in your tests:
+
+- We have to specify the `__esModule: true` property (see the [`jest.mock()`](#jestmockmodulename-factory-options) API for more information).
+- Static ES6 module imports are hoisted to the top of the file, so instead we have to import them dynamically using `import()`.
+- Finally, we need an environment which supports dynamic importing. Please see [Using Babel](GettingStarted.md#using-babel) for the initial setup. Then add the plugin [babel-plugin-dynamic-import-node](https://www.npmjs.com/package/babel-plugin-dynamic-import-node), or an equivalent, to your Babel config to enable dynamic importing in Node.
+
+```js
+beforeEach(() => {
+  jest.resetModules();
+});
+
+test('moduleName 1', () => {
+  jest.doMock('../moduleName', () => {
+    return {
+      __esModule: true,
+      default: 'default1',
+      foo: 'foo1',
+    };
+  });
+  return import('../moduleName').then(moduleName => {
+    expect(moduleName.default).toEqual('default1');
+    expect(moduleName.foo).toEqual('foo1');
+  });
+});
+
+test('moduleName 2', () => {
+  jest.doMock('../moduleName', () => {
+    return {
+      __esModule: true,
+      default: 'default2',
+      foo: 'foo2',
+    };
+  });
+  return import('../moduleName').then(moduleName => {
+    expect(moduleName.default).toEqual('default2');
+    expect(moduleName.foo).toEqual('foo2');
+  });
+});
+```
+
 Returns the `jest` object for chaining.
 
 ### `jest.dontMock(moduleName)`