A module mock is a last resort. It replaces the whole module and is appropriate at a real boundary: a payment SDK, the file system, the network, a runtime API that cannot be substituted otherwise. For domain logic it is almost always redundant: there dependency injection works more cleanly, passing the dependency explicitly rather than intercepting it at the import level. The less module magic, the clearer what exactly is replaced. Injection also makes the dependency visible right in the signature, whereas a module mock hides it in an implicit import that is easy to forget.

When a mock is needed after all, most often it is partial: keep the real module and replace one function. vi.mock with a factory and importOriginal takes the real exports and overrides only what is needed - for example trackPurchase, leaving the rest as is. This way the test does not lose the real behavior of neighboring functions and does not turn the mock into a parallel reimplementation of the whole module.

The crucial subtlety is hoisting. The vi.mock call is hoisted with its factory above the static imports, so inside the factory you cannot reference an ordinary variable from the file: at the moment it runs the variable does not exist yet. For this there is vi.hoisted: it prepares values available to the hoisted factory. The typical pairing is to declare a mock function via vi.hoisted and return it from the vi.mock factory.

If a mock is needed not for the whole file but after a condition or in one test, you use vi.doMock. It is not hoisted and applies to the next dynamic import, so the module is imported via await import after the mock is set. This gives pointwise control: different tests in one file can see different implementations of the boundary without interfering with each other.

Global automock rules that nobody on the team can explain are worth avoiding. An explicit vi.mock of a specific module reads and can be grepped; an invisible auto-replacement of all modules by a glob turns a failure into a riddle. The rule is the same as with spies: replace pointwise and exactly what you describe, not everything around just in case.

In Browser Mode the rules differ: the ESM namespace there is sealed, and you cannot override exports arbitrarily. vi.mock works with the { spy: true } option, and some familiar replacement tricks are unavailable. This is not a ban on browser tests but a reminder: module mocks are heavily tied to the environment, and what works in Node may need a different approach in the browser.