feat: Pretty print argument diffs in UnexpectedCall error messages

Author: NiGhTTraX

package.json

@@ -31,6 +31,7 @@
     "test": "jest --coverage --config tests/jest.config.js"
   },
   "dependencies": {
+    "jest-diff": "~29.4.3",
     "jest-matcher-utils": "~29.7.0",
     "lodash": "~4.17.0"
   },

pnpm-lock.yaml

@@ -1,4 +1,3 @@
-/* eslint-disable class-methods-use-this */
 import { expectAnsilessContain, expectAnsilessEqual } from '../tests/ansiless';
 import { SM } from '../tests/old';
 import {
@@ -14,7 +13,9 @@ import {
   spyExpectationFactory,
   SpyPendingExpectation,
 } from './expectation/expectation.mocks';
+import { It } from './expectation/it';
 import type { CallMap } from './expectation/repository/expectation-repository';
+import { StrongExpectation } from './expectation/strong-expectation';
 import type { ConcreteMatcher } from './mock/options';
 import { PendingExpectationWithFactory } from './when/pending-expectation';
 
@@ -117,29 +118,45 @@ foobar`
   });
 
   describe('UnexpectedCall', () => {
-    it('should print the property and the existing expectations', () => {
-      const e1 = SM.mock<Expectation>();
-      const e2 = SM.mock<Expectation>();
-      SM.when(e1.toJSON()).thenReturn('e1');
-      SM.when(e2.toJSON()).thenReturn('e2');
-
-      const error = new UnexpectedCall(
-        'bar',
-        [1, 2, 3],
-        [SM.instance(e1), SM.instance(e2)]
-      );
+    it('should print the call', () => {
+      const error = new UnexpectedCall('bar', [1, 2, 3], []);
 
       expectAnsilessContain(
         error.message,
         `Didn't expect mock.bar(1, 2, 3) to be called.`
       );
+    });
 
-      expectAnsilessContain(
-        error.message,
-        `Remaining unmet expectations:
- - e1
- - e2`
-      );
+    it('should print the diff', () => {
+      const matcher = It.matches(() => false, {
+        getDiff: (actual) => ({ actual, expected: 'foo' }),
+      });
+
+      const expectation = new StrongExpectation('bar', [matcher], {
+        value: ':irrelevant:',
+      });
+
+      const error = new UnexpectedCall('bar', [1, 2, 3], [expectation]);
+
+      expectAnsilessContain(error.message, `Expected`);
+    });
+
+    it('should print the diff only for expectations for the same property', () => {
+      const matcher = It.matches(() => false, {
+        getDiff: (actual) => ({ actual, expected: 'foo' }),
+      });
+
+      const e1 = new StrongExpectation('foo', [matcher], {
+        value: ':irrelevant:',
+      });
+      const e2 = new StrongExpectation('bar', [matcher], {
+        value: ':irrelevant:',
+      });
+
+      const error = new UnexpectedCall('foo', [1, 2, 3], [e1, e2]);
+
+      // Yeah, funky way to do a negated ansiless contains.
+      expect(() => expectAnsilessContain(error.message, `bar`)).toThrow();
     });
   });
 

src/errors.spec.ts

@@ -1,7 +1,12 @@
 import { EXPECTED_COLOR } from 'jest-matcher-utils';
 import type { Expectation } from './expectation/expectation';
 import type { CallMap } from './expectation/repository/expectation-repository';
-import { printCall, printProperty, printRemainingExpectations } from './print';
+import {
+  printCall,
+  printDiffForAllExpectations,
+  printProperty,
+  printRemainingExpectations,
+} from './print';
 import type { Property } from './proxy';
 import type { PendingExpectation } from './when/pending-expectation';
 
@@ -43,11 +48,23 @@ export class UnexpectedCall extends Error {
     args: unknown[],
     expectations: Expectation[]
   ) {
-    super(`Didn't expect ${EXPECTED_COLOR(
-      `mock${printCall(property, args)}`
-    )} to be called.
+    const header = `Didn't expect mock${printCall(
+      property,
+      args
+    )} to be called.`;
 
-${printRemainingExpectations(expectations)}`);
+    const propertyExpectations = expectations.filter(
+      (e) => e.property === property
+    );
+
+    if (propertyExpectations.length) {
+      super(`${header}
+
+Remaining expectations:
+${printDiffForAllExpectations(propertyExpectations, args)}`);
+    } else {
+      super(header);
+    }
   }
 }
 

src/errors.ts

@@ -17,6 +17,11 @@ import { isMatcher, MATCHER_SYMBOL } from './matcher';
  * @param toJSON An optional function that should return a string that will be
  *   used when the matcher needs to be printed in an error message. By default,
  *   it stringifies `cb`.
+ * @param getDiff An optional function that will be called when printing the
+ *   diff between a matcher from an expectation and the received arguments. You
+ *   can format both the received and the expected values according to your
+ *   matcher's logic. By default, the `toJSON` method will be used to format
+ *   the expected value, while the received value will be returned as-is.
  *
  * @example
  * const fn = mock<(x: number) => number>();
