feat: add expect.addEqualityTesters API

docs/api/expect.md

@@ -1407,3 +1407,84 @@ Don't forget to include the ambient declaration file in your `tsconfig.json`.
 :::tip
 If you want to know more, checkout [guide on extending matchers](/guide/extending-matchers).
 :::
+
+## expect.addEqualityTesters
+
+- **Type:** `(tester: Array<Tester>) => void`
+- **Version:** Since Vitest 1.0.0
+
+You can use this method to define custom matcher to test if two object equals or not. And this function is compatible with Jest's `expect.extend`, so any library that uses it to create custom matchers will work with Vitest.
+
+```ts
+class Duration {
+  public time: number
+  public unit: 'H' | 'M' | 'S'
+
+  constructor(time: number, unit: 'H' | 'M' | 'S') {
+    this.time = time
+    this.unit = unit
+  }
+
+  toString(): string {
+    return `[Duration: ${this.time.toString()}${this.unit}]`
+  }
+
+  equals(other: Duration): boolean {
+    if (this.unit === other.unit)
+      return this.time === other.time
+
+    else if (
+      (this.unit === 'H' && other.unit === 'M')
+        || (this.unit === 'M' && other.unit === 'S')
+    )
+      return (this.time * 60) === other.time
+
+    else if (
+      (other.unit === 'H' && this.unit === 'M')
+        || (other.unit === 'M' && this.unit === 'S')
+    )
+      return (other.time * 60) === this.time
+
+    return (this.time * 60 * 60) === other.time
+  }
+}
+```
+
+```ts
+function isDurationMatch(a: Duration, b: Duration) {
+  const isDurationA = a instanceof Duration
+  const isDurationB = b instanceof Duration
+
+  if (isDurationA && isDurationB)
+    return a.equals(b)
+
+  else if (isDurationA === isDurationB)
+    return undefined
+
+  return false
+}
+
+expect.addEqualityTesters([isDurationMatch])
+```
+
+```ts
+it('basic test case', () => {
+  expect(new Duration(1, 'H')).toEqual(new Duration(3600, 'S'))
+})
+```
+
+For custom matchers function, you can combine it with `expect.extend`, For example:
+
+```ts
+expect.extend({
+  toEqualDuration(received: Duration, expected: Duration) {
+    const result = this.equals(received, expected, this.customTesters)
+    return {
+      message: () => `Expected object: ${received.toString()}. But expectedly got: ${expected.toString()}`,
+      pass: result,
+    }
+  },
+})
+
+expect(new Duration(1, 'H')).toEqualDuration(new Duration(3600, 'S'))
+```

examples/vitesse/src/auto-import.d.ts

