feat: support async functions in toBe (#15714)

Co-authored-by: Christoph Nakazawa <[email protected]>

Author: notoriousmango

CHANGELOG.md

@@ -2,7 +2,8 @@
 
 ### Features
 
-- `[expect]` Have `Inverse` exportable ([#15704](https://github.com/jestjs/jest/pull/15704))
+- `[expect]` Have `Inverse` exportable ([#15714](https://github.com/jestjs/jest/pull/15714))
+- `[expect]` feat: support `async functions` in `toBe` ([#15704](https://github.com/jestjs/jest/pull/15704))
 - `[jest-snapshot]` Handle line endings in snapshots ([#15708](https://github.com/jestjs/jest/pull/15708))
 
 ## 30.0.3

packages/expect/src/__tests__/__snapshots__/matchers.test.js.snap

@@ -87,7 +87,7 @@ Rejected to value: <r>4</>
 exports[`.resolves fails non-promise value "a" 1`] = `
 <d>expect(</><r>received</><d>).</>resolves<d>.</>toBeDefined<d>()</>
 
-<b>Matcher error</>: <r>received</> value must be a promise
+<b>Matcher error</>: <r>received</> value must be a promise or a function returning a promise
 
 Received has type:  string
 Received has value: <r>"a"</>
@@ -96,7 +96,7 @@ Received has value: <r>"a"</>
 exports[`.resolves fails non-promise value "a" synchronously 1`] = `
 <d>expect(</><r>received</><d>).</>resolves<d>.</>toBeDefined<d>()</>
 
-<b>Matcher error</>: <r>received</> value must be a promise
+<b>Matcher error</>: <r>received</> value must be a promise or a function returning a promise
 
 Received has type:  string
 Received has value: <r>"a"</>
@@ -105,7 +105,7 @@ Received has value: <r>"a"</>
 exports[`.resolves fails non-promise value [1] 1`] = `
 <d>expect(</><r>received</><d>).</>resolves<d>.</>toBeDefined<d>()</>
 
-<b>Matcher error</>: <r>received</> value must be a promise
+<b>Matcher error</>: <r>received</> value must be a promise or a function returning a promise
 
 Received has type:  array
 Received has value: <r>[1]</>
@@ -114,7 +114,7 @@ Received has value: <r>[1]</>
 exports[`.resolves fails non-promise value [1] synchronously 1`] = `
 <d>expect(</><r>received</><d>).</>resolves<d>.</>toBeDefined<d>()</>
 
-<b>Matcher error</>: <r>received</> value must be a promise
+<b>Matcher error</>: <r>received</> value must be a promise or a function returning a promise
 
 Received has type:  array
 Received has value: <r>[1]</>
@@ -123,7 +123,7 @@ Received has value: <r>[1]</>
 exports[`.resolves fails non-promise value [Function anonymous] 1`] = `
 <d>expect(</><r>received</><d>).</>resolves<d>.</>toBeDefined<d>()</>
 
-<b>Matcher error</>: <r>received</> value must be a promise
+<b>Matcher error</>: <r>received</> value must be a promise or a function returning a promise
 
 Received has type:  function
 Received has value: <r>[Function anonymous]</>
@@ -132,7 +132,7 @@ Received has value: <r>[Function anonymous]</>
 exports[`.resolves fails non-promise value [Function anonymous] synchronously 1`] = `
 <d>expect(</><r>received</><d>).</>resolves<d>.</>toBeDefined<d>()</>
 
-<b>Matcher error</>: <r>received</> value must be a promise
+<b>Matcher error</>: <r>received</> value must be a promise or a function returning a promise
 
 Received has type:  function
 Received has value: <r>[Function anonymous]</>
@@ -141,7 +141,7 @@ Received has value: <r>[Function anonymous]</>
 exports[`.resolves fails non-promise value {"a": 1} 1`] = `
 <d>expect(</><r>received</><d>).</>resolves<d>.</>toBeDefined<d>()</>
 
-<b>Matcher error</>: <r>received</> value must be a promise
+<b>Matcher error</>: <r>received</> value must be a promise or a function returning a promise
 
 Received has type:  object
 Received has value: <r>{"a": 1}</>
@@ -150,7 +150,7 @@ Received has value: <r>{"a": 1}</>
 exports[`.resolves fails non-promise value {"a": 1} synchronously 1`] = `
 <d>expect(</><r>received</><d>).</>resolves<d>.</>toBeDefined<d>()</>
 
-<b>Matcher error</>: <r>received</> value must be a promise
+<b>Matcher error</>: <r>received</> value must be a promise or a function returning a promise
 
 Received has type:  object
 Received has value: <r>{"a": 1}</>
@@ -159,7 +159,7 @@ Received has value: <r>{"a": 1}</>
 exports[`.resolves fails non-promise value 4 1`] = `
 <d>expect(</><r>received</><d>).</>resolves<d>.</>not<d>.</>toBeDefined<d>()</>
 
-<b>Matcher error</>: <r>received</> value must be a promise
+<b>Matcher error</>: <r>received</> value must be a promise or a function returning a promise
 
 Received has type:  number
 Received has value: <r>4</>
@@ -168,7 +168,7 @@ Received has value: <r>4</>
 exports[`.resolves fails non-promise value 4 synchronously 1`] = `
 <d>expect(</><r>received</><d>).</>resolves<d>.</>not<d>.</>toBeDefined<d>()</>
 
-<b>Matcher error</>: <r>received</> value must be a promise
+<b>Matcher error</>: <r>received</> value must be a promise or a function returning a promise
 
 Received has type:  number
 Received has value: <r>4</>
@@ -177,23 +177,23 @@ Received has value: <r>4</>
 exports[`.resolves fails non-promise value null 1`] = `
 <d>expect(</><r>received</><d>).</>resolves<d>.</>not<d>.</>toBeDefined<d>()</>
 
-<b>Matcher error</>: <r>received</> value must be a promise
+<b>Matcher error</>: <r>received</> value must be a promise or a function returning a promise
 
 Received has value: <r>null</>
 `;
 
 exports[`.resolves fails non-promise value null synchronously 1`] = `
 <d>expect(</><r>received</><d>).</>resolves<d>.</>not<d>.</>toBeDefined<d>()</>
 
-<b>Matcher error</>: <r>received</> value must be a promise
+<b>Matcher error</>: <r>received</> value must be a promise or a function returning a promise
 
 Received has value: <r>null</>
 `;
 
 exports[`.resolves fails non-promise value true 1`] = `
 <d>expect(</><r>received</><d>).</>resolves<d>.</>not<d>.</>toBeDefined<d>()</>
 
-<b>Matcher error</>: <r>received</> value must be a promise
+<b>Matcher error</>: <r>received</> value must be a promise or a function returning a promise
 
 Received has type:  boolean
 Received has value: <r>true</>
@@ -202,7 +202,7 @@ Received has value: <r>true</>
 exports[`.resolves fails non-promise value true synchronously 1`] = `
 <d>expect(</><r>received</><d>).</>resolves<d>.</>not<d>.</>toBeDefined<d>()</>
 
-<b>Matcher error</>: <r>received</> value must be a promise
+<b>Matcher error</>: <r>received</> value must be a promise or a function returning a promise
 
 Received has type:  boolean
 Received has value: <r>true</>
@@ -211,15 +211,15 @@ Received has value: <r>true</>
 exports[`.resolves fails non-promise value undefined 1`] = `
 <d>expect(</><r>received</><d>).</>resolves<d>.</>not<d>.</>toBeDefined<d>()</>
 
-<b>Matcher error</>: <r>received</> value must be a promise
+<b>Matcher error</>: <r>received</> value must be a promise or a function returning a promise
 
 Received has value: <r>undefined</>
 `;
 
 exports[`.resolves fails non-promise value undefined synchronously 1`] = `
 <d>expect(</><r>received</><d>).</>resolves<d>.</>not<d>.</>toBeDefined<d>()</>
 
-<b>Matcher error</>: <r>received</> value must be a promise
+<b>Matcher error</>: <r>received</> value must be a promise or a function returning a promise
 
 Received has value: <r>undefined</>
 `;

packages/expect/src/__tests__/matchers.test.js

@@ -143,6 +143,13 @@ describe('.resolves', () => {
     ).resolves.toThrow();
   });
 
+  it('should resolve async function to toBe', async () => {
+    async function fn() {
+      return 'Test';
+    }
+    await jestExpect(fn).resolves.toBe('Test');
+  });
+
   for (const value of ['a', [1], () => {}, {a: 1}]) {
     it(`fails non-promise value ${stringify(value)} synchronously`, () => {
       let error;

packages/expect/src/index.ts

@@ -165,7 +165,7 @@ const makeResolveMatcher =
     matcherName: string,
     matcher: RawMatcherFn,
     isNot: boolean,
-    actual: Promise<any>,
+    actual: Promise<any> | (() => Promise<any>),
     outerErr: JestAssertionError,
   ): PromiseMatcherFn =>
   (...args) => {
@@ -174,11 +174,16 @@ const makeResolveMatcher =
       promise: 'resolves',
     };
 
-    if (!isPromise(actual)) {
+    const actualWrapper: Promise<any> =
+      typeof actual === 'function' ? actual() : actual;
+
+    if (!isPromise(actualWrapper)) {
       throw new JestAssertionError(
         matcherUtils.matcherErrorMessage(
           matcherUtils.matcherHint(matcherName, undefined, '', options),
-          `${matcherUtils.RECEIVED_COLOR('received')} value must be a promise`,
+          `${matcherUtils.RECEIVED_COLOR(
+            'received',
+          )} value must be a promise or a function returning a promise`,
           matcherUtils.printWithType(
             'Received',
             actual,
@@ -190,7 +195,7 @@ const makeResolveMatcher =
 
     const innerErr = new JestAssertionError();
 
-    return actual.then(
+    return actualWrapper.then(
       result =>
         makeThrowingMatcher(matcher, isNot, 'resolves', result, innerErr).apply(
           null,