docs: ESM update

docs/ECMAScriptModules.md

@@ -7,7 +7,7 @@ Jest ships with _experimental_ support for ECMAScript Modules (ESM).
 
 > Note that due to its experimental nature there are many bugs and missing features in Jest's implementation, both known and unknown. You should check out the [tracking issue](https://github.com/facebook/jest/issues/9430) and the [label](https://github.com/facebook/jest/labels/ES%20Modules) on the issue tracker for the latest status.
 
-> Also note that the APIs Jest uses to implement ESM support is still [considered experimental by Node](https://nodejs.org/api/vm.html#vm_class_vm_module) (as of version `14.13.1`).
+> Also note that the APIs Jest uses to implement ESM support is still [considered experimental by Node](https://nodejs.org/api/vm.html#vm_class_vm_module) (as of version `18.8.0`).
 
 With the warnings out of the way, this is how you activate ESM support in your tests.
 
@@ -38,4 +38,35 @@ import.meta.jest.useFakeTimers();
 // jest === import.meta.jest => true
 ```
 
+Additionally, since ESM evaluates static `import` statements before looking at the code, hoisting on `jest.mock` calls that happens in CJS modules won't work in ESM. To `mock` modules in ESM, you need to use dynamic `import()` after `jest.mock` calls to load the mocked modules, same applies to modules which have to load the mocked modules.
+
+```js
+// - main.cjs
+const { BrowserWindow, app } = require('electron');
+
+// etc.
+
+module.exports = { example };
+```
+
+```js
+// - main.test.js
+import { jest } from '@jest/globals';
+
+jest.mock('electron', () => ({
+  app: {
+    on: jest.fn(),
+    whenReady: jest.fn(() => Promise.resolve()),
+  },
+  BrowserWindow: jest.fn().mockImplementation(() => ({
+    // partial mocks.
+  }))
+}));
+
+const { BrowserWindow } = (await import('electron')).default;
+const exported = await import('main.cjs');
+
+// etc.
+```
+
 Please note that we currently don't support `jest.mock` in a clean way in ESM, but that is something we intend to add proper support for in the future. Follow [this issue](https://github.com/facebook/jest/issues/10025) for updates.

docs/ManualMocks.md

@@ -130,6 +130,8 @@ The code for this example is available at [examples/manual-mocks](https://github
 
 If you're using [ES module imports](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import) then you'll normally be inclined to put your `import` statements at the top of the test file. But often you need to instruct Jest to use a mock before modules use it. For this reason, Jest will automatically hoist `jest.mock` calls to the top of the module (before any imports). To learn more about this and see it in action, see [this repo](https://github.com/kentcdodds/how-jest-mocking-works).
 
+*__Caution__: Jest does NOT hoist `jest.mock` calls to the top of the module if you have ESM support activated. See [ECMAScriptModules](ECMAScriptModules.md) for details.*
+
 ## Mocking methods which are not implemented in JSDOM
 
 If some code uses a method which JSDOM (the DOM implementation used by Jest) hasn't implemented yet, testing it is not easily possible. This is e.g. the case with `window.matchMedia()`. Jest returns `TypeError: window.matchMedia is not a function` and doesn't properly execute the test.

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

@@ -7,7 +7,7 @@ Jest ships with _experimental_ support for ECMAScript Modules (ESM).
 
 > Note that due to its experimental nature there are many bugs and missing features in Jest's implementation, both known and unknown. You should check out the [tracking issue](https://github.com/facebook/jest/issues/9430) and the [label](https://github.com/facebook/jest/labels/ES%20Modules) on the issue tracker for the latest status.
 
-> Also note that the APIs Jest uses to implement ESM support is still [considered experimental by Node](https://nodejs.org/api/vm.html#vm_class_vm_module) (as of version `14.13.1`).
+> Also note that the APIs Jest uses to implement ESM support is still [considered experimental by Node](https://nodejs.org/api/vm.html#vm_class_vm_module) (as of version `18.8.0`).
 
 With the warnings out of the way, this is how you activate ESM support in your tests.
 
@@ -32,4 +32,35 @@ jest.useFakeTimers();
 // etc.
 ```
 
+Additionally, since ESM evaluates static `import` statements before looking at the code, hoisting on `jest.mock` calls that happens in CJS modules won't work in ESM. To `mock` modules in ESM, you need to use dynamic `import()` after `jest.mock` calls to load the mocked modules, same applies to modules which have to load the mocked modules.
+
+```js
+// - main.cjs
+const { BrowserWindow, app } = require('electron');
+
+// etc.
+
+module.exports = { example };
+```
+
+```js
+// - main.test.js
+import { jest } from '@jest/globals';
+
+jest.mock('electron', () => ({
+  app: {
+    on: jest.fn(),
+    whenReady: jest.fn(() => Promise.resolve()),
+  },
+  BrowserWindow: jest.fn().mockImplementation(() => ({
+    // partial mocks.
+  }))
+}));
+
+const { BrowserWindow } = (await import('electron')).default;
+const exported = await import('main.cjs');
+
+// etc.
+```
+
 Please note that we currently don't support `jest.mock` in a clean way in ESM, but that is something we intend to add proper support for in the future. Follow [this issue](https://github.com/facebook/jest/issues/10025) for updates.

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

@@ -130,6 +130,8 @@ The code for this example is available at [examples/manual-mocks](https://github
 
 If you're using [ES module imports](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import) then you'll normally be inclined to put your `import` statements at the top of the test file. But often you need to instruct Jest to use a mock before modules use it. For this reason, Jest will automatically hoist `jest.mock` calls to the top of the module (before any imports). To learn more about this and see it in action, see [this repo](https://github.com/kentcdodds/how-jest-mocking-works).
 
+*__Caution__: Jest does NOT hoist `jest.mock` calls to the top of the module if you have ESM support activated. See [ECMAScriptModules](ECMAScriptModules.md) for details.*
+
 ## Mocking methods which are not implemented in JSDOM
 
 If some code uses a method which JSDOM (the DOM implementation used by Jest) hasn't implemented yet, testing it is not easily possible. This is e.g. the case with `window.matchMedia()`. Jest returns `TypeError: window.matchMedia is not a function` and doesn't properly execute the test.

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

@@ -7,7 +7,7 @@ Jest ships with _experimental_ support for ECMAScript Modules (ESM).
 
 > Note that due to its experimental nature there are many bugs and missing features in Jest's implementation, both known and unknown. You should check out the [tracking issue](https://github.com/facebook/jest/issues/9430) and the [label](https://github.com/facebook/jest/labels/ES%20Modules) on the issue tracker for the latest status.
 
-> Also note that the APIs Jest uses to implement ESM support is still [considered experimental by Node](https://nodejs.org/api/vm.html#vm_class_vm_module) (as of version `14.13.1`).
+> Also note that the APIs Jest uses to implement ESM support is still [considered experimental by Node](https://nodejs.org/api/vm.html#vm_class_vm_module) (as of version `18.8.0`).
 
 With the warnings out of the way, this is how you activate ESM support in your tests.
 
@@ -32,4 +32,35 @@ jest.useFakeTimers();
 // etc.
 ```
 
+Additionally, since ESM evaluates static `import` statements before looking at the code, hoisting on `jest.mock` calls that happens in CJS modules won't work in ESM. To `mock` modules in ESM, you need to use dynamic `import()` after `jest.mock` calls to load the mocked modules, same applies to modules which have to load the mocked modules.
+
+```js
+// - main.cjs
+const { BrowserWindow, app } = require('electron');
+
+// etc.
+
+module.exports = { example };
+```
+
+```js
+// - main.test.js
+import { jest } from '@jest/globals';
+
+jest.mock('electron', () => ({
+  app: {
+    on: jest.fn(),
+    whenReady: jest.fn(() => Promise.resolve()),
+  },
+  BrowserWindow: jest.fn().mockImplementation(() => ({
+    // partial mocks.
+  }))
+}));
+
+const { BrowserWindow } = (await import('electron')).default;
+const exported = await import('main.cjs');
+
+// etc.
+```
+
 Please note that we currently don't support `jest.mock` in a clean way in ESM, but that is something we intend to add proper support for in the future. Follow [this issue](https://github.com/facebook/jest/issues/10025) for updates.

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

@@ -130,6 +130,8 @@ The code for this example is available at [examples/manual-mocks](https://github
 
 If you're using [ES module imports](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import) then you'll normally be inclined to put your `import` statements at the top of the test file. But often you need to instruct Jest to use a mock before modules use it. For this reason, Jest will automatically hoist `jest.mock` calls to the top of the module (before any imports). To learn more about this and see it in action, see [this repo](https://github.com/kentcdodds/how-jest-mocking-works).
 
+*__Caution__: Jest does NOT hoist `jest.mock` calls to the top of the module if you have ESM support activated. See [ECMAScriptModules](ECMAScriptModules.md) for details.*
+
 ## Mocking methods which are not implemented in JSDOM
 
 If some code uses a method which JSDOM (the DOM implementation used by Jest) hasn't implemented yet, testing it is not easily possible. This is e.g. the case with `window.matchMedia()`. Jest returns `TypeError: window.matchMedia is not a function` and doesn't properly execute the test.

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

@@ -7,7 +7,7 @@ Jest ships with _experimental_ support for ECMAScript Modules (ESM).
 
 > Note that due to its experimental nature there are many bugs and missing features in Jest's implementation, both known and unknown. You should check out the [tracking issue](https://github.com/facebook/jest/issues/9430) and the [label](https://github.com/facebook/jest/labels/ES%20Modules) on the issue tracker for the latest status.
 
-> Also note that the APIs Jest uses to implement ESM support is still [considered experimental by Node](https://nodejs.org/api/vm.html#vm_class_vm_module) (as of version `14.13.1`).
+> Also note that the APIs Jest uses to implement ESM support is still [considered experimental by Node](https://nodejs.org/api/vm.html#vm_class_vm_module) (as of version `18.8.0`).
 
 With the warnings out of the way, this is how you activate ESM support in your tests.
 
@@ -33,4 +33,35 @@ jest.useFakeTimers();
 // etc.
 ```
 
+Additionally, since ESM evaluates static `import` statements before looking at the code, hoisting on `jest.mock` calls that happens in CJS modules won't work in ESM. To `mock` modules in ESM, you need to use dynamic `import()` after `jest.mock` calls to load the mocked modules, same applies to modules which have to load the mocked modules.
+
+```js
+// - main.cjs
+const { BrowserWindow, app } = require('electron');
+
+// etc.
+
+module.exports = { example };
+```
+
+```js
+// - main.test.js
+import { jest } from '@jest/globals';
+
+jest.mock('electron', () => ({
+  app: {
+    on: jest.fn(),
+    whenReady: jest.fn(() => Promise.resolve()),
+  },
+  BrowserWindow: jest.fn().mockImplementation(() => ({
+    // partial mocks.
+  }))
+}));
+
+const { BrowserWindow } = (await import('electron')).default;
+const exported = await import('main.cjs');
+
+// etc.
+```
+
 Please note that we currently don't support `jest.mock` in a clean way in ESM, but that is something we intend to add proper support for in the future. Follow [this issue](https://github.com/facebook/jest/issues/10025) for updates.

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

@@ -130,6 +130,8 @@ The code for this example is available at [examples/manual-mocks](https://github
 
 If you're using [ES module imports](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import) then you'll normally be inclined to put your `import` statements at the top of the test file. But often you need to instruct Jest to use a mock before modules use it. For this reason, Jest will automatically hoist `jest.mock` calls to the top of the module (before any imports). To learn more about this and see it in action, see [this repo](https://github.com/kentcdodds/how-jest-mocking-works).
 
+*__Caution__: Jest does NOT hoist `jest.mock` calls to the top of the module if you have ESM support activated. See [ECMAScriptModules](ECMAScriptModules.md) for details.*
+
 ## Mocking methods which are not implemented in JSDOM
 
 If some code uses a method which JSDOM (the DOM implementation used by Jest) hasn't implemented yet, testing it is not easily possible. This is e.g. the case with `window.matchMedia()`. Jest returns `TypeError: window.matchMedia is not a function` and doesn't properly execute the test.

website/versioned_docs/version-28.x/ECMAScriptModules.md

@@ -7,7 +7,7 @@ Jest ships with _experimental_ support for ECMAScript Modules (ESM).
 
 > Note that due to its experimental nature there are many bugs and missing features in Jest's implementation, both known and unknown. You should check out the [tracking issue](https://github.com/facebook/jest/issues/9430) and the [label](https://github.com/facebook/jest/labels/ES%20Modules) on the issue tracker for the latest status.
 
-> Also note that the APIs Jest uses to implement ESM support is still [considered experimental by Node](https://nodejs.org/api/vm.html#vm_class_vm_module) (as of version `14.13.1`).
+> Also note that the APIs Jest uses to implement ESM support is still [considered experimental by Node](https://nodejs.org/api/vm.html#vm_class_vm_module) (as of version `18.8.0`).
 
 With the warnings out of the way, this is how you activate ESM support in your tests.
 
@@ -38,4 +38,35 @@ import.meta.jest.useFakeTimers();
 // jest === import.meta.jest => true
 ```
 
+Additionally, since ESM evaluates static `import` statements before looking at the code, hoisting on `jest.mock` calls that happens in CJS modules won't work in ESM. To `mock` modules in ESM, you need to use dynamic `import()` after `jest.mock` calls to load the mocked modules, same applies to modules which have to load the mocked modules.
+
+```js
+// - main.cjs
+const { BrowserWindow, app } = require('electron');
+
+// etc.
+
+module.exports = { example };
+```
+
+```js
+// - main.test.js
+import { jest } from '@jest/globals';
+
+jest.mock('electron', () => ({
+  app: {
+    on: jest.fn(),
+    whenReady: jest.fn(() => Promise.resolve()),
+  },
+  BrowserWindow: jest.fn().mockImplementation(() => ({
+    // partial mocks.
+  }))
+}));
+
+const { BrowserWindow } = (await import('electron')).default;
+const exported = await import('main.cjs');
+
+// etc.
+```
+
 Please note that we currently don't support `jest.mock` in a clean way in ESM, but that is something we intend to add proper support for in the future. Follow [this issue](https://github.com/facebook/jest/issues/10025) for updates.

website/versioned_docs/version-28.x/ManualMocks.md

@@ -130,6 +130,8 @@ The code for this example is available at [examples/manual-mocks](https://github
 
 If you're using [ES module imports](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import) then you'll normally be inclined to put your `import` statements at the top of the test file. But often you need to instruct Jest to use a mock before modules use it. For this reason, Jest will automatically hoist `jest.mock` calls to the top of the module (before any imports). To learn more about this and see it in action, see [this repo](https://github.com/kentcdodds/how-jest-mocking-works).
 
+*__Caution__: Jest does NOT hoist `jest.mock` calls to the top of the module if you have ESM support activated. See [ECMAScriptModules](ECMAScriptModules.md) for details.*
+
 ## Mocking methods which are not implemented in JSDOM
 
 If some code uses a method which JSDOM (the DOM implementation used by Jest) hasn't implemented yet, testing it is not easily possible. This is e.g. the case with `window.matchMedia()`. Jest returns `TypeError: window.matchMedia is not a function` and doesn't properly execute the test.

website/versioned_docs/version-29.0/ECMAScriptModules.md

@@ -7,7 +7,7 @@ Jest ships with _experimental_ support for ECMAScript Modules (ESM).
 
 > Note that due to its experimental nature there are many bugs and missing features in Jest's implementation, both known and unknown. You should check out the [tracking issue](https://github.com/facebook/jest/issues/9430) and the [label](https://github.com/facebook/jest/labels/ES%20Modules) on the issue tracker for the latest status.
 
-> Also note that the APIs Jest uses to implement ESM support is still [considered experimental by Node](https://nodejs.org/api/vm.html#vm_class_vm_module) (as of version `14.13.1`).
+> Also note that the APIs Jest uses to implement ESM support is still [considered experimental by Node](https://nodejs.org/api/vm.html#vm_class_vm_module) (as of version `18.8.0`).
 
 With the warnings out of the way, this is how you activate ESM support in your tests.
 
@@ -38,4 +38,35 @@ import.meta.jest.useFakeTimers();
 // jest === import.meta.jest => true
 ```
 
+Additionally, since ESM evaluates static `import` statements before looking at the code, hoisting on `jest.mock` calls that happens in CJS modules won't work in ESM. To `mock` modules in ESM, you need to use dynamic `import()` after `jest.mock` calls to load the mocked modules, same applies to modules which have to load the mocked modules.
+
+```js
+// - main.cjs
+const { BrowserWindow, app } = require('electron');
+
+// etc.
+
+module.exports = { example };
+```
+
+```js
+// - main.test.js
+import { jest } from '@jest/globals';
+
+jest.mock('electron', () => ({
+  app: {
+    on: jest.fn(),
+    whenReady: jest.fn(() => Promise.resolve()),
+  },
+  BrowserWindow: jest.fn().mockImplementation(() => ({
+    // partial mocks.
+  }))
+}));
+
+const { BrowserWindow } = (await import('electron')).default;
+const exported = await import('main.cjs');
+
+// etc.
+```
+
 Please note that we currently don't support `jest.mock` in a clean way in ESM, but that is something we intend to add proper support for in the future. Follow [this issue](https://github.com/facebook/jest/issues/10025) for updates.

website/versioned_docs/version-29.0/ManualMocks.md

@@ -130,6 +130,8 @@ The code for this example is available at [examples/manual-mocks](https://github
 
 If you're using [ES module imports](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import) then you'll normally be inclined to put your `import` statements at the top of the test file. But often you need to instruct Jest to use a mock before modules use it. For this reason, Jest will automatically hoist `jest.mock` calls to the top of the module (before any imports). To learn more about this and see it in action, see [this repo](https://github.com/kentcdodds/how-jest-mocking-works).
 
+*__Caution__: Jest does NOT hoist `jest.mock` calls to the top of the module if you have ESM support activated. See [ECMAScriptModules](ECMAScriptModules.md) for details.*
+
 ## Mocking methods which are not implemented in JSDOM
 
 If some code uses a method which JSDOM (the DOM implementation used by Jest) hasn't implemented yet, testing it is not easily possible. This is e.g. the case with `window.matchMedia()`. Jest returns `TypeError: window.matchMedia is not a function` and doesn't properly execute the test.