feat(expect, @jest/expect): infer type of *ReturnedWith matchers argument

CHANGELOG.md

@@ -2,9 +2,10 @@
 
 ### 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))
-- `[feat(@jest/environment]` Allow `jest.mock` and `jest.doMock` to take a type argument ([#13254](https://github.com/facebook/jest/pull/13254))
+- `[@jest/environment, jest-runtime]` Allow `jest.requireActual` and `jest.requireMock` to take a type argument ([#13253](https://github.com/facebook/jest/pull/13253))
+- `[@jest/environment]` Allow `jest.mock` and `jest.doMock` to take a type argument ([#13254](https://github.com/facebook/jest/pull/13254))
 - `[@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))
+- `[expect, @jest/expect]` Infer type of `*ReturnedWith` matchers argument ([#13278](https://github.com/facebook/jest/pull/13278))
 
 ### Fixes
 

packages/expect/__typetests__/expect.test.ts

@@ -16,7 +16,8 @@ import {
 } from 'expect';
 import type * as jestMatcherUtils from 'jest-matcher-utils';
 
-type M = Matchers<void>;
+type M = Matchers<void, unknown>;
+type N = Matchers<void>;
 
 expectError(() => {
   type E = Matchers;

packages/expect/src/types.ts

@@ -94,9 +94,9 @@ export interface BaseExpect {
 }
 
 export type Expect = {
-  <T = unknown>(actual: T): Matchers<void> &
-    Inverse<Matchers<void>> &
-    PromiseMatchers;
+  <T = unknown>(actual: T): Matchers<void, T> &
+    Inverse<Matchers<void, T>> &
+    PromiseMatchers<T>;
 } & BaseExpect &
   AsymmetricMatchers &
   Inverse<Omit<AsymmetricMatchers, 'any' | 'anything'>>;
@@ -118,36 +118,40 @@ export interface AsymmetricMatchers {
   stringMatching(sample: string | RegExp): AsymmetricMatcher;
 }
 
-type PromiseMatchers = {
+type PromiseMatchers<T = unknown> = {
   /**
    * Unwraps the reason of a rejected promise so any other matcher can be chained.
    * If the promise is fulfilled the assertion fails.
    */
-  rejects: Matchers<Promise<void>> & Inverse<Matchers<Promise<void>>>;
+  rejects: Matchers<Promise<void>> & Inverse<Matchers<Promise<void>, T>>;
   /**
    * Unwraps the value of a fulfilled promise so any other matcher can be chained.
    * If the promise is rejected the assertion fails.
    */
-  resolves: Matchers<Promise<void>> & Inverse<Matchers<Promise<void>>>;
+  resolves: Matchers<Promise<void>> & Inverse<Matchers<Promise<void>, T>>;
 };
 
-export interface Matchers<R extends void | Promise<void>> {
+type EnsureFunctionLike<T> = T extends (...args: Array<unknown>) => unknown
+  ? T
+  : never;
+
+export interface Matchers<R extends void | Promise<void>, T = unknown> {
   /**
    * Ensures the last call to a mock function was provided specific args.
    */
   lastCalledWith(...expected: Array<unknown>): R;
   /**
    * Ensure that the last call to a mock function has returned a specified value.
    */
-  lastReturnedWith(expected: unknown): R;
+  lastReturnedWith(expected: ReturnType<EnsureFunctionLike<T>>): R;
   /**
    * Ensure that a mock function is called with specific arguments on an Nth call.
    */
   nthCalledWith(nth: number, ...expected: Array<unknown>): R;
   /**
    * Ensure that the nth call to a mock function has returned a specified value.
    */
-  nthReturnedWith(nth: number, expected: unknown): R;
+  nthReturnedWith(nth: number, expected: ReturnType<EnsureFunctionLike<T>>): R;
   /**
    * Checks that a value is what you expect. It calls `Object.is` to compare values.
    * Don't use `toBe` with floating-point numbers.
@@ -262,7 +266,7 @@ export interface Matchers<R extends void | Promise<void>> {
    * If the last call to the mock function threw an error, then this matcher will fail
    * no matter what value you provided as the expected return value.
    */
-  toHaveLastReturnedWith(expected: unknown): R;
+  toHaveLastReturnedWith(expected: ReturnType<EnsureFunctionLike<T>>): R;
   /**
    * Used to check that an object has a `.length` property
    * and it is set to a certain numeric value.
@@ -273,7 +277,10 @@ export interface Matchers<R extends void | Promise<void>> {
    * If the nth call to the mock function threw an error, then this matcher will fail
    * no matter what value you provided as the expected return value.
    */
-  toHaveNthReturnedWith(nth: number, expected: unknown): R;
+  toHaveNthReturnedWith(
+    nth: number,
+    expected: ReturnType<EnsureFunctionLike<T>>,
+  ): R;
   /**
    * Use to check if property at provided reference keyPath exists for an object.
    * For checking deeply nested properties in an object you may use dot notation or an array containing
@@ -303,7 +310,7 @@ export interface Matchers<R extends void | Promise<void>> {
   /**
    * Use to ensure that a mock function returned a specific value.
    */
-  toHaveReturnedWith(expected: unknown): R;
+  toHaveReturnedWith(expected: ReturnType<EnsureFunctionLike<T>>): R;
   /**
    * Check that a string matches a regular expression.
    */
@@ -325,7 +332,7 @@ export interface Matchers<R extends void | Promise<void>> {
   /**
    * Ensure that a mock function has returned a specified value at least once.
    */
-  toReturnWith(expected: unknown): R;
+  toReturnWith(expected: ReturnType<EnsureFunctionLike<T>>): R;
   /**
    * Use to test that objects have the same types as well as structure.
    */

packages/jest-expect/src/types.ts

@@ -29,7 +29,7 @@ type Inverse<Matchers> = {
   not: Matchers;
 };
 
-type JestMatchers<R extends void | Promise<void>, T> = Matchers<R> &
+type JestMatchers<R extends void | Promise<void>, T> = Matchers<R, T> &
   SnapshotMatchers<R, T>;
 
 type PromiseMatchers<T = unknown> = {

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

@@ -247,21 +247,44 @@ expectError(expect(jest.fn()).toHaveReturnedTimes(true));
 expectError(expect(jest.fn()).toHaveReturnedTimes());
 
 expectType<void>(expect(jest.fn()).toReturnWith('value'));
+expectType<void>(expect(jest.fn<() => string>()).toReturnWith('value'));
+expectError(expect(jest.fn<() => number>()).toReturnWith('value'));
+expectError(expect(123).toReturnWith('value'));
 expectError(expect(jest.fn()).toReturnWith());
+
 expectType<void>(expect(jest.fn()).toHaveReturnedWith(123));
+expectType<void>(expect(jest.fn<() => number>()).toHaveReturnedWith(123));
+expectError(expect(jest.fn<() => string>()).toHaveReturnedWith(123));
+expectError(expect(123).toHaveReturnedWith(123));
 expectError(expect(jest.fn()).toHaveReturnedWith());
 
 expectType<void>(expect(jest.fn()).lastReturnedWith('value'));
+expectType<void>(expect(jest.fn<() => string>()).lastReturnedWith('value'));
+expectError(expect(jest.fn<() => number>()).lastReturnedWith('value'));
+expectError(expect(123).lastReturnedWith('value'));
 expectError(expect(jest.fn()).lastReturnedWith());
+
 expectType<void>(expect(jest.fn()).toHaveLastReturnedWith(123));
+expectType<void>(expect(jest.fn<() => number>()).toHaveLastReturnedWith(123));
+expectError(expect(jest.fn<() => string>()).toHaveLastReturnedWith(123));
+expectError(expect(123).toHaveLastReturnedWith(123));
 expectError(expect(jest.fn()).toHaveLastReturnedWith());
 
 expectType<void>(expect(jest.fn()).nthReturnedWith(1, 'value'));
+expectType<void>(expect(jest.fn<() => string>()).nthReturnedWith(2, 'value'));
+expectError(expect(jest.fn<() => number>()).nthReturnedWith(3, 'value'));
+expectError(expect(123).nthReturnedWith(4, 'value'));
+expectError(expect(123).nthReturnedWith(5));
 expectError(expect(jest.fn()).nthReturnedWith());
-expectError(expect(jest.fn()).nthReturnedWith(2));
+
 expectType<void>(expect(jest.fn()).toHaveNthReturnedWith(1, 'value'));
+expectType<void>(
+  expect(jest.fn<() => string>()).toHaveNthReturnedWith(2, 'value'),
+);
+expectError(expect(jest.fn<() => number>()).toHaveNthReturnedWith(3, 'value'));
+expectError(expect(123).toHaveNthReturnedWith(4, 'value'));
+expectError(expect(123).toHaveNthReturnedWith(5));
 expectError(expect(jest.fn()).toHaveNthReturnedWith());
-expectError(expect(jest.fn()).toHaveNthReturnedWith(2));
 
 // snapshot matchers