expect-matcher-node-mock 1.1.2 → 1.1.3

package/README.md

@@ -22,15 +22,15 @@ This package bridges that gap by:
 ## Installation
 
 ```bash
-npm install expect-matcher-node-mock
+npm install --save-dev expect-matcher-node-mock
 ```
 
 ```bash
-yarn add expect-matcher-node-mock
+yarn add --dev expect-matcher-node-mock
 ```
 
 ```bash
-pnpm add expect-matcher-node-mock
+pnpm add --save-dev expect-matcher-node-mock
 ```
 
 ## Usage
@@ -163,14 +163,24 @@ https://jestjs.io/docs/expect#tohaventhreturnedwithnthcall-value
 ## Requirements
 
 - **Node.js 18.0.0 or higher** (for native test runner support)
-- **expect package** (peer dependency) - Install with `npm install expect`
+- **expect package** (peer dependency) - Version 29.0.0 or higher
+- **jest-matcher-utils package** (peer dependency) - Version 29.0.0 or higher
+- **chalk package** (peer dependency) - Version 4.0.0 or higher
 
 ## Peer Dependencies
 
-This package requires the `expect` library to be installed in your project:
+This package requires the following libraries to be installed in your project:
 
 ```bash
-npm install expect
+npm install expect jest-matcher-utils chalk
+```
+
+```bash
+yarn add expect jest-matcher-utils chalk
+```
+
+```bash
+pnpm add expect jest-matcher-utils chalk
 ```
 
 ## Troubleshooting
@@ -225,8 +235,14 @@ npm install
 # Run tests
 npm test
 
-# Run linting
+# Run linting (uses Biome)
 npm run lint
