feat(@jest/environment, jest-runtime): allow requireActual and `req…

…uireMock` to take a type argument (#13253)

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ### Features
 
+- `[feat(@jest/environment, jest-runtime)]` Allow `jest.requireActual` and `jest.requireMock` to take a type argument ([#13253](https://github.com/facebook/jest/pull/13253))
 - `[@jest/fake-timers]` Add `jest.now()` to return the current fake clock time ([#13244](https://github.com/facebook/jest/pull/13244), [13246](https://github.com/facebook/jest/pull/13246))
 
 ### Fixes

docs/JestObjectAPI.md

@@ -416,17 +416,33 @@ _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
+```js tab
 jest.mock('../myModule', () => {
   // Require the original module to not be mocked...
   const originalModule = jest.requireActual('../myModule');
 
   return {
     __esModule: true, // Use it when dealing with esModules
     ...originalModule,
-    getRandom: jest.fn().mockReturnValue(10),
+    getRandom: jest.fn(() => 10),
+  };
+});
+
+const getRandom = require('../myModule').getRandom;
+
+getRandom(); // Always returns 10
+```
+
+```ts tab
+jest.mock('../myModule', () => {
+  // Require the original module to not be mocked...
+  const originalModule =
+    jest.requireActual<typeof import('../myModule')>('../myModule');
+
+  return {
+    __esModule: true, // Use it when dealing with esModules
+    ...originalModule,
+    getRandom: jest.fn(() => 10),
   };
 });
 

packages/jest-environment/src/index.ts

@@ -205,7 +205,7 @@ export interface Jest {
      getRandom(); // Always returns 10
      ```
     */
-  requireActual: (moduleName: string) => unknown;
+  requireActual<T = unknown>(moduleName: string): T;
   /**
    * Wraps types of the `source` object and its deep members with type definitions
    * of Jest mock function. Pass `{shallow: true}` option to disable the deeply
@@ -216,7 +216,7 @@ export interface Jest {
    * Returns a mock module instead of the actual module, bypassing all checks
    * on whether the module should be required normally or not.
    */
-  requireMock: (moduleName: string) => unknown;
+  requireMock<T = unknown>(moduleName: string): T;
   /**
    * Resets the state of all mocks. Equivalent to calling `.mockReset()` on
    * every mocked function.

packages/jest-runtime/src/index.ts

@@ -2129,8 +2129,8 @@ export default class Runtime {
       mock,
       mocked,
       now: () => _getFakeTimers().now(),
-      requireActual: this.requireActual.bind(this, from),
-      requireMock: this.requireMock.bind(this, from),
+      requireActual: moduleName => this.requireActual(from, moduleName),
+      requireMock: moduleName => this.requireMock(from, moduleName),
       resetAllMocks,
       resetModules,
       restoreAllMocks,

packages/jest-types/__typetests__/jest.test.ts

@@ -118,9 +118,15 @@ expectType<typeof jest>(
 );
 
 expectType<unknown>(jest.requireActual('./pathToModule'));
+expectType<{some: 'module'}>(
+  jest.requireActual<{some: 'module'}>('./pathToModule'),
+);
 expectError(jest.requireActual());
 
 expectType<unknown>(jest.requireMock('./pathToModule'));
+expectType<{some: 'module'}>(
+  jest.requireMock<{some: 'module'}>('./pathToModule'),
+);
 expectError(jest.requireMock());
 
 expectType<typeof jest>(jest.resetModules());