vi.spyOn vs vi.mock for mocking? Best practice for mocking

[dolanmiu]

What is the best practice for mocking?

It seems that these are equivalent. What are the benefits of using each approach?

import { axiosClient } from "../axiosClient";

vi.spyOn(axiosClient, "get").mockResolvedValue({ data: MOCk_DATA });

describe("api", () => {
   ...
});

import { AxiosInstance } from "axios";

vi.mock("../axiosClient");
const realAxiosImport = await import("../axiosClient");

realAxiosImport.axiosClient = {
    get: vi.fn().mockReturnValue({ data: MOCk_DATA }),
} as unknown as AxiosInstance;

describe("api", () => {
   ...
});

1. I am aware that vi.mock gets hoisted to the top.... but that to me makes it a disadvantage, as vi.spyOn can be called from anywhere (even at the top after imports)
2. It seems vi.mock is way more verbose for the same functionality as vi.spyOn.
3. vi.spyOn is more type safe (notice in vi.mock get, I can return anything
4. vi.mock requires all functions mocked, so casting to unknown is a workaround
5. vi.spyOn is more explicit/strict with async/await (notice mockResolvedValue rather than mockReturnValue)
6. vi.mock doesn't work well if you re-name/move files ("../axiosClient" would not auto-refactor etc)
7. vi.spyOn is more feature rich (mocking implementations, mocking variables etc)

It seems to me that vi.spyOn is superior? What does everyone think?

[mcous]

I've spent a lot of time doing TDD with mocks in Vitest (and Jest before it, and mocha/sinon before that), and I've come to believe that using vi.spyOn is almost always a bad idea.

spyOn creates partial mocks, which are harmful to the health of your test suite. Partially real, partially mocked objects can be quite difficult for future developers (and your future self) to reason with, because you lack control over parts of the mock. I always point people at this talk for an excellent overview of good and bad mocking practices - including a section on partial mocks.

import { AxiosInstance } from "axios";

vi.mock("../axiosClient");
const realAxiosImport = await import("../axiosClient");

realAxiosImport.axiosClient = {
  get: vi.fn().mockReturnValue({ data: MOCk_DATA }),
} as unknown as AxiosInstance;

describe("api", () => {
  ...
});

This doesn't look quite right to me. Because of vi.mock hoisting, I think realAxiosImport would be the automocked module. In that case, you shouldn't need to manually assign a new object to .axiosClient; vi.mock will have already mocked it out:

import { axiosClient } from "../axiosClient";
import * as subject from "../subject";

vi.mock("../axiosClient");

describe("api", () => {
  it("should call GET /foo", async () => {
    vi.mocked(axiosClient.get).mockResolvedValue({ data: { mockData: true } });

    const result = await subject.fetchFoo();

    expect(axiosClient.get).toHaveBeenCalledWith("/foo");
    expect(result).toEqual({ mockData: true });
  });
});

1. I am aware that vi.mock gets hoisted to the top.... but that to me makes it a disadvantage, as vi.spyOn can be called from anywhere (even at the top after imports)

While I dislike the magic of hoisting, I think mixing and matching mocks vs real modules in a single test suite leads to confusion. In that way, I find vi.mock to be helpful: the module will always be mocked throughout the whole test suite. There is the non-hoisted vi.doMock, but I've yet to find a good use-case for it in my projects.

2. It seems vi.mock is way more verbose for the same functionality as vi.spyOn.

I've found it to be the other way around; vi.mock hands you an entirely fake module, while with vi.spyOn you have to do the extra work of specifying the method you're mocking out.

3. vi.spyOn is more type safe (notice in vi.mock get, I can return anything
4. vi.mock requires all functions mocked, so casting to unknown is a workaround
5. vi.spyOn is more explicit/strict with async/await (notice mockResolvedValue rather than mockReturnValue)

You can use the vi.mocked helper, as in the example above, to get the proper type annotations when using vi.mock. Alternatively, (shameless self-promotion) you can use a library like vitest-when to provide even more typing strictness, including for call arguments, to your mocks:

import { describe, expect, it, vi } from "vitest";
import { when } from "vitest-when";

import { axiosClient } from "../axiosClient";
import * as subject from "../subject";

vi.mock("../axiosClient");

describe("fetching foo", () => {
  afterEach(() => {
    vi.resetAllMocks()
  })

  it("should call GET /foo", async () => {
    when(axiosClient.get)
      .calledWith("/foo")
      .thenResolve({ data: { mockData: true } });

    const result = await subject.fetchFoo();

    expect(result).toEqual({ mockData: true });
  });
});

6. vi.mock doesn't work well if you re-name/move files ("../axiosClient" would not auto-refactor etc)

True! I only ever experience this as an occasional minor inconvenience that I fix with a find-and-replace, so I don't personally consider it that important. Might be an interesting feature for the VSCode extension, though!

7. vi.spyOn is more feature rich (mocking implementations, mocking variables etc)

I've found vi.mock's auto-mocking to be quite sophisticated and flexible with sensible defaults. Where have you found it to fall short? Certainly you can get vi.spyOn to do some complicated stuff, but at a certain point, if you're jumping through hoops to get your mocks configured, rather than thinking "how can I make this mock work?", you should be thinking "how can I redesign my internal APIs to make testing easier?"

[dolanmiu]

"I need to mock this primitive value" would be "No, you need to restructure your internal APIs"

What if those APIs are external? lol
There was a use case which i needed to mock a primitive window.location.href, I couldn't do it with vi.mock
I had to use vi.spyOn

And also, with vi.mock, we need to teardown right? with afterAll(() => vi.restoreAllMocks);? vi.spyOn doesn't need this I think

[mcous]

"I need to mock this primitive value" would be "No, you need to restructure your internal APIs"

What if those APIs are external? lol

My opinion in that case is don't mock out external APIs directly 🥲. This can be a really big shift in thinking if you're used to using mocks to knock something out that makes your tests difficult. IMO this sort of mocking is tech debt.

Mocking third-party dependencies, which is something I've done a lot of in my career, almost always ends up:

• Missing bugs at the time of writing, and failing to catch regressions in the future
• Creating friction against change through coupling my source and tests to APIs I don't control

Tests that directly mock third party things don't test that my code works, because mocks are fake things. They also don't really test that the interactions are correct, because I don't control the behavior of the thing I'm mocking nor what's "correct." If I really try to explain one of these tests to myself, I end up realizing that all I've done is encode my own assumptions about how to call something external twice - in the source and the test - instead of just once.

There's a couple approaches I like to take instead of faking out something like window.location.href:

• Create a wrapper module (e.g. getCurrentURL) and mock out my wrapper module where needed
  • This isolates the third-party dependency, avoiding coupling
  • If the third-party dependency is complex, this also gives me a chance to provide a more simple API to the rest of my codebase
  • I don't - and probably can't - test the wrapper module directly; this is OK and allows my unit tests to be a little more honest about what's actually covered
• Avoid mocks and have "collaborators" that deal with calling the third-party APIs and passing the results on to unit-tested logic modules via function parameters
  • Replace "functions" and "parameters" with "components" and "props" for UI tests
  • I'm always in a type-checked codebase, so my type annotations help ensure proper collaborator wire up

Both approaches benefit greatly from having a coherent E2E testing strategy / suite, but I'd also argue that any project that uses mocks in its unit test suite requires an E2E suite to have meaningful test coverage.

And also, with vi.mock, we need to teardown right? with afterAll(() => vi.restoreAllMocks);? vi.spyOn doesn't need this I think

Both absolutely require cleanup logic to avoid cross test pollution. When using vi.mock, all I do is set mockReset: true in my Vitest config to automatically reset the mock call history and implementations after every test.

vi.restoreAllMocks doesn't unmock modules, only vi.unmock can do that. Mocked modules are only applicable on a per-test-file basis, so there is no need for an afterAll teardown

[GitMurf]

This discussion was super helpful and insightful! Thanks!

[pbotas]

Very helpful indeed! I landed here because of a specific issue, and even with all the experiments I wasn't able to fix it.
I'm mocking a module with vi.mock('./my-module') and then I test invocation with expect(myModule.myFunction).toHaveBeenCalled(). And vi.resetAllMocks() on afterEach.
It passes as expected on a normal vitest --run and same on the first run in watch mode. But in watch mode it always fails the next runs.
Any help?
Test file minimal:

import * as myModule from './my-module';
vi.mock('./my-module');
describe('another module', () => {
  afterEach(() => vi.resetAllMocks());
  it.only('should call myFunction', () => {
    await anotherModuleFunction();
    expect(myModule.myFunction).toHaveBeenCalled();
  });
});

[SteffanEnnis]

In your specific example from above if you want to maintain the original functionality of your module and just check that it's been invocated I'd use vi.spyOn.

Something like the following

import * as myModule from './my-module';
describe('another module', () => {
  afterEach(() => vi.resetAllMocks());
  it.only('should call myFunction', () => {
    const funcSpy = vi.spyOn(myModule,'myFunction')
    await anotherModuleFunction();
    expect(funcSpy).toHaveBeenCalled();
  });
});

I will also be a devils advocate for spyOn. In my experience I gravitate to spyOn unless in strict mode (enforced by the vitest browser mode) or otherwise prevented by other reasons.

• Most unit tests don't need to know the full API of the thing they are testing. Providing full mocks can often be overly verbose and in the case of moving contracts dangerous.
  • Reducing the blast radius of a breaking change is often a good thing
  • This is more important for large legacy codebases where it is often not realistic to refactor or rewrite.
• SpyOn doesn't hoist so you don't get weird module resolution errors (as many would've experienced with JEST and Babel)
• SpyOn doesn't interfere with globally mocked interfaces.
  • Not that I'm advocating for monkey patching but if there is any in the project providing a full mock will likely break the patch
    • Vite now enforces strict mode so in theory monkey patching should be less prevalent
  • On big projects with many contributors we want least resistance to testing. Global mocks largely solve that allowing for contributions to be made with less friction