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

…8573) * docs(jest.doMock): Add information for ES6 modules * chore(CHANGELOG): Update CHANGELOG * docs(jest.doMock): Fix statement on import hoisting behavior * docs(jest.doMock): Clarify statement about ES6 imports and `require` The steps outlined in jest.doMock for ES6 imports are only necessary if you don't want to use `require` in your tests. * docs(jest.doMock): Return promise in example tests
jestjs · Jun 18, 2019 · 85d9698 · 85d9698
1 parent 6fbcd9e
commit 85d9698
Show file tree

Hide file tree

Showing 5 changed files with 161 additions and 0 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -21,6 +21,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
 

diff --git a/docs/JestObjectAPI.md b/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)`

diff --git a/website/versioned_docs/version-22.x/JestObjectAPI.md b/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)`

diff --git a/website/versioned_docs/version-23.x/JestObjectAPI.md b/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)`

diff --git a/website/versioned_docs/version-24.0/JestObjectAPI.md b/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)`