How does jest.mock work and why does hoisting matter?

When a module is imported, Jest resolves it through its own registry. jest.mock registers a replacement for that path before the module is required. Babel and ts-jest hoist the call to the top of the file so the replacement exists by the time the import runs.

jest.mock("./mailer", () => ({
  sendEmail: jest.fn().mockResolvedValue({ ok: true }),
}));

import { sendEmail } from "./mailer";
import { notifyUser } from "./notify";

test("sends one email", async () => {
  await notifyUser("asha@example.com");
  expect(sendEmail).toHaveBeenCalledTimes(1);
});

The hoisting rule

• The jest.mock call is moved above imports by the transform
• A factory referencing a top-level variable can fail with a module initialization error
• Variables prefixed with mock are allowed by the hoist guard
• Use jest.requireActual inside the factory to keep real exports
• Use jest.requireMock to read the replacement

jest.mock("./mailer", () => {
  const actual = jest.requireActual("./mailer");

  return {
    ...actual,
    sendEmail: jest.fn(),
  };
});

jest.mock is file-scoped. It applies to the module registry used by that test file, not to other files. If you need a different mock per test, import the mocked module and change the implementation with mockImplementation, or call jest.resetModules() and re-require carefully.