From 1d5494e2a940e12f780dbd39d76db74b29d4fc29 Mon Sep 17 00:00:00 2001
From: Gareth Jones <Jones258@Gmail.com>
Date: Wed, 6 Nov 2019 10:28:06 +1300
Subject: [PATCH] [@types/jest]: improve definition of MatcherUtils (#40068)

* [@types/jest]: improve definition of MatcherUtils

* Update `equals` types
---
 types/jest/index.d.ts    | 82 ++++++++++++++++++++++++++++++++--------
 types/jest/jest-tests.ts |  8 +---
 2 files changed, 68 insertions(+), 22 deletions(-)

diff --git a/types/jest/index.d.ts b/types/jest/index.d.ts
index 1d7f20226b..009639bd3a 100644
--- a/types/jest/index.d.ts
+++ b/types/jest/index.d.ts
@@ -424,38 +424,90 @@ declare namespace jest {
         each: Each;
     }
 
+    type PrintLabel = (string: string) => string;
+
+    type MatcherHintColor = (arg: string) => string;
+
+    interface MatcherHintOptions {
+        comment?: string;
+        expectedColor?: MatcherHintColor;
+        isDirectExpectCall?: boolean;
+        isNot?: boolean;
+        promise?: string;
+        receivedColor?: MatcherHintColor;
+        secondArgument?: string;
+        secondArgumentColor?: MatcherHintColor;
+    }
+
+    interface ChalkFunction {
+        (text: TemplateStringsArray, ...placeholders: any[]): string;
+        (...text: any[]): string;
+    }
+
+    interface ChalkColorSupport {
+        level: 0 | 1 | 2 | 3;
+        hasBasic: boolean;
+        has256: boolean;
+        has16m: boolean;
+    }
+
+    type MatcherColorFn = ChalkFunction & { supportsColor: ChalkColorSupport };
+
+    type EqualityTester = (a: any, b: any) => boolean | undefined;
+
     interface MatcherUtils {
         readonly isNot: boolean;
         readonly dontThrow: () => void;
         readonly promise: string;
+        readonly assertionCalls: number;
+        readonly expectedAssertionsNumber: number | null;
+        readonly isExpectingAssertions: boolean;
+        readonly suppressedErrors: any[];
+        readonly expand: boolean;
+        readonly testPath: string;
+        readonly currentTestName: string;
         utils: {
-            readonly EXPECTED_COLOR: (text: string) => string;
-            readonly RECEIVED_COLOR: (text: string) => string;
-            diff: typeof import('jest-diff');
-            ensureActualIsNumber(actual: any, matcherName?: string): void;
-            ensureExpectedIsNumber(actual: any, matcherName?: string): void;
-            ensureNoExpected(actual: any, matcherName?: string): void;
-            ensureNumbers(actual: any, expected: any, matcherName?: string): void;
-            /**
-             * get the type of a value with handling of edge cases like `typeof []` and `typeof null`
-             */
-            getType(value: any): string;
+            readonly EXPECTED_COLOR: MatcherColorFn;
+            readonly RECEIVED_COLOR: MatcherColorFn;
+            readonly INVERTED_COLOR: MatcherColorFn;
+            readonly BOLD_WEIGHT: MatcherColorFn;
+            readonly DIM_COLOR: MatcherColorFn;
+            readonly SUGGEST_TO_CONTAIN_EQUAL: string;
+            diff(a: any, b: any, options?: import("jest-diff").DiffOptions): string | null;
+            ensureActualIsNumber(actual: any, matcherName: string, options?: MatcherHintOptions): void;
+            ensureExpectedIsNumber(actual: any, matcherName: string, options?: MatcherHintOptions): void;
+            ensureNoExpected(actual: any, matcherName: string, options?: MatcherHintOptions): void;
+            ensureNumbers(actual: any, expected: any, matcherName: string, options?: MatcherHintOptions): void;
+            ensureExpectedIsNonNegativeInteger(expected: any, matcherName: string, options?: MatcherHintOptions): void;
             matcherHint(
                 matcherName: string,
                 received?: string,
                 expected?: string,
-                options?: { secondArgument?: string; isDirectExpectCall?: boolean }
+                options?: MatcherHintOptions
+            ): string;
+            matcherErrorMessage(
+              hint: string,
+              generic: string,
+              specific: string
             ): string;
             pluralize(word: string, count: number): string;
+            printReceived(object: any): string;
             printExpected(value: any): string;
-            printReceived(value: any): string;
-            printWithType(name: string, received: any, print: (value: any) => string): string;
+            printWithType(name: string, value: any, print: (value: any) => string): string;
             stringify(object: {}, maxDepth?: number): string;
+            highlightTrailingWhitespace(text: string): string;
+
+            printDiffOrStringify(expected: any, received: any, expectedLabel: string, receivedLabel: string, expand: boolean): string;
+
+            getLabelPrinter(...strings: string[]): PrintLabel;
+
+            iterableEquality: EqualityTester;
+            subsetEquality: EqualityTester;
         };
         /**
          *  This is a deep-equality function that will return true if two objects have the same values (recursively).
          */
-        equals(a: any, b: any): boolean;
+        equals(a: any, b: any, customTesters?: EqualityTester[], strictCheck?: boolean): boolean;
         [other: string]: any;
     }
 
diff --git a/types/jest/jest-tests.ts b/types/jest/jest-tests.ts
index 925c841c40..36012808b6 100644
--- a/types/jest/jest-tests.ts
+++ b/types/jest/jest-tests.ts
@@ -725,22 +725,16 @@ expect.extend({
         const expectedColor = this.utils.EXPECTED_COLOR('blue');
         const receivedColor = this.utils.EXPECTED_COLOR('red');
 
-        const diff: string = this.utils.diff({}, {});
+        const diff: string | null = this.utils.diff({}, {});
 
-        this.utils.ensureActualIsNumber({});
         this.utils.ensureActualIsNumber({}, 'matcher');
 
-        this.utils.ensureExpectedIsNumber({});
         this.utils.ensureExpectedIsNumber({}, 'matcher');
 
-        this.utils.ensureNoExpected({});
         this.utils.ensureNoExpected({}, 'matcher');
 
-        this.utils.ensureNumbers({}, {});
         this.utils.ensureNumbers({}, {}, 'matcher');
 
-        const valueType: string = this.utils.getType({});
-
         this.utils.matcherHint('matcher');
         this.utils.matcherHint('matcher', 'received');
         this.utils.matcherHint('matcher', 'received', 'expected');