[Feature] Add support for custom equality testers

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ### Features
 
+- `[expect, @jest/expect-utils]` Support custom equality testers
 - `[jest-config]` Add colors configuration option [#13624](https://github.com/facebook/jest/pull/13624)
 - `[jest-haste-map]` ignore Sapling vcs directories (`.sl/`) ([#13674](https://github.com/facebook/jest/pull/13674))
 - `[jest-resolve]` Support subpath imports ([#13705](https://github.com/facebook/jest/pull/13705))

packages/expect-utils/src/jasmineUtils.ts

@@ -76,7 +76,7 @@ function eq(
   }
 
   for (let i = 0; i < customTesters.length; i++) {
-    const customTesterResult = customTesters[i](a, b);
+    const customTesterResult = customTesters[i](a, b, customTesters);
     if (customTesterResult !== undefined) {
       return customTesterResult;
     }

packages/expect-utils/src/types.ts

@@ -6,4 +6,8 @@
  *
  */
 
-export type Tester = (a: any, b: any) => boolean | undefined;
+export type Tester = (
+  a: any,
+  b: any,
+  customTesters: Array<Tester>,
+) => boolean | undefined;

packages/expect-utils/src/utils.ts

@@ -16,6 +16,7 @@ import {
   isImmutableUnorderedSet,
 } from './immutableUtils';
 import {equals, isA} from './jasmineUtils';
+import type {Tester} from './types';
 
 type GetPath = {
   hasEndProp?: boolean;
@@ -102,20 +103,27 @@ export const getPath = (
 export const getObjectSubset = (
   object: any,
   subset: any,
+  customTesters: Array<Tester> = [],
   seenReferences: WeakMap<object, boolean> = new WeakMap(),
 ): any => {
   /* eslint-enable @typescript-eslint/explicit-module-boundary-types */
   if (Array.isArray(object)) {
     if (Array.isArray(subset) && subset.length === object.length) {
       // The map method returns correct subclass of subset.
       return subset.map((sub: any, i: number) =>
-        getObjectSubset(object[i], sub),
+        getObjectSubset(object[i], sub, customTesters),
       );
     }
   } else if (object instanceof Date) {
     return object;
   } else if (isObject(object) && isObject(subset)) {
-    if (equals(object, subset, [iterableEquality, subsetEquality])) {
+    if (
+      equals(object, subset, [
+        ...customTesters,
+        iterableEquality,
+        subsetEquality,
+      ])
+    ) {
       // Avoid unnecessary copy which might return Object instead of subclass.
       return subset;
     }
@@ -128,7 +136,12 @@ export const getObjectSubset = (
       .forEach(key => {
         trimmed[key] = seenReferences.has(object[key])
           ? seenReferences.get(object[key])
-          : getObjectSubset(object[key], subset[key], seenReferences);
+          : getObjectSubset(
+              object[key],
+              subset[key],
+              customTesters,
+              seenReferences,
+            );
       });
 
     if (Object.keys(trimmed).length > 0) {
@@ -147,6 +160,7 @@ const hasIterator = (object: any) =>
 export const iterableEquality = (
   a: any,
   b: any,
+  customTesters: Array<Tester> = [],
   /* eslint-enable @typescript-eslint/explicit-module-boundary-types */
   aStack: Array<any> = [],
   bStack: Array<any> = [],
@@ -177,8 +191,23 @@ export const iterableEquality = (
   aStack.push(a);
   bStack.push(b);
 
+  // eslint-disable-next-line prefer-const
+  let filteredCustomTesters: Array<Tester>;
   const iterableEqualityWithStack = (a: any, b: any) =>
-    iterableEquality(a, b, [...aStack], [...bStack]);
+    iterableEquality(
+      a,
+      b,
+      [...filteredCustomTesters],
+      [...aStack],
+      [...bStack],
+    );
+
+  // Replace any instance of iterableEquality with the new
+  // iterableEqualityWithStack so we can do circular detection
+  filteredCustomTesters = [
+    ...customTesters.filter(t => t !== iterableEquality),
+    iterableEqualityWithStack,
+  ];
 
   if (a.size !== undefined) {
     if (a.size !== b.size) {
@@ -189,7 +218,7 @@ export const iterableEquality = (
         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;
             }
@@ -213,19 +242,23 @@ export const iterableEquality = (
       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,
-              ]);
+              matchedValue = equals(
+                aEntry[1],
+                bEntry[1],
+                filteredCustomTesters,
+              );
             }
             if (matchedValue === true) {
               has = true;
@@ -249,10 +282,7 @@ export const iterableEquality = (
 
   for (const aValue of a) {
     const nextB = bIterator.next();
-    if (
-      nextB.done ||
-      !equals(aValue, nextB.value, [iterableEqualityWithStack])
-    ) {
+    if (nextB.done || !equals(aValue, nextB.value, filteredCustomTesters)) {
       return false;
     }
   }
@@ -290,7 +320,10 @@ const isObjectWithKeys = (a: any) =>
 export const 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.
@@ -304,15 +337,15 @@ export const subsetEquality = (
       return Reflect.ownKeys(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.
@@ -366,6 +399,7 @@ export const arrayBufferEquality = (
 export const sparseArrayEquality = (
   a: unknown,
   b: unknown,
+  customTesters: Array<Tester> = [],
 ): boolean | undefined => {
   if (!Array.isArray(a) || !Array.isArray(b)) {
     return undefined;
@@ -375,7 +409,12 @@ export const sparseArrayEquality = (
   const aKeys = Object.keys(a);
   const bKeys = Object.keys(b);
   return (
-    equals(a, b, [iterableEquality, typeEquality], true) && equals(aKeys, bKeys)
+    equals(
+      a,
+      b,
+      customTesters.filter(t => t !== sparseArrayEquality),
+      true,
+    ) && equals(aKeys, bKeys)
   );
 };
 

packages/expect/__typetests__/expect.test.ts

@@ -48,6 +48,7 @@ expectType<void>(
       expectType<Array<Error>>(this.suppressedErrors);
       expectType<string | undefined>(this.testPath);
       expectType<MatcherUtils>(this.utils);
+      expectType<Array<Tester>>(this.customTesters);
 
       const pass = actual >= floor && actual <= ceiling;
       if (pass) {
@@ -79,6 +80,17 @@ declare module 'expect' {
 expectType<void>(expect(100).toBeWithinRange(90, 110));
 expectType<void>(expect(101).not.toBeWithinRange(0, 100));
 
+expectType<void>(
+  expect.addEqualityTesters([
+    (a, b, customTesters) => {
+      expectType<any>(a);
+      expectType<any>(b);
+      expectType<Array<Tester>>(customTesters);
+      return true;
+    },
+  ]),
+);
+
 expectType<void>(
   expect({apples: 6, bananas: 3}).toEqual({
     apples: expect.toBeWithinRange(1, 10),

packages/expect/src/__tests__/__snapshots__/customEqualityTesters.test.ts.snap

@@ -0,0 +1,17 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`with custom equality testers toMatchObject error shows special objects as equal 1`] = `
+"<dim>expect(</intensity><red>received</color><dim>).</intensity>toMatchObject<dim>(</intensity><green>expected</color><dim>)</intensity>
+
+<green>- Expected  - 1</color>
+<red>+ Received  + 1</color>
+
+<dim>  Object {</intensity>
+<green>-   "a": 2,</color>
+<red>+   "a": 1,</color>
+<dim>    "b": Object {</intensity>
+<dim>      "$$special": Symbol(special test object type),</intensity>
+<dim>      "value": "2",</intensity>
+<dim>    },</intensity>
+<dim>  }</intensity>"
+`;