Improve toEqualText error message

.github/workflows/nodejs.yml

@@ -25,6 +25,10 @@ jobs:
           npx prettier --check .
       - run: npm run build
       - run: npm test
+        env:
+          # Used by chalk. Ensures output from Jest includes ANSI escape
+          # characters that are needed to match test snapshots.
+          FORCE_COLOR: true
       - run: npx codecov
         env:
           CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

src/matchers/tests/utils.ts

@@ -8,3 +8,7 @@ export const testWrapper = (result: SyncExpectationResult) => {
     throw new Error(result.message())
   }
 }
+
+export const assertSnapshot = async (fn: () => Promise<void>) => {
+  await expect(fn).rejects.toThrowErrorMatchingSnapshot()
+}

src/matchers/toEqualText/__snapshots__/index.test.ts.snap

@@ -1,9 +1,30 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
-exports[`toEqualText selector negative 1`] = `"'not-existing' does not equal 'zzzBarzzz' of '#foobar'."`;
+exports[`toEqualText element failure 1`] = `
+"expect(received).toEqualText(expected)
 
-exports[`toEqualText selector positive 1`] = `"'Bar' does equal 'Bar'."`;
+Expected: \\"not-existing\\"
+Received: \\"zzzBarzzz\\""
+`;
 
-exports[`toEqualText selector positive frame 1`] = `"'Example Domain' does equal 'Example Domain'."`;
+exports[`toEqualText page failure 1`] = `
+"expect(received).toEqualText(expected)
+
+Expected: \\"not-existing\\"
+Received: \\"zzzBarzzz\\""
+`;
+
+exports[`toEqualText selector negative 1`] = `
+"expect(received).toEqualText(expected)
+
+Expected: \\"Bar\\"
+Received: \\"zzzBarzzz\\""
+`;
+
+exports[`toEqualText selector not failure 1`] = `
+"expect(received).not.toEqualText(expected)
+
+Expected: not \\"Bar\\""
+`;
 
 exports[`toEqualText selector timeout should throw an error after the timeout exceeds 1`] = `"Error: Timeout exceed for element '#foobar'"`;

src/matchers/toEqualText/index.test.ts

@@ -1,6 +1,7 @@
-import { testWrapper } from "../tests/utils"
-
 import toEqualText from "."
