Add example to jest.requireActual (#8482)

CHANGELOG.md

@@ -12,6 +12,7 @@
 ### Chore & Maintenance
 
 - `[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)
 
 ### Performance
 

docs/JestObjectAPI.md

@@ -321,6 +321,25 @@ _Note It is recommended to use [`jest.mock()`](#jestmockmodulename-factory-optio
 
 Returns the actual module instead of a mock, bypassing all checks on whether the module should receive a mock implementation or not.
 
+Example:
+
+```js
+jest.mock('../myModule', () => {
+  // Require the original module to not be mocked...
+  const originalModule = jest.requireActual(moduleName);
+
+  return {
+    __esModule: true, // Use it when dealing with esModules
+    ...originalModule,
+    getRandom: jest.fn().mockReturnValue(10),
+  };
+});
+
+const getRandom = require('../myModule').getRandom;
+
+getRandom(); // Always returns 10
+```
+
 ### `jest.requireMock(moduleName)`
 
 Returns a mock module instead of the actual module, bypassing all checks on whether the module should be required normally or not.

packages/jest-environment/src/index.ts

@@ -137,6 +137,23 @@ export interface Jest {
   /**
    * Returns the actual module instead of a mock, bypassing all checks on
    * whether the module should receive a mock implementation or not.
+   *
+   * @example
+   ```
+    jest.mock('../myModule', () => {
+    // Require the original module to not be mocked...
+    const originalModule = jest.requireActual(moduleName);
+      return {
+        __esModule: true, // Use it when dealing with esModules
+        ...originalModule,
+        getRandom: jest.fn().mockReturnValue(10),
+      };
+    });
+
+    const getRandom = require('../myModule').getRandom;
+
+    getRandom(); // Always returns 10
+    ```
    */
   requireActual: (moduleName: string) => unknown;
   /**

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

@@ -444,6 +444,25 @@ This is useful for scenarios such as one where the module being tested schedules
 
 Returns the actual module instead of a mock, bypassing all checks on whether the module should receive a mock implementation or not.
 
+Example:
+
+```js
+jest.mock('../myModule', () => {
+  // Require the original module to not be mocked...
+  const originalModule = jest.requireActual(moduleName);
+
+  return {
+    __esModule: true, // Use it when dealing with esModules
+    ...originalModule,
+    getRandom: jest.fn().mockReturnValue(10),
+  };
+});
+
+const getRandom = require('../myModule').getRandom;
+
+getRandom(); // Always returns 10
+```
+
 ### `jest.requireMock(moduleName)`
 
 Returns a mock module instead of the actual module, bypassing all checks on whether the module should be required normally or not.

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

@@ -460,6 +460,25 @@ This is useful for scenarios such as one where the module being tested schedules
 
 Returns the actual module instead of a mock, bypassing all checks on whether the module should receive a mock implementation or not.
 
+Example:
+
+```js
+jest.mock('../myModule', () => {
+  // Require the original module to not be mocked...
+  const originalModule = jest.requireActual(moduleName);
+
+  return {
+    __esModule: true, // Use it when dealing with esModules
+    ...originalModule,
+    getRandom: jest.fn().mockReturnValue(10),
+  };
+});
+
+const getRandom = require('../myModule').getRandom;
+
+getRandom(); // Always returns 10
+```
+
 ### `jest.requireMock(moduleName)`
 
 Returns a mock module instead of the actual module, bypassing all checks on whether the module should be required normally or not.

website/versioned_docs/version-24.0/JestObjectAPI.md

@@ -322,6 +322,25 @@ _Note It is recommended to use [`jest.mock()`](#jestmockmodulename-factory-optio
 
 Returns the actual module instead of a mock, bypassing all checks on whether the module should receive a mock implementation or not.
 
+Example:
+
+```js
+jest.mock('../myModule', () => {
+  // Require the original module to not be mocked...
+  const originalModule = jest.requireActual(moduleName);
+
+  return {
+    __esModule: true, // Use it when dealing with esModules
+    ...originalModule,
+    getRandom: jest.fn().mockReturnValue(10),
+  };
+});
+
+const getRandom = require('../myModule').getRandom;
+
+getRandom(); // Always returns 10
+```
+
 ### `jest.requireMock(moduleName)`
 
 Returns a mock module instead of the actual module, bypassing all checks on whether the module should be required normally or not.