@@ -27,12 +32,16 @@ import { isMatcher, MATCHER_SYMBOL } from './matcher';
  */
 const matches = <T>(
   cb: (actual: T) => boolean,
-  { toJSON = () => `matches(${cb.toString()})` }: { toJSON?: () => string } = {}
+  {
+    toJSON = () => `matches(${cb.toString()})`,
+    getDiff = (actual) => ({ actual, expected: toJSON() }),
+  }: Partial<Pick<Matcher, 'toJSON' | 'getDiff'>> = {}
 ): TypeMatcher<T> => {
   const matcher: Matcher = {
     [MATCHER_SYMBOL]: true,
-    matches: (arg: T) => cb(arg),
+    matches: (actual: T) => cb(actual),
     toJSON,
+    getDiff,
   };
 
   return matcher as any;
@@ -73,7 +82,10 @@ const deepEquals = <T>(
 
       return isEqual(removeUndefined(actual), removeUndefined(expected));
     },
-    { toJSON: () => printArg(expected) }
+    {
+      toJSON: () => printArg(expected),
+      getDiff: (actual) => ({ actual, expected }),
+    }
   );
 
 /**

src/expectation/it.ts

@@ -509,6 +509,28 @@ describe('It', () => {
         It.matches(() => true, { toJSON: () => 'foobar' }).toJSON()
       ).toEqual('foobar');
     });
+
+    it('should call getDiff if the matcher fails', () => {
+      const matcher = It.matches(() => false, {
+        getDiff: () => ({ actual: 'a', expected: 'e' }),
+      });
+
+      expect(matcher.getDiff(42)).toEqual({ actual: 'a', expected: 'e' });
+    });
+
+    it('should call getDiff if the matcher succeeds', () => {
+      const matcher = It.matches(() => true, {
+        getDiff: () => ({ actual: 'a', expected: 'e' }),
+      });
+
+      expect(matcher.getDiff(42)).toEqual({ actual: 'a', expected: 'e' });
+    });
+
+    it('should use toJSON as the default getDiff', () => {
+      const matcher = It.matches(() => false, { toJSON: () => 'foobar' });
+
+      expect(matcher.getDiff(42)).toEqual({ actual: 42, expected: 'foobar' });
+    });
   });
 
   describe('isObject', () => {

src/expectation/matcher.spec.ts

@@ -1,13 +1,42 @@
 export const MATCHER_SYMBOL = Symbol('matcher');
 
+/**
+ * You should use {@link It.matches} to create this type.
+ */
 export type Matcher = {
   /**
    * Will be called with a value to match against.
    */
-  matches: (arg: any) => boolean;
+  matches: (actual: any) => boolean;
 
   [MATCHER_SYMBOL]: boolean;
 
+  /**
+   * Will be called when printing the diff between an expectation and the
+   * (mismatching) received arguments.
+   *
+   * With this function you can pretty print the `actual` and `expected` values
+   * according to your matcher's logic.
+   *
+   * @param actual The actual value received by this matcher, same as the one
+   *   in `matches`.
+   *
+   * @returns an {actual, expected} pair that will be diffed visually in the
+   *   error message.
+   *
+   * @example
+   * const neverMatcher = It.matches(() => false, {
+   *   getDiff: () => ({ actual: 'something, expected: 'never' })
+   * });
+   * // Will end up printing:
+   * - Expected
+   * + Received
+   *
+   *   - 'something'
+   *   + 'never
+   */
+  getDiff: (actual: any) => { actual: any; expected: any };
+
   /**
    * Used by `pretty-format`.
    */

src/expectation/matcher.ts

@@ -1,8 +1,15 @@
 /* eslint-disable class-methods-use-this */
+import { expectAnsilessContain, expectAnsilessEqual } from '../tests/ansiless';
 import { ApplyProp } from './expectation/expectation';
 import { It } from './expectation/it';
-import { printCall, printProperty, printReturns } from './print';
-import { expectAnsilessContain, expectAnsilessEqual } from '../tests/ansiless';
+import { StrongExpectation } from './expectation/strong-expectation';
+import {
+  printCall,
+  printDiffForAllExpectations,
+  printExpectationDiff,
+  printProperty,
+  printReturns,
+} from './print';
 
 describe('print', () => {
   describe('printProperty', () => {
@@ -105,4 +112,78 @@ describe('print', () => {
       );
     });
   });
+
+  describe('printExpectationDiff', () => {
+    it('should print the diff when we have single expectation', () => {
+      const matcher = It.matches(() => false, {
+        getDiff: (actual) => ({ actual, expected: 'foo' }),
+      });
+
+      const expectation = new StrongExpectation(':irrelevant:', [matcher], {
+        value: ':irrelevant:',
+      });
+
+      const args = ['bar'];
+
+      expectAnsilessEqual(
+        printExpectationDiff(expectation, args),
+        `-   "foo",
++   "bar"`
+      );
+    });
+    it('should print the diff for an expectation with no received args', () => {
+      const matcher = It.matches(() => false, {
+        getDiff: (actual) => ({ actual, expected: 'foo' }),
+      });
+
+      const expectation = new StrongExpectation(':irrelevant:', [matcher], {
+        value: ':irrelevant:',
+      });
+
+      expectAnsilessEqual(
+        printExpectationDiff(expectation, []),
+        `-   "foo",
++   undefined`
+      );
+    });
+
+    it('should not print the diff for an expectation with no expected args', () => {
+      const expectation = new StrongExpectation(':irrelevant:', [], {
+        value: ':irrelevant:',
+      });
+
+      expectAnsilessEqual(printExpectationDiff(expectation, [1, 2]), '');
+    });
+  });
+
+  describe('printDiffForAllExpectations', () => {
+    it('should print the diff when we have multiple expectations', () => {
+      const matcher = It.matches(() => false, {
+        getDiff: (actual) => ({ actual, expected: 'foo' }),
+      });
+
+      const expectation = new StrongExpectation(':irrelevant:', [matcher], {
+        value: ':irrelevant:',
+      });
+
+      const args = ['bar'];
+
+      expectAnsilessEqual(
+        printDiffForAllExpectations([expectation, expectation], args),
+        `when(() => mock.:irrelevant:(matches(() => false))).thenReturn(":irrelevant:").between(1, 1)
+- Expected
++ Received
+
+-   "foo",
++   "bar"
+
+when(() => mock.:irrelevant:(matches(() => false))).thenReturn(":irrelevant:").between(1, 1)
+- Expected
++ Received
+
+-   "foo",
++   "bar"`
+      );
+    });
+  });
 });

