fix: custom expect messages for expect.extend matchers

Author: lzl0304

packages/expect/src/jest-extend.ts

@@ -27,6 +27,7 @@ function getMatcherState(
   const obj = assertion._obj
   const isNot = util.flag(assertion, 'negate') as boolean
   const promise = util.flag(assertion, 'promise') || ''
+  const customMessage = util.flag(assertion, 'message') as string | undefined
   const jestUtils = {
     ...getMatcherUtils(),
     diff,
@@ -52,6 +53,7 @@ function getMatcherState(
     state: matcherState,
     isNot,
     obj,
+    customMessage,
   }
 }
 
@@ -73,7 +75,7 @@ function JestExtendPlugin(
           this: Chai.AssertionStatic & Chai.Assertion,
           ...args: any[]
         ) {
-          const { state, isNot, obj } = getMatcherState(this, expect)
+          const { state, isNot, obj, customMessage } = getMatcherState(this, expect)
 
           const result = expectAssertion.call(state, obj, ...args)
 
@@ -85,15 +87,21 @@ function JestExtendPlugin(
             const thenable = result as PromiseLike<SyncExpectationResult>
             return thenable.then(({ pass, message, actual, expected }) => {
               if ((pass && isNot) || (!pass && !isNot)) {
-                throw new JestExtendError(message(), actual, expected)
+                const errorMessage = customMessage != null
+                  ? customMessage
+                  : message()
+                throw new JestExtendError(errorMessage, actual, expected)
               }
             })
           }
 
           const { pass, message, actual, expected } = result as SyncExpectationResult
 
           if ((pass && isNot) || (!pass && !isNot)) {
-            throw new JestExtendError(message(), actual, expected)
+            const errorMessage = customMessage != null
+              ? `${customMessage}: ${message()}`
+              : message()
+            throw new JestExtendError(errorMessage, actual, expected)
           }
         }
 

test/core/test/expect.test.ts

@@ -389,3 +389,39 @@ describe('Temporal equality', () => {
     })
   })
 })
+
+describe('expect with custom message', () => {
+  test('built-in matcher throws custom message on failure', () => {
+    expect(() => expect(1, 'custom message').toBe(2)).toThrow('custom message')
+  })
+
+  test('custom matcher with expect.extend throws custom message on failure', () => {
+    expect.extend({
+      toBeFoo(actual) {
+        const { isNot } = this
+        return {
+          pass: actual === 'foo',
+          message: () => `${actual} is${isNot ? ' not' : ''} foo`,
+        }
+      },
+    })
+    expect(() => (expect('bar', 'custom message') as any).toBeFoo()).toThrow('custom message')
+  })
+
+  test('custom matcher passes with custom message when assertion succeeds', () => {
+    expect.extend({
+      toBeFoo(actual) {
+        const { isNot } = this
+        return {
+          pass: actual === 'foo',
+          message: () => `${actual} is${isNot ? ' not' : ''} foo`,
+        }
+      },
+    })
+    expect(() => (expect('foo', 'custom message') as any).toBeFoo()).not.toThrow()
+  })
+
+  test('empty custom message falls back to default matcher message', () => {
+    expect(() => expect(1, '').toBe(2)).toThrow('expected 1 to be 2 // Object.is equality')
+  })
+})