strong-mock 8.0.1 → 9.0.0-beta.0

package/dist/index.js

@@ -1,19 +1,84 @@
 var jestMatcherUtils = require('jest-matcher-utils');
+var jestDiff = require('jest-diff');
+var stripAnsi = require('strip-ansi');
 var lodash = require('lodash');
 
+function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
+
+var stripAnsi__default = /*#__PURE__*/_interopDefaultLegacy(stripAnsi);
+
+/**
+ * Special symbol denoting the call of a function.
+ */
+const ApplyProp = Symbol('apply');
+
 const MATCHER_SYMBOL = Symbol('matcher');
-/**
- * Used to test if an expectation on an argument is a custom matcher.
+/**
+ * Used to test if an expectation is an argument is a custom matcher.
  */
 
 function isMatcher(f) {
   return !!(f && f[MATCHER_SYMBOL]);
 }
-
-/**
- * Special symbol denoting the call of a function.
+const getMatcherDiffs = (matchers, args) => {
+  const matcherDiffs = matchers.map((matcher, i) => matcher.getDiff(args[i]));
+  const actual = matcherDiffs.map(d => d.actual);
+  const expected = matcherDiffs.map(d => d.expected);
+  return {
+    actual,
+    expected
+  };
+};
+/**
+ * Create a custom matcher.
+ *
+ * @param predicate Will receive the actual value and return whether it matches the expectation.
+ * @param options
+ * @param options.toString 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 `predicate`.
+ * @param options.getDiff An optional function that will be called when printing the
+ *   diff for a failed expectation. It will only be called if there's a mismatch
+ *   between the expected and received values i.e. `predicate(actual)` fails.
+ *   By default, the `toString` method will be used to format the expected value,
+ *   while the received value will be returned as-is.
+ *
+ * @example
+ * // Create a matcher for positive numbers.
+ * const fn = mock<(x: number) => number>();
+ * when(() => fn(It.matches(x => x >= 0))).thenReturn(42);
+ *
+ * fn(2) === 42
+ * fn(-1) // throws
  */
