Jest: How to spy on a function

When writing unit tests in JavaScript, especially with Jest, one common need is to spy on a function—in other words, to track whether it was called, how many times, and with what arguments. In this post, we'll walk through how to spy on a function using Jest, step by step, with real-world examples.

📌 Why Spy on a Function?

Spying is useful when:

• You want to verify that a callback was triggered.
• You need to ensure a method was called with the right parameters.
• You’re mocking a dependency but want to retain its original implementation.

🛠️ How to Spy on a Function in Jest

1. Using jest.spyOn()

Jest provides the jest.spyOn() method to spy on object methods.

✅ Example 1: Spying on an Object Method

const utils = {
  greet: (name) => `Hello, ${name}!`
};

test('greet should be called with correct argument', () => {
  const spy = jest.spyOn(utils, 'greet');

  utils.greet('Alice');

  expect(spy).toHaveBeenCalled();
  expect(spy).toHaveBeenCalledWith('Alice');

  spy.mockRestore(); // Clean up
});

🔎 What jest.spyOn() Does:

• Tracks calls to utils.greet
• Captures arguments passed
• Can be restored after testing

🧪 Example 2: Spying and Mocking Return Values

You can also mock the return value of a spied function.

test('greet returns a mocked value', () => {
  const spy = jest.spyOn(utils, 'greet').mockReturnValue('Mocked!');

  const result = utils.greet('Bob');

  expect(result).toBe('Mocked!');
  expect(spy).toHaveBeenCalledWith('Bob');

  spy.mockRestore();
});

⚠️ Gotchas & Best Practices

• Always restore the original function using mockRestore() to avoid test pollution.
• Only spy on existing methods of an object, not standalone functions. For standalone functions, use jest.fn().

💡 Bonus: Spying on Imported Module Functions

If you’re testing a module that imports a function, you can still spy on it:

// utils.js
export const log = (msg) => console.log(msg);

// app.js
import { log } from './utils';

export const run = () => {
  log('Running...');
};

// app.test.js
import * as utils from './utils';
import { run } from './app';

test('log should be called when run is invoked', () => {
  const spy = jest.spyOn(utils, 'log');
  run();
  expect(spy).toHaveBeenCalledWith('Running...');
  spy.mockRestore();
});

🚀 Summary

Jest's spyOn() is a powerful tool for tracking how your code interacts with functions. Whether you're testing internal logic or external dependencies, spying lets you assert behavior with precision.

✅ Quick Recap:

• Use jest.spyOn(object, 'method') to create a spy
• Assert calls with toHaveBeenCalled, toHaveBeenCalledWith
• Clean up with mockRestore()