feat(expect, @jest/expect): support type inference for function parame…

CHANGELOG.md

@@ -5,6 +5,7 @@
 - `[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/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))
+- `[feat(expect, jest-expect)]` support type inference for function parameters in `CalledWith` assertions ([#13268](https://github.com/facebook/jest/pull/13268))
 
 ### Fixes
 

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,32 +118,39 @@ export interface AsymmetricMatchers {
   stringMatching(sample: string | RegExp): AsymmetricMatcher;
 }
 
-type PromiseMatchers = {
+// if T is a function, return its parameters array type, otherwise return an unknown array type
+type ConditionalFunctionParameters<T> = T extends (
+  ...args: Array<unknown>
+) => unknown
+  ? Parameters<T>
+  : Array<unknown>;
+
+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>> {
+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;
+  lastCalledWith(...expected: ConditionalFunctionParameters<T>): R;
   /**
    * Ensure that the last call to a mock function has returned a specified value.
    */
   lastReturnedWith(expected: unknown): R;
   /**
    * Ensure that a mock function is called with specific arguments on an Nth call.
    */
-  nthCalledWith(nth: number, ...expected: Array<unknown>): R;
+  nthCalledWith(nth: number, ...expected: ConditionalFunctionParameters<T>): R;
   /**
    * Ensure that the nth call to a mock function has returned a specified value.
    */
@@ -164,7 +171,7 @@ export interface Matchers<R extends void | Promise<void>> {
   /**
    * Ensure that a mock function is called with specific arguments.
    */
-  toBeCalledWith(...expected: Array<unknown>): R;
+  toBeCalledWith(...expected: ConditionalFunctionParameters<T>): R;
   /**
    * Using exact equality with floating point numbers is a bad idea.
    * Rounding means that intuitive things fail.
@@ -247,16 +254,19 @@ export interface Matchers<R extends void | Promise<void>> {
   /**
    * Ensure that a mock function is called with specific arguments.
    */
-  toHaveBeenCalledWith(...expected: Array<unknown>): R;
+  toHaveBeenCalledWith(...expected: ConditionalFunctionParameters<T>): R;
   /**
    * Ensure that a mock function is called with specific arguments on an Nth call.
    */
-  toHaveBeenNthCalledWith(nth: number, ...expected: Array<unknown>): R;
+  toHaveBeenNthCalledWith(
+    nth: number,
+    ...expected: ConditionalFunctionParameters<T>
+  ): R;
   /**
    * If you have a mock function, you can use `.toHaveBeenLastCalledWith`
    * to test what arguments it was last called with.
    */
-  toHaveBeenLastCalledWith(...expected: Array<unknown>): R;
+  toHaveBeenLastCalledWith(...expected: ConditionalFunctionParameters<T>): R;
   /**
    * Use to test the specific value that a mock function last returned.
    * If the last call to the mock function threw an error, then this matcher will fail

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> = {