@@ -61,5 +61,5 @@ declare global {
 // for type re-export
 declare global {
   // @ts-ignore
-  export type { Component, ComponentPublicInstance, ComputedRef, InjectionKey, PropType, Ref, VNode } from 'vue'
+  export type { Component, ComponentPublicInstance, ComputedRef, ExtractDefaultPropTypes, ExtractPropTypes, ExtractPublicPropTypes, InjectionKey, PropType, Ref, VNode, WritableComputedRef } from 'vue'
 }

packages/expect/src/index.ts

@@ -2,7 +2,7 @@ export * from './jest-asymmetric-matchers'
 export * from './jest-utils'
 export * from './constants'
 export * from './types'
-export { getState, setState } from './state'
+export { getState, setState, addCustomEqualityTesters } from './state'
 export { JestChaiExpect } from './jest-expect'
 export { JestExtend } from './jest-extend'
 export { setupColors } from '@vitest/utils'

packages/expect/src/jest-asymmetric-matchers.ts

@@ -1,6 +1,6 @@
 import type { ChaiPlugin, MatcherState } from './types'
 import { GLOBAL_EXPECT } from './constants'
-import { getState } from './state'
+import { getCustomEqualityTesters, getState } from './state'
 import { diff, getMatcherUtils, stringify } from './jest-matcher-utils'
 
 import { equals, isA, iterableEquality, pluralize, subsetEquality } from './jest-utils'
@@ -26,7 +26,7 @@ export abstract class AsymmetricMatcher<
       ...getState(expect || (globalThis as any)[GLOBAL_EXPECT]),
       equals,
       isNot: this.inverse,
-      customTesters: [],
+      customTesters: getCustomEqualityTesters(),
       utils: {
         ...getMatcherUtils(),
         diff,

packages/expect/src/jest-expect.ts

@@ -9,6 +9,7 @@ import type { AsymmetricMatcher } from './jest-asymmetric-matchers'
 import { diff, stringify } from './jest-matcher-utils'
 import { JEST_MATCHERS_OBJECT } from './constants'
 import { recordAsyncExpect, wrapSoft } from './utils'
+import { getCustomEqualityTesters } from './state'
 
 // polyfill globals because expect can be used in node environment
 declare class Node {
@@ -80,7 +81,7 @@ export const JestChaiExpect: ChaiPlugin = (chai, utils) => {
     const equal = jestEquals(
       actual,
       expected,
-      [iterableEquality],
+      [...getCustomEqualityTesters(), iterableEquality],
     )
 
     return this.assert(
@@ -98,6 +99,7 @@ export const JestChaiExpect: ChaiPlugin = (chai, utils) => {
       obj,
       expected,
       [
+        ...getCustomEqualityTesters(),
         iterableEquality,
         typeEquality,
         sparseArrayEquality,
@@ -125,6 +127,7 @@ export const JestChaiExpect: ChaiPlugin = (chai, utils) => {
         actual,
         expected,
         [
+          ...getCustomEqualityTesters(),
           iterableEquality,
           typeEquality,
           sparseArrayEquality,
@@ -140,7 +143,7 @@ export const JestChaiExpect: ChaiPlugin = (chai, utils) => {
         const toEqualPass = jestEquals(
           actual,
           expected,
-          [iterableEquality],
+          [...getCustomEqualityTesters(), iterableEquality],
         )
 
         if (toEqualPass)
@@ -159,7 +162,7 @@ export const JestChaiExpect: ChaiPlugin = (chai, utils) => {
   def('toMatchObject', function (expected) {
     const actual = this._obj
     return this.assert(
-      jestEquals(actual, expected, [iterableEquality, subsetEquality]),
+      jestEquals(actual, expected, [...getCustomEqualityTesters(), iterableEquality, subsetEquality]),
       'expected #{this} to match object #{exp}',
       'expected #{this} to not match object #{exp}',
       expected,
@@ -208,7 +211,7 @@ export const JestChaiExpect: ChaiPlugin = (chai, utils) => {
   def('toContainEqual', function (expected) {
     const obj = utils.flag(this, 'object')
     const index = Array.from(obj).findIndex((item) => {
-      return jestEquals(item, expected)
+      return jestEquals(item, expected, [...getCustomEqualityTesters(), iterableEquality])
     })
 
     this.assert(

packages/expect/src/jest-extend.ts

@@ -8,7 +8,7 @@ import type {
 } from './types'
 import { ASYMMETRIC_MATCHERS_OBJECT, JEST_MATCHERS_OBJECT } from './constants'
 import { AsymmetricMatcher } from './jest-asymmetric-matchers'
-import { getState } from './state'
+import { getCustomEqualityTesters, getState } from './state'
 
 import { diff, getMatcherUtils, stringify } from './jest-matcher-utils'
 
@@ -33,8 +33,7 @@ function getMatcherState(assertion: Chai.AssertionStatic & Chai.Assertion, expec
 
   const matcherState: MatcherState = {
     ...getState(expect),
-    // TODO: implement via expect.addEqualityTesters
-    customTesters: [],
+    customTesters: getCustomEqualityTesters(),
     isNot,
     utils: jestUtils,
     promise,

packages/expect/src/jest-utils.ts

@@ -298,7 +298,13 @@ function hasIterator(object: any) {
   return !!(object != null && object[IteratorSymbol])
 }
 
-export function iterableEquality(a: any, b: any, aStack: Array<any> = [], bStack: Array<any> = []): boolean | undefined {
+export function iterableEquality(
+  a: any,
+  b: any,
+  customTesters: Array<Tester> = [],
+  aStack: Array<any> = [],
+  bStack: Array<any> = [],
+): boolean | undefined {
   if (
     typeof a !== 'object'
     || typeof b !== 'object'
@@ -324,7 +330,20 @@ export function iterableEquality(a: any, b: any, aStack: Array<any> = [], bStack
   aStack.push(a)
   bStack.push(b)
 
-  const iterableEqualityWithStack = (a: any, b: any) => iterableEquality(a, b, [...aStack], [...bStack])
+  const filteredCustomTesters: Array<Tester> = [
+    ...customTesters.filter(t => t !== iterableEquality),
+    iterableEqualityWithStack,
+  ]
+
+  function iterableEqualityWithStack(a: any, b: any) {
+    return iterableEquality(
+      a,
+      b,
+      [...filteredCustomTesters],
+      [...aStack],
+      [...bStack],
+    )
+  }
 
   if (a.size !== undefined) {
     if (a.size !== b.size) {
@@ -336,7 +355,7 @@ export function iterableEquality(a: any, b: any, aStack: Array<any> = [], bStack
         if (!b.has(aValue)) {
           let has = false
           for (const bValue of b) {
-            const isEqual = equals(aValue, bValue, [iterableEqualityWithStack])
+            const isEqual = equals(aValue, bValue, filteredCustomTesters)
             if (isEqual === true)
               has = true
           }
@@ -357,20 +376,16 @@ export function iterableEquality(a: any, b: any, aStack: Array<any> = [], bStack
       for (const aEntry of a) {
         if (
           !b.has(aEntry[0])
-          || !equals(aEntry[1], b.get(aEntry[0]), [iterableEqualityWithStack])
+          || !equals(aEntry[1], b.get(aEntry[0]), filteredCustomTesters)
         ) {
           let has = false
           for (const bEntry of b) {
-            const matchedKey = equals(aEntry[0], bEntry[0], [
-              iterableEqualityWithStack,
-            ])
+            const matchedKey = equals(aEntry[0], bEntry[0], filteredCustomTesters)
 
             let matchedValue = false
-            if (matchedKey === true) {
-              matchedValue = equals(aEntry[1], bEntry[1], [
-                iterableEqualityWithStack,
-              ])
-            }
+            if (matchedKey === true)
+              matchedValue = equals(aEntry[1], bEntry[1], filteredCustomTesters)
+
             if (matchedValue === true)
               has = true
           }
@@ -394,7 +409,7 @@ export function iterableEquality(a: any, b: any, aStack: Array<any> = [], bStack
     const nextB = bIterator.next()
     if (
       nextB.done
-      || !equals(aValue, nextB.value, [iterableEqualityWithStack])
+      || !equals(aValue, nextB.value, filteredCustomTesters)
     )
       return false
   }
@@ -430,7 +445,13 @@ function isObjectWithKeys(a: any) {
   && !(a instanceof Date)
 }
 
-export function subsetEquality(object: unknown, subset: unknown): boolean | undefined {
+export function subsetEquality(
+  object: unknown,
+  subset: unknown,
+  customTesters: Array<Tester> = [],
+): boolean | undefined {
+  const filteredCustomTesters = customTesters.filter(t => t !== subsetEquality)
+
   // subsetEquality needs to keep track of the references
   // it has already visited to avoid infinite loops in case
   // there are circular references in the subset passed to it.
@@ -443,15 +464,15 @@ export function subsetEquality(object: unknown, subset: unknown): boolean | unde
         return Object.keys(subset).every((key) => {
           if (isObjectWithKeys(subset[key])) {
             if (seenReferences.has(subset[key]))
-              return equals(object[key], subset[key], [iterableEquality])
+              return equals(object[key], subset[key], filteredCustomTesters)
 
             seenReferences.set(subset[key], true)
           }
           const result
             = object != null
             && hasPropertyInObject(object, key)
             && equals(object[key], subset[key], [
-              iterableEquality,
+              ...filteredCustomTesters,
               subsetEqualityWithContext(seenReferences),
             ])
           // The main goal of using seenReference is to avoid circular node on tree.

packages/expect/src/state.ts

@@ -1,4 +1,5 @@
-import type { ExpectStatic, MatcherState } from './types'
+import { getType } from '@vitest/utils'
+import type { ExpectStatic, MatcherState, Tester } from './types'
 import { ASYMMETRIC_MATCHERS_OBJECT, GLOBAL_EXPECT, JEST_MATCHERS_OBJECT, MATCHERS_OBJECT } from './constants'
 
 if (!Object.prototype.hasOwnProperty.call(globalThis, MATCHERS_OBJECT)) {
@@ -33,3 +34,18 @@ export function setState<State extends MatcherState = MatcherState>(
   Object.assign(current, state)
   map.set(expect, current)
 }
+
+export function getCustomEqualityTesters(): Array<Tester> {
+  const { customTesters } = getState((globalThis as any)[GLOBAL_EXPECT])
+  return customTesters || []
+}
+
+export function addCustomEqualityTesters(testers: Array<Tester>): void {
+  if (!Array.isArray(testers)) {
+    throw new TypeError(
+      `expect.customEqualityTesters should receive array type, but got: ${getType(testers)}`,
+    )
+  }
+
+  setState({ customTesters: [...testers] }, (globalThis as any)[GLOBAL_EXPECT])
+}

packages/expect/src/types.ts

@@ -88,6 +88,7 @@ export interface ExpectStatic extends Chai.ExpectStatic, AsymmetricMatchersConta
   getState(): MatcherState
   setState(state: Partial<MatcherState>): void
   not: AsymmetricMatchersContaining
+  addEqualityTesters(tester: Array<Tester>): void
 }
 
 export interface AsymmetricMatchersContaining {

packages/vitest/src/integrations/chai/index.ts

@@ -4,7 +4,7 @@ import * as chai from 'chai'
 import './setup'
 import type { TaskPopulated, Test } from '@vitest/runner'
 import { getCurrentTest } from '@vitest/runner'
-import { ASYMMETRIC_MATCHERS_OBJECT, GLOBAL_EXPECT, getState, setState } from '@vitest/expect'
+import { ASYMMETRIC_MATCHERS_OBJECT, GLOBAL_EXPECT, addCustomEqualityTesters, getState, setState } from '@vitest/expect'
 import type { Assertion, ExpectStatic } from '@vitest/expect'
 import type { MatcherState } from '../../types/chai'
 import { getFullName } from '../../utils/tasks'
@@ -59,6 +59,8 @@ export function createExpect(test?: TaskPopulated) {
     chai.assert.fail(`expected${message ? ` "${message}" ` : ' '}not to be reached`)
   }
 
+  expect.addEqualityTesters = addCustomEqualityTesters
+
   function assertions(expected: number) {
     const errorGen = () => new Error(`expected number of assertions to be ${expected}, but got ${expect.getState().assertionCalls}`)
     if (Error.captureStackTrace)