feat(@jest/environment, jest-runtime): allow requireActual and requireMock to take a type argument

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,9 +416,7 @@ _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');
@@ -435,6 +433,24 @@ 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<() => number>().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.
@@ -491,7 +507,7 @@ const otherCopyOfMyModule = require('myModule');
 
 Returns a new, unused [mock function](MockFunctionAPI.md). Optionally takes a mock implementation.
 
-```js
+```js tab
 const mockFn = jest.fn();
 mockFn();
 expect(mockFn).toHaveBeenCalled();
@@ -501,9 +517,19 @@ const returnsTrue = jest.fn(() => true);
 console.log(returnsTrue()); // true;
 ```
 
+```ts tab
+const mockFn = jest.fn<() => void>();
+mockFn();
+expect(mockFn).toHaveBeenCalled();
+
+// With a mock implementation:
+const returnsTrue = jest.fn<() => boolean>(() => true);
+console.log(returnsTrue()); // true;
+```
+
 :::tip
 
-See [Mock Functions](MockFunctionAPI.md#jestfnimplementation) page for details on TypeScript usage.
+See [Mock Functions](MockFunctionAPI.md#jestfnimplementation) page for more details on TypeScript usage.
 
 :::
 

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());