documentation/guide page on vitest browser mode mocking and stubbing

[fvanderwielen]

Clear and concise description of the problem

Hey,

(first of all congrats on the 4.0 release!)

I recently discovered browser mode, and I am trying to migrate our vitest projects from JSDom to using browser mode instead. migrating the locators is not too challenging, as we come from testing library, but fixing all the mocks is to be honest.

The existing documentation on mocks under browser mode that I am aware of is this: https://vitest.dev/guide/browser/#spying-on-module-exports
it is concise, but already very helpful, without it I would not properly know what was wrong with what was previously normally functioning vitest tests.

I am still running into quite some particularities/gotchas of running tests in browser mode, to the point I think it would help if there was some documentation or a guide describing (correct me if I am wrong of course):

• which parts of the vitest API no longer work
• how previous tests can influence wether vi.mock('./module.js', { spy: true }) no longer works because that module was imported without mocks before. (A different feature request is perhaps that this would throw an error if possible?). I think this comment also holds valuable information on this topic.
• how caching of modules or instances of them seems to work differently.
• other things I am currently unaware of.

Suggested solution

A page in the documentation of vitest browser mode that explains the mentioned particularities of mocking in browser mode.

Alternative

No response

Additional context

No response

Validations

• Follow our Code of Conduct
• Read the Contributing Guidelines.
• Read the docs.
• Check that there isn't already an issue that request the same feature to avoid creating a duplicate.

[sheremet-va]

The only meaningful differences are documented, except the second point that you mentioned, and should indeed be mentioned somewhere, but I don't think it's possible to throw an error in that case because we don't control the browser module graph.

Otherwise, it uses the same @vitest/mocker package and should work the same way, that's why the documentation is concise, it's supposed to have almost no differences.

If you are interested in the implementation details, there is https://vitest.dev/guide/mocking/modules.html#browser-mode

[fvanderwielen]

Thanks for responding so quickly and sharing the link, I missed that info in the first place because the table of content in the upper right did not show the browser mode section.

Glad to hear also that most things should just work, I am noticing that that second bullet does seem to have quite some impact in migrating my tests. I am trying to fix this by adding all the needed vi.mock('./module.js', { spy: true }) in setupTest.js for all the modules that need mocking at some point. It is difficult to check whether that is the reason why tests fail though, as these problems fail silently and are complex to debug. It is a big wrinkle compared to the 'it just works' mocking of before.

Something that (probably) still works in isolation but becomes a much less useful pattern is passing a factory function to vi.mock(); that is different per test file, at least if I understand correctly. Because the mock would get locked into the first factory function of the first test file that happens to run. This pattern is used a lot in our projects as it is very ergonomic, while by my current understanding this causes issues across the test project.

Another thing that the browser blocks from stubbing are read only global variables, that therefore do not come from a module. Where I could previously do this:
vi.stubGlobal("window", { location: { href: "https://www.website.net/search?q=someSearchKeyword" } });
this no longer works, and I work around it by making modules that do something like this in a separate module:
export const getLocation = () => (window.location);
it allows for mocking and works easily enough, a pattern I think I learned lots of years ago from the Karma days...

[sheremet-va]

Glad to hear also that most things should just work, I am noticing that that second bullet does seem to have quite some impact in migrating my tests. I am trying to fix this by adding all the needed vi.mock('./module.js', { spy: true }) in setupTest.js for all the modules that need mocking at some point. It is difficult to check whether that is the reason why tests fail though, as these problems fail silently and are complex to debug. It is a big wrinkle compared to the 'it just works' mocking of before.

Something that (probably) still works in isolation but becomes a much less useful pattern is passing a factory function to vi.mock(); that is different per test file, at least if I understand correctly. Because the mock would get locked into the first factory function of the first test file that happens to run. This pattern is used a lot in our projects as it is very ergonomic, while by my current understanding this causes issues across the test project.

That is supposed to be a minor inconvenience. If you are encountering it, maybe your setup is a big more complex that I expected. One thing you can try to do is reduce the amount of code imported in your setup file, so that tests will always import a new version of the module making it possible to mock. Maybe move some of it into a utility that you have to import in every test instead?

If one test imported a module, it doesn't affect the mocks of other tests.

[sheremet-va]

There is a guide for mocking modules now: https://vitest.dev/guide/mocking/modules.html