+import { assertSnapshot } from "../tests/utils"
+
+expect.extend({ toEqualText })
 
 describe("toEqualText", () => {
   afterEach(async () => {
@@ -10,71 +11,72 @@ describe("toEqualText", () => {
     it("positive frame", async () => {
       await page.setContent(`<iframe src="https://example.com"></iframe>`)
       const iframe = await page.$("iframe")
-      const result = await toEqualText(iframe!, "h1", "Example Domain")
-      expect(result.pass).toBe(true)
-      expect(result.message()).toMatchSnapshot()
+      await expect(iframe!).toEqualText("h1", "Example Domain")
     })
     it("positive", async () => {
       await page.setContent(`<div id="foobar">Bar</div>`)
-      const result = await toEqualText(page, "#foobar", "Bar")
-      expect(result.pass).toBe(true)
-      expect(result.message()).toMatchSnapshot()
+      await expect(page).toEqualText("#foobar", "Bar")
     })
     it("negative", async () => {
       await page.setContent(`<div id="foobar">zzzBarzzz</div>`)
-      expect(
-        testWrapper(await toEqualText(page, "#foobar", "not-existing"))
-      ).toThrowErrorMatchingSnapshot()
+      await assertSnapshot(() => expect(page).toEqualText("#foobar", "Bar"))
+    })
+    describe("not", () => {
+      it("success in frame", async () => {
+        await page.setContent(`<iframe src="https://example.com"></iframe>`)
+        const iframe = await page.$("iframe")
+        await expect(iframe!).not.toEqualText("h1", "Foo")
+      })
+      it("success", async () => {
+        await page.setContent(`<div id="foobar">Bar</div>`)
+        await expect(page).not.toEqualText("#foobar", "Foo")
+      })
+      it("failure", async () => {
+        await page.setContent(`<div id="foobar">Bar</div>`)
+        await assertSnapshot(() =>
+          expect(page).not.toEqualText("#foobar", "Bar")
+        )
+      })
     })
     describe("timeout", () => {
-      it("positive: should be able to use a custom timeout", async () => {
+      it("success with a custom timeout", async () => {
         setTimeout(async () => {
           await page.setContent(`<div id="foobar">Bar</div>`)
         }, 500)
-        expect(testWrapper(await toEqualText(page, "#foobar", "Bar"))).toBe(
-          true
-        )
+        await expect(page).toEqualText("#foobar", "Bar")
       })
       it("should throw an error after the timeout exceeds", async () => {
         const start = new Date().getTime()
-        expect(
-          testWrapper(
-            await toEqualText(page, "#foobar", "Bar", {
-              timeout: 1 * 1000,
-            })
-          )
-        ).toThrowErrorMatchingSnapshot()
+        await assertSnapshot(() =>
+          expect(page).toEqualText("#foobar", "Bar", { timeout: 1 * 1000 })
+        )
         const duration = new Date().getTime() - start
         expect(duration).toBeLessThan(1500)
       })
     })
   })
   describe("element", () => {
-    it("positive", async () => {
+    it("success", async () => {
       await page.setContent(`<div id="foobar">Bar</div>`)
       const element = await page.$("#foobar")
-      expect(element).not.toBe(null)
-      expect(testWrapper(await toEqualText(element!, "Bar"))).toBe(true)
+      expect(element).not.toBeNull()
+      await expect(element!).toEqualText("Bar")
     })
-    it("negative", async () => {
+    it("failure", async () => {
       await page.setContent(`<div id="foobar">zzzBarzzz</div>`)
       const element = await page.$("#foobar")
-      expect(element).not.toBe(null)
-      expect(
-        testWrapper(await toEqualText(element!, "not-existing"))
-      ).toThrowError()
+      expect(element).not.toBeNull()
+      await assertSnapshot(() => expect(element!).toEqualText("not-existing"))
     })
   })
   describe("page", () => {
-    it("positive", async () => {
+    it("success", async () => {
       await page.setContent(`<body><div>Bar</div></body>`)
-      expect(testWrapper(await toEqualText(page, "Bar"))).toBe(true)
+      await expect(page).toEqualText("Bar")
     })
-    it("negative", async () => {
+    it("failure", async () => {
       await page.setContent(`<body><div>zzzBarzzz</div></body>`)
-      expect(
-        testWrapper(await toEqualText(page, "not-existing"))
-      ).toThrowError()
+      await assertSnapshot(() => expect(page).toEqualText("not-existing"))
     })
   })
 })

src/matchers/toEqualText/index.ts

@@ -1,30 +1,20 @@
 import { SyncExpectationResult } from "expect/build/types"
-import { getElementText, quote, InputArguments } from "../utils"
+import { getElementText, getMessage, InputArguments } from "../utils"
 
-const toEqualText = async (
+const toEqualText: jest.CustomMatcher = async function (
   ...args: InputArguments
-): Promise<SyncExpectationResult> => {
+): Promise<SyncExpectationResult> {
   try {
-    const { elementHandle, selector, expectedValue } = await getElementText(
-      ...args
-    )
+    const { elementHandle, expectedValue } = await getElementText(...args)
     /* istanbul ignore next */
-    const actualTextContent = await elementHandle.evaluate<string | null>(
+    const actualTextContent = await elementHandle.evaluate(
       (el) => el.textContent
     )
-    if (actualTextContent === expectedValue) {
-      return {
-        pass: true,
-        message: () =>
-          `${quote(expectedValue)} does equal ${quote(actualTextContent)}.`,
-      }
-    }
+
     return {
-      pass: false,
+      pass: actualTextContent === expectedValue,
       message: () =>
-        `${quote(expectedValue)} does not equal ${quote(actualTextContent)}${
-          selector ? " of " + quote(selector) + "." : "."
-        }`,
+        getMessage(this, "toEqualText", expectedValue, actualTextContent),
     }
   } catch (err) {
     return {

src/matchers/utils.ts

@@ -113,4 +113,26 @@ export const getElementText = async (
   throw new Error(`Invalid input length: ${args.length}`)
 }
 
-export const quote = (val: string | null) => `'${val}'`
+export const quote = (val: string | null) =>
+  val === null ? "null" : `'${val}'`
+
+export const getMessage = (
+  { isNot, promise, utils }: jest.MatcherContext,
+  matcher: string,
+  expected: string | null,
+  received: string | null
+) => {
+  const matcherHint =
+    utils.matcherHint(matcher, undefined, undefined, { isNot, promise }) +
+    "\n\n"
+
+  if (isNot) {
+    return matcherHint + `Expected: not ${utils.printExpected(expected)}`
+  } else {
+    return (
+      matcherHint +
+      `Expected: ${utils.printExpected(expected)}\n` +
+      `Received: ${utils.printReceived(received)}`
+    )
+  }
+}