feat(expect, @jest/expect): support type inference for toBe assertions

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ### Features
 
+- `[expect, @jest/expect]` support type inference for `toBe` assertions ([#13470](https://github.com/facebook/jest/pull/13470))
 - `[@jest/globals, jest-mock]` Add `jest.Spied*` utility types ([#13440](https://github.com/facebook/jest/pull/13440))
 
 ### Fixes

packages/expect/src/types.ts

@@ -94,9 +94,9 @@ export interface BaseExpect {
 }
 
 export type Expect = {
-  <T = unknown>(actual: T): Matchers<void> &
+  <T = unknown>(actual: T): Matchers<void, T> &
     Inverse<Matchers<void>> &
-    PromiseMatchers;
+    PromiseMatchers<T>;
 } & BaseExpect &
   AsymmetricMatchers &
   Inverse<Omit<AsymmetricMatchers, 'any' | 'anything'>>;
@@ -118,7 +118,7 @@ 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.
@@ -128,10 +128,11 @@ type PromiseMatchers = {
    * 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>, Awaited<T>> &
+    Inverse<Matchers<Promise<void>>>;
 };
 
-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.
    */
@@ -152,7 +153,7 @@ export interface Matchers<R extends void | Promise<void>> {
    * Checks that a value is what you expect. It calls `Object.is` to compare values.
    * Don't use `toBe` with floating-point numbers.
    */
-  toBe(expected: unknown): R;
+  toBe(expected: T): R;
   /**
    * Ensures that a mock function is called.
    */

packages/jest-expect/src/types.ts

@@ -29,22 +29,24 @@ type Inverse<Matchers> = {
   not: Matchers;
 };
 
-type JestMatchers<R extends void | Promise<void>, T> = Matchers<R> &
+type JestMatchers<R extends void | Promise<void>, T = unknown> = Matchers<
+  R,
+  T
+> &
   SnapshotMatchers<R, T>;
 
 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: JestMatchers<Promise<void>, T> &
-    Inverse<JestMatchers<Promise<void>, T>>;
+  rejects: JestMatchers<Promise<void>> & Inverse<JestMatchers<Promise<void>>>;
   /**
    * Unwraps the value of a fulfilled promise so any other matcher can be chained.
    * If the promise is rejected the assertion fails.
    */
-  resolves: JestMatchers<Promise<void>, T> &
-    Inverse<JestMatchers<Promise<void>, T>>;
+  resolves: JestMatchers<Promise<void>, Awaited<T>> &
+    Inverse<JestMatchers<Promise<void>>>;
 };
 
 declare module 'expect' {

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

@@ -221,6 +221,11 @@ expectType<void>(
   ),
 );
 
+expectType<void>(
+  expect({name: 'someName', age: 12}).toBe({name: 'someOtherName', age: 13}),
+);
+expectError(expect({name: 'someName', age: 12}).toBe({name: 'someOtherName'}));
+
 expectType<void>(expect(jest.fn()).toHaveBeenCalledWith());
 expectType<void>(expect(jest.fn()).toHaveBeenCalledWith(123));
 expectType<void>(expect(jest.fn()).toHaveBeenCalledWith(123, 'value'));
@@ -473,6 +478,7 @@ declare module 'expect' {
   interface AsymmetricMatchers {
     toBeWithinRange(floor: number, ceiling: number): void;
   }
+
   interface Matchers<R> {
     toBeWithinRange(floor: number, ceiling: number): R;
   }