matcher error: received value must be a mock or spy function

ELiv 2025

3 min read 06-03-2025

The dreaded "Matcher Error: Received value must be a mock or spy function" often strikes during unit testing with mocking frameworks like Jest or Jasmine. This error signifies a mismatch between your expectation (a mock or spy function) and the actual function called during your test. Let's troubleshoot this common problem.

Understanding the Error

This error arises when you're using a mocking library (like Jest's jest.fn() or Jasmine's spyOn()) to set expectations on a function's behavior. The error message means your test is checking for a specific mock or spy function, but the function it actually encountered is a different, regular function. This usually points to a problem in your code's execution path or your test setup.

Common Causes and Solutions

Let's break down the most frequent reasons behind this error and how to fix them:

1. Incorrect Mocking or Spying

Problem: You might be mocking the wrong function or not mocking it at all. You could be inadvertently calling the real implementation instead of your mock.
Solution: Double-check that you're mocking the exact function you intend to test. Verify the function's path and name precisely. Use the correct mocking syntax. For example, in Jest:

// Correct way to mock a function
const myModule = require('./myModule');
jest.mock('./myModule'); // Mock the entire module

describe('myTest', () => {
  it('should call the mocked function', () => {
    myModule.myFunction.mockReturnValue('mocked response'); // Set the mock's return value
    const result = myModule.myFunction();
    expect(result).toBe('mocked response'); 
  });
});


// Incorrect way - this mocks the module, not the function itself.
// expect(myModule.myFunction).toHaveBeenCalled(); //Will result in the error.

2. Unexpected Function Calls

Problem: Your code might be calling a different function than anticipated due to conditional logic or unexpected side effects.
Solution: Carefully review the code path your test follows. Add console logs or debuggers to track the actual function calls during the test execution. This will help identify the function your test is actually calling versus the one you expect it to call.

3. Asynchronous Operations

Problem: If you're dealing with asynchronous operations (promises, async/await), the mock might not be set up correctly within the asynchronous context. The test might finish before the asynchronous operation completes, leading to a mismatch.
Solution: Use await within your it block to ensure the asynchronous operation finishes before assertions are made.

it('should handle asynchronous calls correctly', async () => {
  const mockFunction = jest.fn().mockResolvedValue('async result');
  const result = await myAsyncFunction(mockFunction);
  expect(mockFunction).toHaveBeenCalled();
  expect(result).toBe('async result');
});

4. Module Re-imports or Caching

Problem: Your testing environment might be caching the original function, even after mocking.
Solution: Ensure you're properly mocking the module before each test using beforeEach or a similar setup method. Restart your testing environment if necessary to clear any potential caches. Jest's automatic mocking usually handles this, but in certain edge cases you might need manual intervention.

5. Incorrect Assertions

Problem: Your expectations might be misconfigured; you're asserting against the wrong properties or using incorrect matchers.
Solution: Review your expect statements and ensure they correctly reflect your expectations of the mocked function (e.g., number of calls, arguments passed, return value).

Debugging Tips

Console Logging: Add console.log statements within your tested function and within your test to trace the execution flow. This helps pinpoint where the discrepancy occurs.
Debuggers: Use your IDE's debugger to step through the code line by line. This allows you to inspect variables and function calls at runtime and identify the source of the problem.

By systematically investigating these common causes and employing these debugging techniques, you'll be well-equipped to resolve the "Matcher Error: Received value must be a mock or spy function" and write more robust and reliable unit tests. Remember to carefully examine your mocking strategy, code flow, and assertions. Often, a minor adjustment is all that's needed to get your tests running smoothly.