+
+# Auto-fix linting issues
+npm run lint:fix
+
+# Format code
+npm run format
 ```
 
 ## Changelog

package/lib/index.mjs

@@ -6,12 +6,12 @@ import {
   toHaveBeenCalledWith,
   toHaveBeenLastCalledWith,
   toHaveBeenNthCalledWith,
-  toReturn,
+  toHaveLastReturnedWith,
+  toHaveNthReturnedWith,
   toHaveReturned,
   toHaveReturnedTimes,
   toHaveReturnedWith,
-  toHaveLastReturnedWith,
-  toHaveNthReturnedWith,
+  toReturn,
 } from './mockMethodMatchers.mjs';
 
 expect.extend({

package/lib/mockMethodMatchers.mjs

@@ -13,13 +13,44 @@ export const INVERTED_COLOR = chalk.inverse;
 export const BOLD_WEIGHT = chalk.bold;
 export const DIM_COLOR = chalk.dim;
 
+/**
+ * Helper function to check if arguments match using deep equality
+ * @param {Array} callArgs - The arguments from the actual call
+ * @param {Array} expectedArgs - The expected arguments
+ * @returns {boolean} - Whether the arguments match
+ */
+function argumentsMatch(callArgs, expectedArgs) {
+  if (callArgs.length !== expectedArgs.length) {
+    return false;
+  }
+  return expectedArgs.every((arg, index) => {
+    try {
+      expect(callArgs[index]).toEqual(arg);
+      return true;
+    } catch (_) {
+      return false;
+    }
+  });
+}
+
+/**
+ * Helper function to format expected arguments message
+ * @param {Array} args - The arguments to format
+ * @returns {string} - Formatted message
+ */
+function formatExpectedArgs(args) {
+  return args.length === 0
+    ? 'called with 0 arguments'
+    : args.map(arg => printExpected(arg)).join(', ');
+}
+
 /**
  * Function to ensure that the received value is a mock function
- * @param {Function} received
- * @param {string} matcherName
- * @param {Object} options
- * @returns {boolean}
- * @throws {TypeError}
+ * @param {Function} received - The value to check if it's a mock function
+ * @param {string} matcherName - The name of the matcher being used
+ * @param {Object} [options={}] - Optional configuration for error messages
+ * @returns {boolean} - Returns true if validation passes
+ * @throws {TypeError} - Throws if received is not a function or not a mock function
  */
 function ensureReceivedIsNodeMock(received, matcherName, options = {}) {
   if (typeof received !== 'function') {
@@ -45,11 +76,11 @@ function ensureReceivedIsNodeMock(received, matcherName, options = {}) {
 
 /**
  * Factory function to create a matcher object
- * @param {string} matcherName
- * @param {Object} options
- * @param {boolean} options.isNot
- * @param {boolean} options.promise
- * @returns {Object}
+ * @param {string} matcherName - The name of the matcher
+ * @param {Object} [options={}] - Optional configuration
+ * @param {boolean} [options.isNot] - Whether this is a negated matcher
+ * @param {boolean} [options.promise] - Whether this is a promise matcher
+ * @returns {Object} - An object containing matcherName, options, and receivedText
  */
 function matcherFactory(matcherName, { isNot, promise } = {}) {
   return {
@@ -64,9 +95,11 @@ function matcherFactory(matcherName, { isNot, promise } = {}) {
 }
 
 /**
- * toHaveBeenCalled
- *
- * https://jestjs.io/docs/expect#tohavebeencalled
+ * Matcher to verify that a mock function was called at least once
+ * @param {Function} receivedMethod - The mock function to check
+ * @param {...any} args - Should not be provided (will cause an error if present)
+ * @returns {Object} - An object with pass and message properties
+ * @see https://jestjs.io/docs/expect#tohavebeencalled
  */
 function toHaveBeenCalled(receivedMethod, ...args) {
   const { matcherName, options, receivedText } = matcherFactory(
@@ -74,46 +107,37 @@ function toHaveBeenCalled(receivedMethod, ...args) {
     this
   );
 
-  if (ensureReceivedIsNodeMock(receivedMethod, matcherName, options)) {
-    let message = `\n${matcherHint(
-      matcherName,
-      receivedText,
-      '',
-      options
-    )}\n\n`;
-    let pass = false;
+  ensureReceivedIsNodeMock(receivedMethod, matcherName, options);
 
-    if (args && args[0]) {
-      message += `Matcher error: this matcher must not have an expected argument
-          \nExpected has type:  ${typeof args[0]}\nExpected has value: ${EXPECTED_COLOR(
-        args[0]
-      )}\n`;
-    } else {
-      pass = receivedMethod.mock.calls.length > 0;
-      if (pass) {
-        message += `Expected number of calls: ${EXPECTED_COLOR(
-          '0'
-        )}\nReceived number of calls: ${RECEIVED_COLOR(
-          receivedMethod.mock.calls.length
-        )}\n`;
-      } else {
-        message += `Expected number of calls: >= ${EXPECTED_COLOR(
-          '1'
-        )}\nReceived number of calls:    ${RECEIVED_COLOR('0')}\n`;
-      }
-    }
+  const hint = `\n${matcherHint(matcherName, receivedText, '', options)}\n\n`;
 
+  if (args.length > 0) {
     return {
-      pass,
-      message: () => message,
+      pass: false,
+      message: () =>
+        `${hint}Matcher error: this matcher must not have an expected argument\n` +
+        `Expected has type:  ${typeof args[0]}\nExpected has value: ${EXPECTED_COLOR(args[0])}\n`,
     };
   }
+
+  const pass = receivedMethod.mock.calls.length > 0;
+  const callsCount = receivedMethod.mock.calls.length;
+  const message = pass
+    ? `Expected number of calls: ${EXPECTED_COLOR('0')}\nReceived number of calls: ${RECEIVED_COLOR(callsCount)}\n`
+    : `Expected number of calls: >= ${EXPECTED_COLOR('1')}\nReceived number of calls:    ${RECEIVED_COLOR('0')}\n`;
+
+  return {
+    pass,
+    message: () => hint + message,
+  };
 }
 
 /**
- * toHaveBeenCalledTimes
- *
- * https://jestjs.io/docs/expect#tohavebeencalledtimesnumber
+ * Matcher to verify that a mock function was called an exact number of times
+ * @param {Function} receivedMethod - The mock function to check
+ * @param {number} expected - The expected number of calls
+ * @returns {Object} - An object with pass and message properties
+ * @see https://jestjs.io/docs/expect#tohavebeencalledtimesnumber
  */
 function toHaveBeenCalledTimes(receivedMethod, expected) {
   const { matcherName, options, receivedText } = matcherFactory(
@@ -147,9 +171,11 @@ function toHaveBeenCalledTimes(receivedMethod, expected) {
 }
 
 /**
- * toHaveBeenCalledWith
- *
- * https://jestjs.io/docs/expect#tohavebeencalledwitharg1-arg2-
+ * Matcher to verify that a mock function was called with specific arguments at least once
+ * @param {Function} receivedMethod - The mock function to check
+ * @param {...any} args - The expected arguments
+ * @returns {Object} - An object with pass and message properties
+ * @see https://jestjs.io/docs/expect#tohavebeencalledwitharg1-arg2-
  */
 function toHaveBeenCalledWith(receivedMethod, ...args) {
   const { matcherName, options, receivedText } = matcherFactory(
@@ -157,77 +183,41 @@ function toHaveBeenCalledWith(receivedMethod, ...args) {
     this
   );
 
-  if (ensureReceivedIsNodeMock(receivedMethod, matcherName, options)) {
-    const argsCount = args.length;
-    const receivedArgs = [];
-    let pass = false;
-    let message = '';
-
-    if (!receivedMethod.mock.calls.length) {
-      pass = false;
-      message = `Expected: `;
-      if (argsCount === 0) {
-        message += `called with 0 arguments`;
-      } else {
-        message += `${args.map(arg => printExpected(arg)).join(', ')}`;
-      }
-    } else {
-      pass = receivedMethod.mock.calls.some(call => {
-        receivedArgs.push(call.arguments);
-        return (
-          argsCount &&
-          args.every((arg, index) => {
-            try {
-              expect(call.arguments[index]).toEqual(arg);
-              return true;
-            } catch (_) {
-              return false;
-            }
-          })
-        );
-      });
-
-      message = `Expected: ${pass ? 'not ' : ''}`;
-
-      if (argsCount === 0) {
-        message += `called with 0 arguments`;
-      } else {
-        message += `${args.map(arg => printExpected(arg)).join(', ')}`;
-      }
-
-      message += `\n\nReceived\n${receivedArgs.reduce(
-        (receivedText, args, index) =>
-          (receivedText +=
-            args.length === 0
-              ? '\t' + index + ': called with 0 arguments\n'
-              : '\t' +
-                index +
-                ': ' +
-                args.map(arg => printReceived(arg)).join(', ') +
-                '\n'),
-        ''
-      )}`;
-    }
-
-    return {
-      pass,
-      message: () =>
-        `\n${matcherHint(
-          matcherName,
-          receivedText,
-          '...expected',
-          options
-        )}\n\n${message}\n\nNumber of calls: ${RECEIVED_COLOR(
-          receivedMethod.mock.calls.length
-        )}\n`,
-    };
+  ensureReceivedIsNodeMock(receivedMethod, matcherName, options);
+
+  const calls = receivedMethod.mock.calls;
+  const pass = calls.some(call => argumentsMatch(call.arguments, args));
+
+  const expectedMsg = `Expected: ${pass ? 'not ' : ''}${formatExpectedArgs(args)}`;
+
+  let receivedMsg = '';
+  if (calls.length === 0) {
+    receivedMsg = 'But the function was not called';
+  } else {
+    receivedMsg = `\n\nReceived\n${calls
+      .map((call, index) => {
+        const callArgs = call.arguments;
+        return callArgs.length === 0
+          ? `\t${index}: called with 0 arguments`
+          : `\t${index}: ${callArgs.map(arg => printReceived(arg)).join(', ')}`;
+      })
+      .join('\n')}`;
   }
+
+  return {
+    pass,
+    message: () =>
+      `\n${matcherHint(matcherName, receivedText, '...expected', options)}\n\n` +
+      `${expectedMsg}${receivedMsg}\n\nNumber of calls: ${RECEIVED_COLOR(calls.length)}\n`,
+  };
 }
 
 /**
- * toHaveBeenLastCalledWith
- *
- * https://jestjs.io/docs/expect#tohavebeenlastcalledwitharg1-arg2-
+ * Matcher to verify that a mock function was last called with specific arguments
+ * @param {Function} receivedMethod - The mock function to check
+ * @param {...any} args - The expected arguments
+ * @returns {Object} - An object with pass and message properties
+ * @see https://jestjs.io/docs/expect#tohavebeenlastcalledwitharg1-arg2-
  */
 function toHaveBeenLastCalledWith(receivedMethod, ...args) {
   const { matcherName, options, receivedText } = matcherFactory(
@@ -235,67 +225,44 @@ function toHaveBeenLastCalledWith(receivedMethod, ...args) {
     this
   );
 
-  if (ensureReceivedIsNodeMock(receivedMethod, matcherName, options)) {
-    const argsCount = args.length;
-    const receivedArgs = [];
-    let pass = false;
-    let message = '';
-    const callsCount = receivedMethod.mock.calls.length;
-
-    if (!callsCount) {
-      pass = false;
-      message = `Expected: `;
-      if (argsCount === 0) {
-        message += `called with 0 arguments`;
-      } else {
-        message += `${args.map(arg => printExpected(arg)).join(', ')}`;
-      }
-    } else {
-      const lastCall = receivedMethod.mock.calls[callsCount - 1];
-      receivedArgs.push(lastCall.arguments);
-      pass =
-        argsCount &&
-        args.every((arg, index) => {
-          try {
-            expect(lastCall.arguments[index]).toEqual(arg);
-            return true;
-          } catch (_) {
-            return false;
-          }
-        });
-
-      message = `Expected: ${pass ? 'not ' : ''}`;
-
-      if (argsCount === 0) {
-        message += `called with 0 arguments`;
-      } else {
-        message += `${args.map(arg => printExpected(arg)).join(', ')}`;
-      }
-
-      message += `\n\n\nReceived: ${receivedArgs.map(args =>
-        args.map(arg => printReceived(arg)).join(', ')
-      )}`;
-    }
+  ensureReceivedIsNodeMock(receivedMethod, matcherName, options);
 
+  const calls = receivedMethod.mock.calls;
+  const callsCount = calls.length;
+
+  if (callsCount === 0) {
     return {
-      pass,
+      pass: false,
       message: () =>
-        `${matcherHint(
-          matcherName,
-          receivedText,
-          '...expected',
-          options
-        )}\n\n${message}\n\nNumber of calls: ${RECEIVED_COLOR(
-          receivedMethod.mock.calls.length
-        )}\n`,
+        `${matcherHint(matcherName, receivedText, '...expected', options)}\n\n` +
+        `Expected: ${formatExpectedArgs(args)}\n` +
+        `But the function was not called\n\nNumber of calls: ${RECEIVED_COLOR(0)}\n`,
     };
   }
+
+  const lastCall = calls[callsCount - 1];
+  const pass = argumentsMatch(lastCall.arguments, args);
+  const receivedArgs = lastCall.arguments
+    .map(arg => printReceived(arg))
+    .join(', ');
+
+  return {
+    pass,
+    message: () =>
+      `${matcherHint(matcherName, receivedText, '...expected', options)}\n\n` +
+      `Expected: ${pass ? 'not ' : ''}${formatExpectedArgs(args)}\n\n\n` +
+      `Received: ${receivedArgs || 'called with 0 arguments'}\n\n` +
+      `Number of calls: ${RECEIVED_COLOR(callsCount)}\n`,
+  };
 }
 
 /**
- * toHaveBeenNthCalledWith
- *
- * https://jestjs.io/docs/expect#tohavebeennthcalledwithnthcall-arg1-arg2-
+ * Matcher to verify that a mock function was called with specific arguments on the nth call
+ * @param {Function} receivedMethod - The mock function to check
+ * @param {number} nthCallIndex - The call number to check (1-indexed)
+ * @param {...any} args - The expected arguments
+ * @returns {Object} - An object with pass and message properties
+ * @see https://jestjs.io/docs/expect#tohavebeennthcalledwithnthcall-arg1-arg2-
  */
 function toHaveBeenNthCalledWith(receivedMethod, nthCallIndex, ...args) {
   const { matcherName, options, receivedText } = matcherFactory(
@@ -303,71 +270,45 @@ function toHaveBeenNthCalledWith(receivedMethod, nthCallIndex, ...args) {
     this
   );
 
-  if (ensureReceivedIsNodeMock(receivedMethod, matcherName, options)) {
-    const argsCount = args.length;
-    const receivedArgs = [];
-    let pass = false;
-    let message = `n: ${nthCallIndex}\n`;
-    const callsCount = receivedMethod.mock.calls.length;
-
-    if (!callsCount || nthCallIndex > callsCount) {
-      pass = false;
-      message += `Expected: `;
-      if (argsCount === 0) {
-        message += `called with 0 arguments`;
-      } else {
-        message += `${args.map(arg => printExpected(arg)).join(', ')}`;
-      }
-    } else {
-      const nthCall = receivedMethod.mock.calls[nthCallIndex - 1];
-      receivedArgs.push(nthCall.arguments);
-      pass =
-        argsCount &&
-        args.every((arg, index) => {
-          try {
-            expect(nthCall.arguments[index]).toEqual(arg);
-            return true;
-          } catch (_) {
-            return false;
-          }
-        });
-
-      message += `Expected: ${pass ? 'not ' : ''}`;
-
-      if (argsCount === 0) {
-        message += `called with 0 arguments`;
-      } else {
-        message += `${args.map(arg => printExpected(arg)).join(', ')}`;
-      }
-
-      message += `\nReceived: ${
-        receivedArgs.length
-          ? receivedArgs.map(args =>
-              args.map(arg => printReceived(arg)).join(', ')
-            )
-          : 'called with 0 arguments'
-      }`;
-    }
+  ensureReceivedIsNodeMock(receivedMethod, matcherName, options);
+
+  const calls = receivedMethod.mock.calls;
+  const callsCount = calls.length;
 
+  if (nthCallIndex < 1 || nthCallIndex > callsCount) {
     return {
-      pass,
+      pass: false,
       message: () =>
-        `${matcherHint(
-          matcherName,
-          receivedText,
-          '...expected',
-          options
-        )}\n\n${message}\n\nNumber of calls: ${RECEIVED_COLOR(
-          receivedMethod.mock.calls.length
-        )}\n`,
+        `${matcherHint(matcherName, receivedText, '...expected', options)}\n\n` +
+        `n: ${nthCallIndex}\n` +
+        `Expected: ${formatExpectedArgs(args)}\n` +
+        `But the function was ${callsCount === 0 ? 'not called' : `only called ${callsCount} time(s)`}\n\n` +
+        `Number of calls: ${RECEIVED_COLOR(callsCount)}\n`,
     };
   }
+
+  const nthCall = calls[nthCallIndex - 1];
+  const pass = argumentsMatch(nthCall.arguments, args);
+  const receivedArgs = nthCall.arguments
+    .map(arg => printReceived(arg))
+    .join(', ');
+
+  return {
+    pass,
+    message: () =>
+      `${matcherHint(matcherName, receivedText, '...expected', options)}\n\n` +
+      `n: ${nthCallIndex}\n` +
+      `Expected: ${pass ? 'not ' : ''}${formatExpectedArgs(args)}\n` +
+      `Received: ${receivedArgs || 'called with 0 arguments'}\n\n` +
+      `Number of calls: ${RECEIVED_COLOR(callsCount)}\n`,
+  };
 }
 
 /**
- * toHaveReturned
- *
- * https://jestjs.io/docs/expect#tohavereturned
+ * Matcher to verify that a mock function successfully returned (without error) at least once
+ * @param {Function} receivedMethod - The mock function to check
+ * @returns {Object} - An object with pass and message properties
+ * @see https://jestjs.io/docs/expect#tohavereturned
  */
 function toHaveReturned(receivedMethod) {
   const { matcherName, options, receivedText } = matcherFactory(
@@ -405,18 +346,21 @@ function toHaveReturned(receivedMethod) {
 }
 
 /**
- * toReturn
- *
- * https://jestjs.io/docs/expect#tohavereturned
+ * Alias for toHaveReturned - verifies that a mock function successfully returned at least once
+ * @param {Function} receivedMethod - The mock function to check
+ * @returns {Object} - An object with pass and message properties
+ * @see https://jestjs.io/docs/expect#tohavereturned
  */
 function toReturn(receivedMethod) {
   return toHaveReturned(receivedMethod);
 }
 
 /**
- * toHaveReturnedTimes
- *
- * https://jestjs.io/docs/expect#tohavereturnedtimesnumber
+ * Matcher to verify that a mock function successfully returned a specific number of times
+ * @param {Function} receivedMethod - The mock function to check
+ * @param {number} times - The expected number of successful returns
+ * @returns {Object} - An object with pass and message properties
+ * @see https://jestjs.io/docs/expect#tohavereturnedtimesnumber
  */
 function toHaveReturnedTimes(receivedMethod, times) {
   const { matcherName, options, receivedText } = matcherFactory(
@@ -424,40 +368,28 @@ function toHaveReturnedTimes(receivedMethod, times) {
     this
   );
 
-  if (ensureReceivedIsNodeMock(receivedMethod, matcherName, options)) {
-    const noErrorCalls = receivedMethod.mock.calls.filter(
-      call => call.error === undefined
-    );
-    const pass = noErrorCalls.length === times;
-
-    let message = `\n${matcherHint(
-      matcherName,
-      receivedText,
-      'expected',
-      options
-    )}\n\n`;
+  ensureReceivedIsNodeMock(receivedMethod, matcherName, options);
 
-    if (pass) {
-      message += `Expected: ${printExpected(times)}\nReceived: ${printReceived(
-        noErrorCalls.length
-      )}`;
-    } else {
-      message += `Expected: ${printExpected(times)}\nReceived: ${printReceived(
-        noErrorCalls.length
-      )}`;
-    }
+  const successfulReturns = receivedMethod.mock.calls.filter(
+    call => call.error === undefined
+  ).length;
+  const pass = successfulReturns === times;
 
-    return {
-      pass,
-      message: () => message,
-    };
-  }
+  return {
+    pass,
+    message: () =>
+      `\n${matcherHint(matcherName, receivedText, 'expected', options)}\n\n` +
+      `Expected: ${pass ? 'not ' : ''}${printExpected(times)}\n` +
+      `Received: ${printReceived(successfulReturns)}`,
+  };
 }
 
 /**
- * toHaveReturnedWith
- *
- * https://jestjs.io/docs/expect#tohavereturnedwithvalue
+ * Matcher to verify that a mock function returned a specific value at least once
+ * @param {Function} receivedMethod - The mock function to check
+ * @param {any} expected - The expected return value
+ * @returns {Object} - An object with pass and message properties
+ * @see https://jestjs.io/docs/expect#tohavereturnedwithvalue
  */
 function toHaveReturnedWith(receivedMethod, expected) {
   const { matcherName, options, receivedText } = matcherFactory(
@@ -465,43 +397,34 @@ function toHaveReturnedWith(receivedMethod, expected) {
     this
   );
 
-  if (ensureReceivedIsNodeMock(receivedMethod, matcherName, options)) {
-    const pass = receivedMethod.mock.calls.some(
-      call => call.result === expected
-    );
+  ensureReceivedIsNodeMock(receivedMethod, matcherName, options);
 
-    let message = `\n${matcherHint(
-      matcherName,
-      receivedText,
-      'expected',
-      options
-    )}\n\n`;
-
-    if (pass) {
-      message += `Expected: ${printExpected(
-        expected
-      )}\nReceived: ${printReceived(
-        receivedMethod.mock.calls.map(call => call.result)
-      )}`;
-    } else {
-      message += `Expected: ${printExpected(
-        expected
-      )}\nReceived: ${printReceived(
-        receivedMethod.mock.calls.map(call => call.result)
-      )}`;
+  const pass = receivedMethod.mock.calls.some(call => {
+    try {
+      expect(call.result).toEqual(expected);
+      return true;
+    } catch (_) {
+      return false;
     }
+  });
 
-    return {
-      pass,
-      message: () => message,
-    };
-  }
+  const allResults = receivedMethod.mock.calls.map(call => call.result);
+
+  return {
+    pass,
+    message: () =>
+      `\n${matcherHint(matcherName, receivedText, 'expected', options)}\n\n` +
+      `Expected: ${pass ? 'not ' : ''}${printExpected(expected)}\n` +
+      `Received: ${printReceived(allResults)}`,
+  };
 }
 
 /**
- * toHaveLastReturnedWith
- *
- * https://jestjs.io/docs/expect#tohavelastreturnedwithvalue
+ * Matcher to verify that a mock function's last return value matches the expected value
+ * @param {Function} receivedMethod - The mock function to check
+ * @param {any} expected - The expected return value
+ * @returns {Object} - An object with pass and message properties
+ * @see https://jestjs.io/docs/expect#tohavelastreturnedwithvalue
  */
 function toHaveLastReturnedWith(receivedMethod, expected) {
   const { matcherName, options, receivedText } = matcherFactory(
@@ -509,39 +432,42 @@ function toHaveLastReturnedWith(receivedMethod, expected) {
     this
   );
 
-  if (ensureReceivedIsNodeMock(receivedMethod, matcherName, options)) {
-    const lastCall =
-      receivedMethod.mock.calls[receivedMethod.mock.calls.length - 1];
-    const pass = lastCall.result === expected;
-
-    let message = `\n${matcherHint(
-      matcherName,
-      receivedText,
-      'expected',
-      options
-    )}\n\n`;
-
-    if (pass) {
-      message += `Expected: ${printExpected(
-        expected
-      )}\nReceived: ${printReceived(lastCall.result)}`;
-    } else {
-      message += `Expected: ${printExpected(
-        expected
-      )}\nReceived: ${printReceived(lastCall.result)}`;
-    }
+  ensureReceivedIsNodeMock(receivedMethod, matcherName, options);
 
+  const calls = receivedMethod.mock.calls;
+  if (calls.length === 0) {
     return {
-      pass,
-      message: () => message,
+      pass: false,
+      message: () =>
+        `\n${matcherHint(matcherName, receivedText, 'expected', options)}\n\nExpected: ${printExpected(expected)}\nBut the function was not called`,
     };
   }
+
+  const lastCall = calls[calls.length - 1];
+  let pass = false;
+  try {
+    expect(lastCall.result).toEqual(expected);
+    pass = true;
+  } catch (_) {
+    pass = false;
+  }
+
+  return {
+    pass,
+    message: () =>
+      `\n${matcherHint(matcherName, receivedText, 'expected', options)}\n\n` +
+      `Expected: ${pass ? 'not ' : ''}${printExpected(expected)}\n` +
+      `Received: ${printReceived(lastCall.result)}`,
+  };
 }
 
 /**
- * toHaveNthReturnedWith
- *
- * https://jestjs.io/docs/expect#tohaventhreturnedwithnthcall-value
+ * Matcher to verify that a mock function's nth return value matches the expected value
+ * @param {Function} receivedMethod - The mock function to check
+ * @param {number} nthCall - The call number to check (1-indexed)
+ * @param {any} expected - The expected return value
+ * @returns {Object} - An object with pass and message properties
+ * @see https://jestjs.io/docs/expect#tohaventhreturnedwithnthcall-value
  */
 function toHaveNthReturnedWith(receivedMethod, nthCall, expected) {
   const { matcherName, options, receivedText } = matcherFactory(
@@ -549,32 +475,37 @@ function toHaveNthReturnedWith(receivedMethod, nthCall, expected) {
     this
   );
 
-  if (ensureReceivedIsNodeMock(receivedMethod, matcherName, options)) {
-    const nthCallResult = receivedMethod.mock.calls[nthCall - 1].result;
-    const pass = nthCallResult === expected;
-
-    let message = `\n${matcherHint(
-      matcherName,
-      receivedText,
-      'expected',
-      options
-    )}\n\n`;
-
-    if (pass) {
-      message += `Expected: ${printExpected(
-        expected
-      )}\nReceived: ${printReceived(nthCallResult)}`;
-    } else {
-      message += `Expected: ${printExpected(
-        expected
-      )}\nReceived: ${printReceived(nthCallResult)}`;
-    }
+  ensureReceivedIsNodeMock(receivedMethod, matcherName, options);
 
+  const calls = receivedMethod.mock.calls;
+  if (nthCall < 1 || nthCall > calls.length) {
     return {
-      pass,
-      message: () => message,
+      pass: false,
+      message: () =>
+        `\n${matcherHint(matcherName, receivedText, 'expected', options)}\n\n` +
+        `n: ${nthCall}\n` +
+        `Expected: ${printExpected(expected)}\n` +
+        `But the function was ${calls.length === 0 ? 'not called' : `only called ${calls.length} time(s)`}`,
     };
   }
+
+  const nthCallResult = calls[nthCall - 1].result;
+  let pass = false;
+  try {
+    expect(nthCallResult).toEqual(expected);
+    pass = true;
+  } catch (_) {
+    pass = false;
+  }
+
+  return {
+    pass,
+    message: () =>
+      `\n${matcherHint(matcherName, receivedText, 'expected', options)}\n\n` +
+      `n: ${nthCall}\n` +
+      `Expected: ${pass ? 'not ' : ''}${printExpected(expected)}\n` +
+      `Received: ${printReceived(nthCallResult)}`,
+  };
 }
 
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expect-matcher-node-mock",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "description": "Jest-like expect matchers for native Node.js test runner mock objects. Provides toHaveBeenCalled, toHaveBeenCalledWith, toHaveReturned and more.",
   "main": "lib/index.mjs",
   "type": "module",
@@ -39,19 +39,18 @@
   "license": "MIT",
   "author": "Crysa Drak <cd@l33t.cz>",
   "scripts": {
-    "lint": "eslint --cache --cache-location=node_modules/.cache/ './**/*.{js,jsx,ts,tsx,mjs}'",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "format": "biome format --write .",
     "test": "node --test --test-reporter=spec"
   },
   "devDependencies": {
-    "eslint": "^8.27.0",
-    "eslint-config-prettier": "^8.5.0",
-    "eslint-plugin-import": "^2.27.5",
-    "eslint-plugin-prettier": "^4.2.1",
-    "prettier": "^2.8.4",
+    "@biomejs/biome": "^1.9.4",
     "strip-ansi": "7.1.0"
   },
-  "dependencies": {
-    "expect": "29.7.0",
-    "jest-matcher-utils": "29.7.0"
+  "peerDependencies": {
+    "chalk": ">=4.0.0",
+    "expect": ">=29.0.0",
+    "jest-matcher-utils": ">=29.0.0"
   }
 }