-const ApplyProp = Symbol('apply');
+
+const matches = (predicate, options) => {
+  var _options$toString, _options$getDiff;
+
+  // We can't use destructuring with default values because `options` is optional,
+  // so it needs a default value of `{}`, which will come with a native `toString`.
+  const toString = (_options$toString = options == null ? void 0 : options.toString) != null ? _options$toString : () => `Matcher(${predicate.toString()})`;
+  const getDiff = (_options$getDiff = options == null ? void 0 : options.getDiff) != null ? _options$getDiff : actual => ({
+    actual,
+    expected: toString()
+  });
+  const matcher = {
+    [MATCHER_SYMBOL]: true,
+    matches: actual => predicate(actual),
+    toString,
+    getDiff: actual => {
+      if (predicate(actual)) {
+        return {
+          actual,
+          expected: actual
+        };
+      }
+
+      return getDiff(actual);
+    }
+  };
+  return matcher;
+};
 
 const printProperty = property => {
   if (property === ApplyProp) {
@@ -26,12 +91,26 @@ const printProperty = property => {
 
   return `.${property}`;
 };
-const printArg = arg => // Call toJSON on matchers directly to avoid wrapping them in quotes.
-isMatcher(arg) ? arg.toJSON() : jestMatcherUtils.printExpected(arg);
+const printValue = arg => {
+  // Call toString on matchers directly to avoid wrapping strings returned by them in quotes.
+  if (isMatcher(arg)) {
+    return arg.toString();
+  }
+
+  return jestMatcherUtils.stringify(arg);
+};
+
+const printArgs = args => args.map(arg => printValue(arg)).join(', ');
+
 const printCall = (property, args) => {
-  const prettyArgs = args.map(arg => printArg(arg)).join(', ');
   const prettyProperty = printProperty(property);
-  return `${prettyProperty}(${prettyArgs})`;
+
+  if (args) {
+    const prettyArgs = printArgs(args);
+    return `mock${jestMatcherUtils.RECEIVED_COLOR(`${prettyProperty}(${prettyArgs})`)}`;
+  }
+
+  return `mock${jestMatcherUtils.RECEIVED_COLOR(`${prettyProperty}`)}`;
 };
 const printReturns = ({
   isError,
@@ -52,118 +131,141 @@ const printReturns = ({
     thenPrefix += 'thenReturn';
   }
 
-  return `.${thenPrefix}(${jestMatcherUtils.printExpected(value)}).between(${min}, ${max})`;
+  return `.${thenPrefix}(${jestMatcherUtils.RECEIVED_COLOR(printValue(value))}).between(${min}, ${max})`;
 };
 const printWhen = (property, args) => {
+  const prettyProperty = printProperty(property);
+
   if (args) {
-    return `when(() => ${jestMatcherUtils.EXPECTED_COLOR(`mock${printCall(property, args)}`)})`;
+    return `when(() => mock${jestMatcherUtils.EXPECTED_COLOR(`${prettyProperty}(${printArgs(args)})`)})`;
   }
 
-  return `when(() => ${jestMatcherUtils.EXPECTED_COLOR(`mock${printProperty(property)}`)})`;
+  return `when(() => mock${jestMatcherUtils.EXPECTED_COLOR(`${printProperty(property)}`)})`;
 };
 const printExpectation = (property, args, returnValue, min, max) => `${printWhen(property, args)}${printReturns(returnValue, min, max)}`;
 const printRemainingExpectations = expectations => expectations.length ? `Remaining unmet expectations:
- - ${expectations.map(e => e.toJSON()).join('\n - ')}` : 'There are no remaining unmet expectations.';
-
-class UnfinishedExpectation extends Error {
-  constructor(pendingExpectation) {
-    super(`There is an unfinished pending expectation:
-
-${pendingExpectation.toJSON()}
-
-Please finish it by setting a return value even if the value
-is undefined.`);
-  }
+ - ${expectations.map(e => e.toString()).join('\n - ')}` : 'There are no remaining unmet expectations.';
 
-}
-class MissingWhen extends Error {
-  constructor() {
-    super(`You tried setting a return value without an expectation.
-
-Every call to set a return value must be preceded by an expectation.`);
-  }
-
-}
 class UnexpectedAccess extends Error {
   constructor(property, expectations) {
-    super(`Didn't expect ${jestMatcherUtils.EXPECTED_COLOR(`mock${printProperty(property)}`)} to be accessed.
+    super(jestMatcherUtils.DIM_COLOR(`Didn't expect ${printCall(property)} to be accessed.
 
 If you expect this property to be accessed then please
 set an expectation for it.
 
-${printRemainingExpectations(expectations)}`);
+${printRemainingExpectations(expectations)}`));
   }
 
 }
-class UnexpectedCall extends Error {
-  constructor(property, args, expectations) {
-    super(`Didn't expect ${jestMatcherUtils.EXPECTED_COLOR(`mock${printCall(property, args)}`)} to be called.
 
-${printRemainingExpectations(expectations)}`);
+const printArgsDiff = (expected, actual) => {
+  const diff = jestDiff.diff(expected, actual, {
+    omitAnnotationLines: true
+  });
+  /* istanbul ignore next this is not expected in practice */
+
+  if (!diff) {
+    return '';
   }
 
-}
-class NotAMock extends Error {
-  constructor() {
-    super(`We couldn't find the mock.
+  const ansilessDiffLines = stripAnsi__default["default"](diff).split('\n');
+  let relevantDiffLines; // Strip Array [ ... ] surroundings.
+
+  if (!expected.length) {
+    // - Array []
+    // + Array [
+    //   ...
+    // ]
+    relevantDiffLines = ansilessDiffLines.slice(2, -1);
+  } else if (!actual.length) {
+    // - Array [
+    //   ...
+    // ]
+    // + Array []
+    relevantDiffLines = ansilessDiffLines.slice(1, -2);
+  } else {
+    // Array [
+    //   ...
+    // ]
+    relevantDiffLines = ansilessDiffLines.slice(1, -1);
+  } // Strip the trailing comma.
 
-Make sure you're passing in an actual mock.`);
-  }
 
-}
-class UnmetExpectations extends Error {
-  constructor(expectations) {
-    super(`There are unmet expectations:
+  const lastLine = relevantDiffLines[relevantDiffLines.length - 1].slice(0, -1);
+  const coloredDiffLines = [...relevantDiffLines.slice(0, -1), lastLine].map(line => {
+    const first = line.charAt(0);
 
- - ${expectations.map(e => e.toJSON()).join('\n - ')}`);
-  }
+    switch (first) {
+      case '-':
+        return jestMatcherUtils.EXPECTED_COLOR(line);
 
-}
-/**
- * Merge property accesses and method calls for the same property
- * into a single call.
- *
- * @example
- * mergeCalls({ foo: [{ arguments: undefined }, { arguments: [1, 2, 3] }] }
- * // returns { foo: [{ arguments: [1, 2, 3] } }
- */
+      case '+':
+        return jestMatcherUtils.RECEIVED_COLOR(line);
 
-const mergeCalls = callMap => new Map(Array.from(callMap.entries()).map(([property, calls]) => {
-  const hasMethodCalls = calls.some(call => call.arguments);
-  const hasPropertyAccesses = calls.some(call => !call.arguments);
+      default:
+        return line;
+    }
+  });
+  return coloredDiffLines.join('\n');
+};
+const printExpectationDiff = (e, args) => {
+  var _e$args;
 
-  if (hasMethodCalls && hasPropertyAccesses) {
-    return [property, calls.filter(call => call.arguments)];
+  if (!((_e$args = e.args) != null && _e$args.length)) {
+    return '';
   }
 
-  return [property, calls];
-}));
-
-class UnexpectedCalls extends Error {
-  constructor(unexpectedCalls, expectations) {
-    const printedCalls = Array.from(mergeCalls(unexpectedCalls).entries()).map(([property, calls]) => calls.map(call => call.arguments ? jestMatcherUtils.EXPECTED_COLOR(`mock${printCall(property, call.arguments)}`) : jestMatcherUtils.EXPECTED_COLOR(`mock${printProperty(property)}`)).join('\n - ')).join('\n - ');
-    super(`The following calls were unexpected:
+  const {
+    actual,
+    expected
+  } = getMatcherDiffs(e.args, args);
+  return printArgsDiff(expected, actual);
+};
+const printDiffForAllExpectations = (expectations, actual) => expectations.map(e => {
+  const diff = printExpectationDiff(e, actual);
 
- - ${printedCalls}
+  if (diff) {
+    return `${e.toString()}
+${jestMatcherUtils.EXPECTED_COLOR('- Expected')}
+${jestMatcherUtils.RECEIVED_COLOR('+ Received')}
 
-${printRemainingExpectations(expectations)}`);
+${diff}`;
   }
 
-}
-class NestedWhen extends Error {
-  constructor(parentProp, childProp) {
-    const snippet = `
-const parentMock = mock<T1>();
-const childMock = mock<T2>();
+  return undefined;
+}).filter(x => x).join('\n\n');
+class UnexpectedCall extends Error {
+  constructor(property, args, expectations) {
+    const header = `Didn't expect ${printCall(property, args)} to be called.`;
+    const propertyExpectations = expectations.filter(e => e.property === property);
 
-when(() => childMock${printProperty(childProp)}).thenReturn(...);
-when(() => parentMock${printProperty(parentProp)}).thenReturn(childMock)
-`;
-    super(`Setting an expectation on a nested property is not supported.
+    if (propertyExpectations.length) {
+      var _propertyExpectations;
 
-You can return an object directly when the first property is accessed,
-or you can even return a separate mock:
-${snippet}`);
+      super(jestMatcherUtils.DIM_COLOR(`${header}
+
+Remaining expectations:
+${printDiffForAllExpectations(propertyExpectations, args)}`)); // If we have a single expectation we can attach the actual/expected args
+      // to the error instance, so that an IDE may show its own diff for them.
+
+      this.matcherResult = void 0;
+
+      if (propertyExpectations.length === 1 && (_propertyExpectations = propertyExpectations[0].args) != null && _propertyExpectations.length) {
+        const {
+          actual,
+          expected
+        } = getMatcherDiffs(propertyExpectations[0].args, args);
+        this.matcherResult = {
+          actual,
+          expected
+        };
+      }
+    } else {
+      super(jestMatcherUtils.DIM_COLOR(`${header}
+      
+No remaining expectations.`));
+      this.matcherResult = void 0;
+    }
   }
 
 }
@@ -171,49 +273,49 @@ ${snippet}`);
 exports.UnexpectedProperty = void 0;
 
 (function (UnexpectedProperty) {
-  /**
-   * Throw an error immediately.
-   *
-   * @example
-   * // Will throw "Didn't expect foo to be accessed".
-   * const { foo } = service;
-   *
-   * // Will throw "Didn't expect foo to be accessed",
-   * // without printing the arguments.
-   * foo(42);
+  /**
+   * Throw an error immediately.
+   *
+   * @example
+   * // Will throw "Didn't expect foo to be accessed".
+   * const { foo } = service;
+   *
+   * // Will throw "Didn't expect foo to be accessed",
+   * // without printing the arguments.
+   * foo(42);
    */
   UnexpectedProperty[UnexpectedProperty["THROW"] = 0] = "THROW";
-  /**
-   * Return a function that will throw if called. This can be useful if your
-   * code destructures a function but never calls it.
-   *
-   * It will also improve error messages for unexpected calls because arguments
-   * will be captured instead of throwing immediately on the property access.
-   *
-   * The function will be returned even if the property is not supposed to be a
-   * function. This could cause weird behavior at runtime, when your code expects
-   * e.g. a number and gets a function instead.
-   *
-   * @example
-   * // This will NOT throw.
-   * const { foo } = service;
-   *
-   * // This will NOT throw, and might produce unexpected results.
-   * foo > 0
-   *
-   * // Will throw "Didn't expect foo(42) to be called".
-   * foo(42);
+  /**
+   * Return a function that will throw if called. This can be useful if your
+   * code destructures a function but never calls it.
+   *
+   * It will also improve error messages for unexpected calls because arguments
+   * will be captured instead of throwing immediately on the property access.
+   *
+   * The function will be returned even if the property is not supposed to be a
+   * function. This could cause weird behavior at runtime, when your code expects
+   * e.g. a number and gets a function instead.
+   *
+   * @example
+   * // This will NOT throw.
+   * const { foo } = service;
+   *
+   * // This will NOT throw, and might produce unexpected results.
+   * foo > 0
+   *
+   * // Will throw "Didn't expect foo(42) to be called".
+   * foo(42);
    */
 
   UnexpectedProperty[UnexpectedProperty["CALL_THROW"] = 1] = "CALL_THROW";
 })(exports.UnexpectedProperty || (exports.UnexpectedProperty = {}));
 
-/**
- * Unbox the expectation's return value.
- *
- * If the value is an error then throw it.
- *
- * If the value is a promise then resolve/reject it.
+/**
+ * Unbox the expectation's return value.
+ *
+ * If the value is an error then throw it.
+ *
+ * If the value is a promise then resolve/reject it.
  */
 const unboxReturnValue = ({
   isError,
@@ -243,9 +345,9 @@ const unboxReturnValue = ({
   return value;
 };
 
-/**
- * An expectation repository with a configurable behavior for
- * unexpected property access.
+/**
+ * An expectation repository with a configurable behavior for
+ * unexpected property access.
  */
 
 class FlexibleRepository {
@@ -417,16 +519,16 @@ class FlexibleRepository {
 
 }
 
-/**
- * Matches a call with more parameters than expected because it is assumed the
- * compiler will check that those parameters are optional.
- *
- * @example
- * new StrongExpectation(
- *   'bar',
- *   deepEquals([1, 2, 3]),
- *   23
- * ).matches('bar', [1, 2, 3]) === true;
+/**
+ * Matches a call with more parameters than expected because it is assumed the
+ * compiler will check that those parameters are optional.
+ *
+ * @example
+ * new StrongExpectation(
+ *   'bar',
+ *   deepEquals([1, 2, 3]),
+ *   23
+ * ).matches('bar', [1, 2, 3]) === true;
  */
 
 class StrongExpectation {
@@ -480,13 +582,58 @@ class StrongExpectation {
     return this.args.every((arg, i) => arg.matches(received[i]));
   }
 
-  toJSON() {
+  toString() {
     return printExpectation(this.property, this.args, this.returnValue, this.min, this.max);
   }
 
 }
 
-class PendingExpectationWithFactory {
+class UnfinishedExpectation extends Error {
+  constructor(property, args) {
+    super(`There is an unfinished pending expectation:
+
+${printWhen(property, args)}
+
+Please finish it by setting a return value even if the value
+is undefined.`);
+  }
+
+}
+class MissingWhen extends Error {
+  constructor() {
+    super(`You tried setting a return value without an expectation.
+
+Every call to set a return value must be preceded by an expectation.`);
+  }
+
+}
+class NotAMock extends Error {
+  constructor() {
+    super(`We couldn't find the mock.
+
+Make sure you're passing in an actual mock.`);
+  }
+
+}
+class NestedWhen extends Error {
+  constructor(parentProp, childProp) {
+    const snippet = `
+const parentMock = mock<T1>();
+const childMock = mock<T2>();
+
+when(() => childMock${printProperty(childProp)}).thenReturn(...);
+when(() => parentMock${printProperty(parentProp)}).thenReturn(childMock)
+`;
+    super(`Setting an expectation on a nested property is not supported.
+
+You can return an object directly when the first property is accessed,
+or you can even return a separate mock:
+${snippet}`);
+  }
+
+}
+
+class ExpectationBuilderWithFactory {
   constructor(createExpectation, concreteMatcher, exactParams) {
     this.createExpectation = void 0;
     this.concreteMatcher = void 0;
@@ -500,7 +647,7 @@ class PendingExpectationWithFactory {
 
   setProperty(value) {
     if (this.property) {
-      throw new UnfinishedExpectation(this);
+      throw new UnfinishedExpectation(this.property, this.args);
     }
 
     this.property = value;
@@ -521,10 +668,6 @@ class PendingExpectationWithFactory {
     return expectation;
   }
 
-  toJSON() {
-    return printWhen(this.property, this.args);
-  }
-
 }
 
 function _extends() {
@@ -545,33 +688,6 @@ function _extends() {
   return _extends.apply(this, arguments);
 }
 
-/**
- * Match a custom predicate.
- *
- * @param cb Will receive the value and returns whether it matches.
- * @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`.
- *
- * @example
- * const fn = mock<(x: number) => number>();
- * when(() => fn(It.matches(x => x >= 0))).returns(42);
- *
- * fn(2) === 42
- * fn(-1) // throws
- */
-
-const matches = (cb, {
-  toJSON = () => `matches(${cb.toString()})`
-} = {}) => {
-  const matcher = {
-    [MATCHER_SYMBOL]: true,
-    matches: arg => cb(arg),
-    toJSON
-  };
-  return matcher;
-};
-
 const removeUndefined = object => {
   if (Array.isArray(object)) {
     return object.map(x => removeUndefined(x));
@@ -583,16 +699,17 @@ const removeUndefined = object => {
 
   return lodash.omitBy(object, lodash.isUndefined);
 };
-/**
- * Compare values using deep equality.
- *
- * @param expected
- * @param strict By default, this matcher will treat a missing key in an object
- *   and a key with the value `undefined` as not equal. It will also consider
- *   non `Object` instances with different constructors as not equal. Setting
- *   this to `false` will consider the objects in both cases as equal.
- *
- * @see It.is A matcher that uses strict equality.
+/**
+ * Compare values using deep equality.
+ *
+ * @param expected
+ * @param strict By default, this matcher will treat a missing key in an object
+ *   and a key with the value `undefined` as not equal. It will also consider
+ *   non `Object` instances with different constructors as not equal. Setting
+ *   this to `false` will consider the objects in both cases as equal.
+ *
+ * @see {@link It.isObject} or {@link It.isArray} if you want to nest matchers.
+ * @see {@link It.is} if you want to use strict equality.
  */
 
 
@@ -605,244 +722,45 @@ const deepEquals = (expected, {
 
   return lodash.isEqual(removeUndefined(actual), removeUndefined(expected));
 }, {
-  toJSON: () => printArg(expected)
-});
-/**
- * Compare values using `Object.is`.
- *
- * @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is
- *
- * @see It.deepEquals A matcher that uses deep equality.
- */
-
-
-const is = expected => matches(actual => Object.is(actual, expected), {
-  toJSON: () => `${jestMatcherUtils.printExpected(expected)}`
-});
-/**
- * Match any value, including `undefined` and `null`.
- *
- * @example
- * const fn = mock<(x: number, y: string) => number>();
- * when(() => fn(It.isAny(), It.isAny())).thenReturn(1);
- *
- * fn(23, 'foobar') === 1
- */
-
-
-const isAny = () => matches(() => true, {
-  toJSON: () => 'anything'
-});
-/**
- * Recursively match an object.
- *
- * Supports nested matcher.
- *
- * @param partial An optional subset of the expected objected.
- *
- * @example
- * const fn = mock<(foo: { x: number, y: number }) => number>();
- * when(() => fn(It.isObject({ x: 23 }))).returns(42);
- *
- * fn({ x: 100, y: 200 }) // throws
- * fn({ x: 23, y: 200 }) // returns 42
- *
- * @example
- * It.isObject({ foo: It.isString() })
- */
-
-
-const isObject = partial => matches(actual => lodash.isMatchWith(actual, partial || {}, (argValue, partialValue) => {
-  if (isMatcher(partialValue)) {
-    return partialValue.matches(argValue);
-  } // Let lodash handle it otherwise.
-
-
-  return undefined;
-}), {
-  toJSON: () => partial ? `object(${jestMatcherUtils.printExpected(partial)})` : 'object'
-});
-/**
- * Match any number.
- *
- * @example
- * const fn = mock<(x: number) => number>();
- * when(() => fn(It.isNumber())).returns(42);
- *
- * fn(20.5) === 42
- * fn(NaN) // throws
- */
-
-
-const isNumber = () => matches(actual => typeof actual === 'number' && !Number.isNaN(actual), {
-  toJSON: () => 'number'
-});
-/**
- * Match a string, potentially by a pattern.
- *
- * @param matching The string has to match this RegExp.
- * @param containing The string has to contain this substring.
- *
- * @example
- * const fn = mock<(x: string, y: string) => number>();
- * when(() => fn(It.isString(), It.isString({ containing: 'bar' }))).returns(42);
- *
- * fn('foo', 'baz') // throws
- * fn('foo', 'bar') === 42
- */
-
-
-const isString = ({
-  matching,
-  containing
-} = {}) => {
-  if (matching && containing) {
-    throw new Error('You can only pass `matching` or `containing`, not both.');
-  }
-
-  return matches(actual => {
-    var _matching$test;
-
-    if (typeof actual !== 'string') {
-      return false;
-    }
-
-    if (containing) {
-      return actual.indexOf(containing) !== -1;
-    }
-
-    return (_matching$test = matching == null ? void 0 : matching.test(actual)) != null ? _matching$test : true;
-  }, {
-    toJSON: () => containing || matching ? `string(${jestMatcherUtils.printExpected(containing || matching)})` : 'string'
-  });
-};
-/**
- * Match an array.
- *
- * Supports nested matchers.
- *
- * @param containing If given, the matched array has to contain ALL of these
- *   elements in ANY order.
- *
- * @example
- * const fn = mock<(arr: number[]) => number>();
- * when(() => fn(It.isArray())).thenReturn(1);
- * when(() => fn(It.isArray([2, 3]))).thenReturn(2);
- *
- * fn({ length: 1, 0: 42 }) // throws
- * fn([]) === 1
- * fn([3, 2, 1]) === 2
- *
- * @example
- * It.isArray([It.isString({ containing: 'foobar' })])
- */
-
-
-const isArray = containing => matches(actual => {
-  if (!Array.isArray(actual)) {
-    return false;
-  }
-
-  if (!containing) {
-    return true;
-  }
-
-  return containing.every(x => actual.find(y => {
-    if (isMatcher(x)) {
-      return x.matches(y);
-    }
-
-    return deepEquals(x).matches(y);
-  }) !== undefined);
-}, {
-  toJSON: () => containing ? `array(${jestMatcherUtils.printExpected(containing)})` : 'array'
+  toString: () => printValue(expected),
+  getDiff: actual => ({
+    actual,
+    expected
+  })
 });
-/**
- * Matches anything and stores the received value.
- *
- * This should not be needed for most cases, but can be useful if you need
- * access to a complex argument outside the expectation e.g. to test a
- * callback.
- *
- * @param name If given, this name will be printed in error messages.
- *
- * @example
- * const fn = mock<(cb: (value: number) => number) => void>();
- * const matcher = It.willCapture();
- * when(() => fn(matcher)).thenReturn();
- *
- * fn(x => x + 1);
- * matcher.value?.(3) === 4
- */
-
-
-const willCapture = name => {
-  let capturedValue;
-  const matcher = {
-    [MATCHER_SYMBOL]: true,
-    matches: actual => {
-      capturedValue = actual;
-      return true;
-    },
-    toJSON: () => name != null ? name : 'captures',
-
-    get value() {
-      return capturedValue;
-    }
-
-  };
-  return matcher;
-};
-/**
- * Contains argument matchers that can be used to ignore arguments in an
- * expectation or to match complex arguments.
- */
-
-
-const It = {
-  matches,
-  deepEquals,
-  is,
-  isAny,
-  isObject,
-  isNumber,
-  isString,
-  isArray,
-  willCapture
-};
 
 const defaults = {
-  concreteMatcher: It.deepEquals,
+  concreteMatcher: deepEquals,
   unexpectedProperty: exports.UnexpectedProperty.CALL_THROW,
   exactParams: false
 };
 let currentDefaults = defaults;
-/**
- * Override strong-mock's defaults.
- *
- * @param newDefaults These will be applied to the library defaults. Multiple
- *   calls don't stack e.g. calling this with `{}` will clear any previously
- *   applied defaults.
+/**
+ * Override strong-mock's defaults.
+ *
+ * @param newDefaults These will be applied to the library defaults. Multiple
+ *   calls don't stack e.g. calling this with `{}` will clear any previously
+ *   applied defaults.
  */
 
 const setDefaults = newDefaults => {
   currentDefaults = _extends({}, defaults, newDefaults);
 };
 
-/**
- * Since `when` doesn't receive the mock subject (because we can't make it
- * consistently return it from `mock()`, `mock.foo` and `mock.bar()`) we need
- * to store a global state for the currently active mock.
- *
- * We also want to throw in the following case:
- *
- * ```
- * when(() => mock()) // forgot returns here
- * when(() => mock()) // should throw
- * ```
- *
- * For that reason we can't just store the currently active mock, but also
- * whether we finished the expectation or not.
+/**
+ * Since `when` doesn't receive the mock subject (because we can't make it
+ * consistently return it from `mock()`, `mock.foo` and `mock.bar()`) we need
+ * to store a global state for the currently active mock.
+ *
+ * We also want to throw in the following case:
+ *
+ * ```
+ * when(() => mock()) // forgot returns here
+ * when(() => mock()) // should throw
+ * ```
+ *
+ * For that reason we can't just store the currently active mock, but also
+ * whether we finished the expectation or not.
  */
 
 let activeMock;
@@ -850,11 +768,11 @@ const setActiveMock = mock => {
   activeMock = mock;
 };
 const getActiveMock = () => activeMock;
-/**
- * Store a global map of all mocks created and their state.
- *
- * This is needed because we can't reliably pass the state between `when`
- * and `thenReturn`.
+/**
+ * Store a global map of all mocks created and their state.
+ *
+ * This is needed because we can't reliably pass the state between `when`
+ * and `thenReturn`.
  */
 
 const mockMap = new Map();
@@ -870,7 +788,9 @@ const setMockState = (mock, state) => {
 };
 const getAllMocks = () => Array.from(mockMap.entries());
 
-const createProxy = traps => // eslint-disable-next-line no-empty-function
+const createProxy = traps => // The Proxy target MUST be a function, otherwise we can't use the `apply` trap:
+// https://262.ecma-international.org/6.0/#sec-proxy-object-internal-methods-and-internal-slots-call-thisargument-argumentslist
+// eslint-disable-next-line no-empty-function,@typescript-eslint/no-empty-function
 new Proxy(
 /* istanbul ignore next */
 () => {}, {
@@ -907,7 +827,7 @@ new Proxy(
 
 });
 
-const createStub = (repo, pendingExpectation, getCurrentMode) => {
+const createStub = (repo, builder, getCurrentMode) => {
   const stub = createProxy({
     property: property => {
       if (getCurrentMode() === Mode.CALL) {
@@ -915,13 +835,13 @@ const createStub = (repo, pendingExpectation, getCurrentMode) => {
       }
 
       setActiveMock(stub);
-      pendingExpectation.setProperty(property);
+      builder.setProperty(property);
       return createProxy({
         property: childProp => {
           throw new NestedWhen(property, childProp);
         },
         apply: args => {
-          pendingExpectation.setArgs(args);
+          builder.setArgs(args);
         },
         ownKeys: () => {
           throw new Error('Spreading during an expectation is not supported.');
@@ -934,8 +854,8 @@ const createStub = (repo, pendingExpectation, getCurrentMode) => {
       }
 
       setActiveMock(stub);
-      pendingExpectation.setProperty(ApplyProp);
-      pendingExpectation.setArgs(args);
+      builder.setProperty(ApplyProp);
+      builder.setArgs(args);
       return undefined;
     },
     ownKeys: () => {
@@ -965,26 +885,26 @@ const setMode = mode => {
 };
 
 const getMode = () => currentMode;
-/**
- * Create a type safe mock.
- *
- * @see {@link when} Set expectations on the mock using `when`.
- *
- * @param options Configure the options for this specific mock, overriding any
- *   defaults that were set with {@link setDefaults}.
- * @param options.unexpectedProperty Controls what happens when an unexpected
- *   property is accessed.
- * @param options.concreteMatcher The matcher that will be used when one isn't
- *   specified explicitly.
- * @param options.exactParams Controls whether the number of received arguments
- *   has to match the expectation.
- *
- * @example
- * const fn = mock<() => number>();
- *
- * when(() => fn()).thenReturn(23);
- *
- * fn() === 23;
+/**
+ * Create a type safe mock.
+ *
+ * @see {@link when} Set expectations on the mock using `when`.
+ *
+ * @param options Configure the options for this specific mock, overriding any
+ *   defaults that were set with {@link setDefaults}.
+ * @param options.unexpectedProperty Controls what happens when an unexpected
+ *   property is accessed.
+ * @param options.concreteMatcher The matcher that will be used when one isn't
+ *   specified explicitly.
+ * @param options.exactParams Controls whether the number of received arguments
+ *   has to match the expectation.
+ *
+ * @example
+ * const fn = mock<() => number>();
+ *
+ * when(() => fn()).thenReturn(23);
+ *
+ * fn() === 23;
  */
 
 
@@ -999,11 +919,11 @@ const mock = ({
     exactParams: exactParams != null ? exactParams : currentDefaults.exactParams
   };
   const repository = new FlexibleRepository(options.unexpectedProperty);
-  const pendingExpectation = new PendingExpectationWithFactory(strongExpectationFactory, options.concreteMatcher, options.exactParams);
-  const stub = createStub(repository, pendingExpectation, getMode);
+  const builder = new ExpectationBuilderWithFactory(strongExpectationFactory, options.concreteMatcher, options.exactParams);
+  const stub = createStub(repository, builder, getMode);
   setMockState(stub, {
     repository,
-    pendingExpectation,
+    builder,
     options
   });
   return stub;
@@ -1048,8 +968,8 @@ const createInvocationCount = expectation => ({
 
 });
 
-const finishPendingExpectation = (returnValue, pendingExpectation, repo) => {
-  const finishedExpectation = pendingExpectation.finish(returnValue);
+const finishExpectation = (returnValue, builder, repo) => {
+  const finishedExpectation = builder.finish(returnValue);
   repo.add(finishedExpectation);
   return createInvocationCount(finishedExpectation);
 };
@@ -1066,54 +986,54 @@ const getError = errorOrMessage => {
   return new Error();
 };
 
-const createReturns = (pendingExpectation, repository) => ({
-  thenReturn: returnValue => finishPendingExpectation( // This will handle both thenReturn(23) and thenReturn(Promise.resolve(3)).
+const createReturns = (builder, repository) => ({
+  thenReturn: returnValue => finishExpectation( // This will handle both thenReturn(23) and thenReturn(Promise.resolve(3)).
   {
     value: returnValue,
     isError: false,
     isPromise: false
-  }, pendingExpectation, repository),
-  thenThrow: errorOrMessage => finishPendingExpectation({
+  }, builder, repository),
+  thenThrow: errorOrMessage => finishExpectation({
     value: getError(errorOrMessage),
     isError: true,
     isPromise: false
-  }, pendingExpectation, repository),
-  thenResolve: promiseValue => finishPendingExpectation({
+  }, builder, repository),
+  thenResolve: promiseValue => finishExpectation({
     value: promiseValue,
     isError: false,
     isPromise: true
-  }, pendingExpectation, repository),
-  thenReject: errorOrMessage => finishPendingExpectation({
+  }, builder, repository),
+  thenReject: errorOrMessage => finishExpectation({
     value: getError(errorOrMessage),
     isError: true,
     isPromise: true
-  }, pendingExpectation, repository)
+  }, builder, repository)
 });
 
-/**
- * Set an expectation on a mock.
- *
- * The expectation must be finished by setting a return value, even if the value
- * is `undefined`.
- *
- * If a call happens that was not expected then the mock will throw an error.
- * By default, the call is expected to only be made once. Use the invocation
- * count helpers to expect a call multiple times.
- *
- * @param expectation A callback to set the expectation on your mock. The
- *   callback must return the value from the mock to properly infer types.
- *
- * @example
- * const fn = mock<() => void>();
- * when(() => fn()).thenReturn(undefined);
- *
- * @example
- * const fn = mock<() => number>();
- * when(() => fn()).thenReturn(42).atMost(3);
- *
- * @example
- * const fn = mock<(x: number) => Promise<number>();
- * when(() => fn(23)).thenResolve(42);
+/**
+ * Set an expectation on a mock.
+ *
+ * The expectation must be finished by setting a return value, even if the value
+ * is `undefined`.
+ *
+ * If a call happens that was not expected then the mock will throw an error.
+ * By default, the call is expected to only be made once. Use the invocation
+ * count helpers to expect a call multiple times.
+ *
+ * @param expectation A callback to set the expectation on your mock. The
+ *   callback must return the value from the mock to properly infer types.
+ *
+ * @example
+ * const fn = mock<() => void>();
+ * when(() => fn()).thenReturn(undefined);
+ *
+ * @example
+ * const fn = mock<() => number>();
+ * when(() => fn()).thenReturn(42).atMost(3);
+ *
+ * @example
+ * const fn = mock<(x: number) => Promise<number>();
+ * when(() => fn(23)).thenResolve(42);
  */
 
 const when = expectation => {
@@ -1121,32 +1041,32 @@ const when = expectation => {
   expectation();
   setMode(Mode.CALL);
   const {
-    pendingExpectation,
+    builder,
     repository
   } = getMockState(getActiveMock());
-  return createReturns(pendingExpectation, repository);
+  return createReturns(builder, repository);
 };
 
-/**
- * Remove any remaining expectations on the given mock.
- *
- * @example
- * const fn = mock<() => number>();
- *
- * when(() => fn()).thenReturn(23);
- *
- * reset(fn);
- *
- * fn(); // throws
+/**
+ * Remove any remaining expectations on the given mock.
+ *
+ * @example
+ * const fn = mock<() => number>();
+ *
+ * when(() => fn()).thenReturn(23);
+ *
+ * reset(fn);
+ *
+ * fn(); // throws
  */
 
 const reset = mock => {
   getMockState(mock).repository.clear();
 };
-/**
- * Reset all existing mocks.
- *
- * @see reset
+/**
+ * Reset all existing mocks.
+ *
+ * @see reset
  */
 
 const resetAll = () => {
@@ -1155,6 +1075,46 @@ const resetAll = () => {
   });
 };
 
+class UnmetExpectations extends Error {
+  constructor(expectations) {
+    super(jestMatcherUtils.DIM_COLOR(`There are unmet expectations:
+
+ - ${expectations.map(e => e.toString()).join('\n - ')}`));
+  }
+
+}
+/**
+ * Merge property accesses and method calls for the same property
+ * into a single call.
+ *
+ * @example
+ * mergeCalls({ getData: [{ arguments: undefined }, { arguments: [1, 2, 3] }] }
+ * // returns { getData: [{ arguments: [1, 2, 3] } }
+ */
+
+const mergeCalls = callMap => new Map(Array.from(callMap.entries()).map(([property, calls]) => {
+  const hasMethodCalls = calls.some(call => call.arguments);
+  const hasPropertyAccesses = calls.some(call => !call.arguments);
+
+  if (hasMethodCalls && hasPropertyAccesses) {
+    return [property, calls.filter(call => call.arguments)];
+  }
+
+  return [property, calls];
+}));
+
+class UnexpectedCalls extends Error {
+  constructor(unexpectedCalls, expectations) {
+    const printedCalls = Array.from(mergeCalls(unexpectedCalls).entries()).map(([property, calls]) => calls.map(call => printCall(property, call.arguments)).join('\n - ')).join('\n - ');
+    super(jestMatcherUtils.DIM_COLOR(`The following calls were unexpected:
+
+ - ${printedCalls}
+
+${printRemainingExpectations(expectations)}`));
+  }
+
+}
+
 const verifyRepo = repository => {
   const unmetExpectations = repository.getUnmet();
 
@@ -1168,22 +1128,22 @@ const verifyRepo = repository => {
     throw new UnexpectedCalls(callStats.unexpected, unmetExpectations);
   }
 };
-/**
- * Verify that all expectations on the given mock have been met.
- *
- * @throws Will throw if there are remaining expectations that were set
- * using `when` and that weren't met.
- *
- * @throws Will throw if any unexpected calls happened. Normally those
- * calls throw on their own, but the error might be caught by the code
- * being tested.
- *
- * @example
- * const fn = mock<() => number>();
- *
- * when(() => fn()).thenReturn(23);
- *
- * verify(fn); // throws
+/**
+ * Verify that all expectations on the given mock have been met.
+ *
+ * @throws Will throw if there are remaining expectations that were set
+ * using `when` and that weren't met.
+ *
+ * @throws Will throw if any unexpected calls happened. Normally those
+ * calls throw on their own, but the error might be caught by the code
+ * being tested.
+ *
+ * @example
+ * const fn = mock<() => number>();
+ *
+ * when(() => fn()).thenReturn(23);
+ *
+ * verify(fn); // throws
  */
 
 const verify = mock => {
@@ -1192,10 +1152,10 @@ const verify = mock => {
   } = getMockState(mock);
   verifyRepo(repository);
 };
-/**
- * Verify all existing mocks.
- *
- * @see verify
+/**
+ * Verify all existing mocks.
+ *
+ * @see verify
  */
 
 const verifyAll = () => {
@@ -1204,7 +1164,345 @@ const verifyAll = () => {
   });
 };
 
-exports.It = It;
+/**
+ * Compare values using `Object.is`.
+ *
+ * @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is
+ *
+ * @see It.deepEquals A matcher that uses deep equality.
+ */
+
+const is = expected => matches(actual => Object.is(actual, expected), {
+  toString: () => `${printValue(expected)}`,
+  getDiff: actual => ({
+    actual,
+    expected
+  })
+});
+
+/**
+ * Match any value, including `undefined` and `null`.
+ *
+ * @example
+ * const fn = mock<(x: number, y: string) => number>();
+ * when(() => fn(It.isAny(), It.isAny())).thenReturn(1);
+ *
+ * fn(23, 'foobar') === 1
+ */
+
+const isAny = () => matches(() => true, {
+  toString: () => 'Matcher<any>'
+});
+
+/**
+ * Match an array.
+ *
+ * Supports nested matchers.
+ *
+ * @param containing If given, the matched array has to contain ALL of these
+ *   elements in ANY order.
+ *
+ * @example
+ * const fn = mock<(arr: number[]) => number>();
+ * when(() => fn(It.isArray())).thenReturn(1);
+ * when(() => fn(It.isArray([2, 3]))).thenReturn(2);
+ *
+ * fn({ length: 1, 0: 42 }) // throws
+ * fn([]) === 1
+ * fn([3, 2, 1]) === 2
+ *
+ * @example
+ * It.isArray([It.isString({ containing: 'foobar' })])
+ */
+
+const isArray = containing => matches(actual => {
+  if (!Array.isArray(actual)) {
+    return false;
+  }
+
+  if (!containing) {
+    return true;
+  }
+
+  return containing.every(x => actual.find(y => {
+    if (isMatcher(x)) {
+      return x.matches(y);
+    }
+
+    return deepEquals(x).matches(y);
+  }) !== undefined);
+}, {
+  toString: () => containing ? `array(${printValue(containing)})` : 'array',
+  getDiff: actual => {
+    if (containing) {
+      return {
+        actual,
+        expected: `Matcher<array>([${containing.map(value => {
+          if (isMatcher(value)) {
+            return value.toString();
+          }
+
+          return value;
+        }).join(', ')}])`
+      };
+    }
+
+    return {
+      actual: `${printValue(actual)} (${typeof actual})`,
+      expected: 'Matcher<array>'
+    };
+  }
+});
+
+/**
+ * Match any number.
+ *
+ * @example
+ * const fn = mock<(x: number) => number>();
+ * when(() => fn(It.isNumber())).returns(42);
+ *
+ * fn(20.5) === 42
+ * fn(NaN) // throws
+ */
+
+const isNumber = () => matches(actual => typeof actual === 'number' && !Number.isNaN(actual), {
+  toString: () => 'Matcher<number>',
+  getDiff: actual => ({
+    actual: `${printValue(actual)} (${typeof actual})`,
+    expected: 'Matcher<number>'
+  })
+});
+
+const looksLikeObject = value => lodash.isPlainObject(value);
+
+const getExpectedObjectDiff = (actual, expected) => Object.fromEntries(Reflect.ownKeys(expected).map(key => {
+  const right = expected[key]; // @ts-expect-error because we're fine with a runtime undefined
+
+  const left = actual == null ? void 0 : actual[key];
+
+  if (isMatcher(right)) {
+    return [key, right.getDiff(left).expected];
+  }
+
+  if (looksLikeObject(right)) {
+    return [key, getExpectedObjectDiff(left, right)];
+  }
+
+  return [key, right];
+}));
+
+const getActualObjectDiff = (actual, expected) => {
+  if (!looksLikeObject(actual)) {
+    return actual;
+  }
+
+  return Object.fromEntries(Reflect.ownKeys(expected).map(key => {
+    const right = expected[key];
+    const left = actual[key];
+
+    if (!left) {
+      return [];
+    }
+
+    if (isMatcher(right)) {
+      return [key, right.getDiff(left).actual];
+    }
+
+    if (looksLikeObject(right)) {
+      return [key, getActualObjectDiff(left, right)];
+    }
+
+    return [key, left];
+  }));
+};
+
+const isMatch = (actual, expected) => Reflect.ownKeys(expected).every(key => {
+  const right = expected[key];
+  const left = looksLikeObject(actual) ? actual[key] : undefined;
+
+  if (!left) {
+    return false;
+  }
+
+  if (isMatcher(right)) {
+    return right.matches(left);
+  }
+
+  if (looksLikeObject(right)) {
+    return isMatch(left, right);
+  }
+
+  return deepEquals(right).matches(left);
+});
+
+const deepPrintObject = value => lodash.cloneDeepWith(value, value => {
+  if (isMatcher(value)) {
+    return value.toString();
+  }
+
+  return undefined;
+});
+/**
+ * Match any plain object.
+ *
+ * Object like values, e.g. classes and arrays, will not be matched.
+ *
+ * @param partial An optional subset of the expected object that will be
+ *   recursively matched. Supports nested matchers. Values will be
+ *   compared with {@link deepEquals}.
+ *
+ * @example
+ * const fn = mock<(pos: { x: number, y: number }) => number>();
+ * when(() => fn(It.isObject({ x: 23 }))).returns(42);
+ *
+ * fn({ x: 100, y: 200 }) // throws
+ * fn({ x: 23, y: 200 }) // returns 42
+ *
+ * @example
+ * It.isObject({ foo: It.isString() })
+ */
+
+
+const isObject = partial => matches(actual => {
+  if (!looksLikeObject(actual)) {
+    return false;
+  }
+
+  if (!partial) {
+    return true;
+  }
+
+  return isMatch(actual, partial);
+}, {
+  toString: () => {
+    if (!partial) {
+      return 'Matcher<object>';
+    }
+
+    return `Matcher<object>(${printValue(deepPrintObject(partial))})`;
+  },
+  getDiff: actual => {
+    if (!partial) {
+      return {
+        expected: 'Matcher<object>',
+        actual: `${printValue(actual)}`
+      };
+    }
+
+    return {
+      actual: getActualObjectDiff(actual, partial),
+      expected: getExpectedObjectDiff(actual, partial)
+    };
+  }
+});
+
+/**
+ * Match any string.
+ *
+ * @param matching An optional string or RegExp to match the string against.
+ *   If it's a string, a case-sensitive search will be performed.
+ *
+ * @example
+ * const fn = mock<(x: string, y: string) => number>();
+ * when(() => fn(It.isString(), It.isString('bar'))).returns(42);
+ *
+ * fn('foo', 'baz') // throws
+ * fn('foo', 'bar') === 42
+ */
+
+const isString = matching => matches(actual => {
+  if (typeof actual !== 'string') {
+    return false;
+  }
+
+  if (!matching) {
+    return true;
+  }
+
+  if (typeof matching === 'string') {
+    return actual.indexOf(matching) !== -1;
+  }
+
+  return matching.test(actual);
+}, {
+  toString: () => {
+    if (matching) {
+      return `Matcher<string>(${matching})`;
+    }
+
+    return 'Matcher<string>';
+  },
+  getDiff: actual => {
+    if (matching) {
+      return {
+        expected: `Matcher<string>(${matching})`,
+        actual
+      };
+    }
+
+    return {
+      expected: 'Matcher<string>',
+      actual: `${actual} (${typeof actual})`
+    };
+  }
+});
+
+/**
+ * Matches anything and stores the received value.
+ *
+ * This should not be needed for most cases, but can be useful if you need
+ * access to a complex argument outside the expectation e.g. to test a
+ * callback.
+ *
+ * @param name If given, this name will be printed in error messages.
+ *
+ * @example
+ * const fn = mock<(cb: (value: number) => number) => void>();
+ * const matcher = It.willCapture();
+ * when(() => fn(matcher)).thenReturn();
+ *
+ * fn(x => x + 1);
+ * matcher.value?.(3) === 4
+ */
+
+const willCapture = name => {
+  let capturedValue;
+  const matcher = {
+    [MATCHER_SYMBOL]: true,
+    matches: actual => {
+      capturedValue = actual;
+      return true;
+    },
+    toString: () => name ? `Capture(${name})` : 'Capture',
+    getDiff: actual => ({
+      actual,
+      expected: actual
+    }),
+
+    get value() {
+      return capturedValue;
+    }
+
+  };
+  return matcher;
+};
+
+/* istanbul ignore file */
+
+var it = {
+  __proto__: null,
+  deepEquals: deepEquals,
+  is: is,
+  isAny: isAny,
+  isArray: isArray,
+  isNumber: isNumber,
+  isObject: isObject,
+  isString: isString,
+  matches: matches,
+  willCapture: willCapture
+};
+
+exports.It = it;
 exports.mock = mock;
 exports.reset = reset;
 exports.resetAll = resetAll;