src/print.spec.ts

@@ -1,4 +1,10 @@
-import { EXPECTED_COLOR, printExpected } from 'jest-matcher-utils';
+import { diff as printDiff } from 'jest-diff';
+import {
+  EXPECTED_COLOR,
+  printExpected,
+  printReceived,
+  RECEIVED_COLOR,
+} from 'jest-matcher-utils';
 import type { Expectation } from './expectation/expectation';
 import { ApplyProp } from './expectation/expectation';
 import { isMatcher } from './expectation/matcher';
@@ -19,7 +25,7 @@ export const printProperty = (property: Property) => {
 
 export const printArg = (arg: unknown): string =>
   // Call toJSON on matchers directly to avoid wrapping them in quotes.
-  isMatcher(arg) ? arg.toJSON() : printExpected(arg);
+  isMatcher(arg) ? arg.toJSON() : printReceived(arg);
 
 export const printCall = (property: Property, args: any[]) => {
   const prettyArgs = args.map((arg) => printArg(arg)).join(', ');
@@ -52,10 +58,10 @@ export const printReturns = (
 
 export const printWhen = (property: Property, args: any[] | undefined) => {
   if (args) {
-    return `when(() => ${EXPECTED_COLOR(`mock${printCall(property, args)}`)})`;
+    return `when(() => mock${printCall(property, args)})`;
   }
 
-  return `when(() => ${EXPECTED_COLOR(`mock${printProperty(property)}`)})`;
+  return `when(() => mock${printProperty(property)})`;
 };
 
 export const printExpectation = (
@@ -71,3 +77,48 @@ export const printRemainingExpectations = (expectations: Expectation[]) =>
     ? `Remaining unmet expectations:
  - ${expectations.map((e) => e.toJSON()).join('\n - ')}`
     : 'There are no remaining unmet expectations.';
+
+export const printExpectationDiff = (e: Expectation, args: any[]) => {
+  if (!e.args?.length) {
+    return '';
+  }
+
+  const matcherDiffs = e.args?.map((matcher, j) => matcher.getDiff(args[j]));
+
+  const diff = printDiff(
+    matcherDiffs?.map((d) => d.expected),
+    matcherDiffs?.map((d) => d.actual),
+    { omitAnnotationLines: true }
+  );
+
+  if (!diff) {
+    return '';
+  }
+
+  const diffLines = diff.split('\n').slice(1, -1);
+
+  return `${diffLines.slice(0, -1).join('\n')}\n${diffLines[
+    diffLines.length - 1
+  ].slice(0, -6)}`;
+};
+
+export const printDiffForAllExpectations = (
+  expectations: Expectation[],
+  actual: any[]
+) =>
+  expectations
+    .map((e) => {
+      const diff = printExpectationDiff(e, actual);
+
+      if (diff) {
+        return `${e.toJSON()}
+${EXPECTED_COLOR('- Expected')}
+${RECEIVED_COLOR('+ Received')}
+
+${diff}`;
+      }
+
+      return undefined;
+    })
+    .filter((x) => x)
+    .join('\n\n');