Improve error message when Promise is passed into jest-dom matcher

.changeset/gentle-colts-pretend.md

@@ -0,0 +1,5 @@
+---
+'pleasantest': patch
+---
+
+Improve error message when Promise is passed into jest-dom matcher

src/extend-expect.ts

@@ -1,7 +1,7 @@
 import type { ElementHandle, JSHandle } from 'puppeteer';
 import { createClientRuntimeServer } from './module-server/client-runtime-server';
 import { deserialize, serialize } from './serialize';
-import { jsHandleToArray, removeFuncFromStackTrace } from './utils';
+import { isPromise, jsHandleToArray, removeFuncFromStackTrace } from './utils';
 
 const methods = [
   'toBeInTheDOM',
@@ -45,7 +45,11 @@ expect.extend(
         ...matcherArgs: unknown[]
       ) {
         const serverPromise = createClientRuntimeServer();
-        if (typeof elementHandle !== 'object' || !elementHandle?.asElement()) {
+        if (
+          typeof elementHandle !== 'object' ||
+          // eslint-disable-next-line @cloudfour/typescript-eslint/no-unnecessary-condition
+          !elementHandle?.asElement?.()
+        ) {
           // Special case: expect(null).not.toBeInTheDocument() should pass
           if (methodName === 'toBeInTheDocument' && this.isNot) {
             // This is actually passing but since it is isNot it has to return false
@@ -62,11 +66,15 @@ expect.extend(
             `${this.utils.RECEIVED_COLOR(
               'received',
             )} value must be an HTMLElement or an SVGElement.`,
-            this.utils.printWithType(
-              'Received',
-              elementHandle,
-              this.utils.printReceived,
-            ),
+            isPromise(elementHandle)
+              ? `Received a ${this.utils.RECEIVED_COLOR(
+                  'Promise',
+                )}. Did you forget to await?`
+              : this.utils.printWithType(
+                  'Received',
+                  elementHandle,
+                  this.utils.printReceived,
+                ),
           ].join('\n');
           const error = new Error(message);
 

src/utils.ts

@@ -15,6 +15,10 @@ export const jsHandleToArray = async (arrayHandle: JSHandle) => {
   return arr;
 };
 
+export const isPromise = <T extends any>(
+  input: unknown | Promise<T>,
+): input is Promise<T> => Promise.resolve(input) === input; // https://stackoverflow.com/questions/27746304/how-do-i-tell-if-an-object-is-a-promise/38339199#38339199
+
 export const assertElementHandle: (
   input: unknown,
   fn: (...params: any[]) => any,
@@ -25,11 +29,7 @@ export const assertElementHandle: (
   messageStart = `element must be an ElementHandle\n\n`,
 ) => {
   const type =
-    input === null
-      ? 'null'
-      : typeof input === 'object' && Promise.resolve(input) === input // https://stackoverflow.com/questions/27746304/how-do-i-tell-if-an-object-is-a-promise/38339199#38339199
-      ? 'Promise'
-      : typeof input;
+    input === null ? 'null' : isPromise(input) ? 'Promise' : typeof input;
 
   if (type === 'Promise') {
     throw removeFuncFromStackTrace(

tests/extend-expect.test.ts

@@ -0,0 +1,42 @@
+// The matcher test files cover most of the functionality.
+// This file checks behavior that is common to all matchers
+
+import { withBrowser } from 'pleasantest';
+
+test(
+  'throws useful error if Promise is passed',
+  withBrowser(async ({ screen, utils }) => {
+    await utils.injectHTML('<h1>Hi</h1>');
+    await expect(expect(screen.getByText('Hi')).toBeVisible()).rejects
+      .toThrowErrorMatchingInlineSnapshot(`
+                  "expect(received).toBeVisible()
+
+                  received value must be an HTMLElement or an SVGElement.
+                  Received a Promise. Did you forget to await?"
+              `);
+    // This short delay is necessary to make sure that the screen.getByText finishes before the test finishes
+    // Otherwise, the forgot await error is triggered
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }),
+);
+
+test(
+  'throws useful error if non-ElementHandle is passed',
+  withBrowser(async () => {
+    await expect(expect(null).toBeVisible()).rejects
+      .toThrowErrorMatchingInlineSnapshot(`
+                  "expect(received).toBeVisible()
+
+                  received value must be an HTMLElement or an SVGElement.
+                  Received has value: null"
+              `);
+    await expect(expect({}).toBeVisible()).rejects
+      .toThrowErrorMatchingInlineSnapshot(`
+            "expect(received).toBeVisible()
+
+            received value must be an HTMLElement or an SVGElement.
+            Received has type:  object
+            Received has value: {}"
+          `);
+  }),
+);