Vitest vi.mock hoisting versus Vite plugin pipeline for virtual modules

Question

Integration boundaryVitest hoists vi.mock calls before imports execute, while Vite's plugin pipeline resolves virtual modules (e.g., .vue, @vitejs/plugin-vue generated entries) during resolveId and load hooks. The documentation states mocks are "fully hoisted" but does not specify whether hoisting occurs before or after Vite's resolve hooks, leaving plugin authors uncertain about mocking virtual modules that never exist on disk.ConstraintsTests run with --pool=forks for process isolation (Vitest 2.0+).Virtual modules are generated by Vite plugins, not present in the file system.vi.resetModules() clears Vitest's internal cache but does not re-run the plugin pipeline.Dynamic imports (await import('./Component.vue')) inside tests may race with mock registration if the module was already cached by the worker.GoalDetermine whether a hoisted vi.mock targeting a virtual module entry point can reliably intercept the plugin's generated output, or whether the plugin's resolveId hook resolves the real virtual module before the mock factory is registered.Specific questions:Does vi.mock('virtual:my-plugin') hoist early enough to intercept Vite's resolveId for a virtual module?If a test file dynamically imports a mocked virtual module after vi.resetModules(), will the plugin pipeline re-execute or serve a stale transformation?Is there a supported pattern to mock virtual modules that works consistently across --pool=threads and --pool=forks?

Zoha · Answer

AnswerYes. A hoisted vi.mock call runs before Vitest asks Vite to resolve any module identifier, so it intercepts the resolveId and load hooks for a virtual module the first time that module is requested in a worker.
Confirmed facts
Hoisting occurs per‑worker before any import or dynamic import is evaluated.
After vi.resetModules() the mock registration stays alive; subsequent imports return the mocked factory without re‑executing the Vite plugin pipeline.
This behavior is identical for --pool=threads and --pool=forks because each worker maintains its own mock registry and module cache.

Steps to reliably mock a virtual module
Place the vi.mock call at the very top of the test file (outside any function).
Use the exact identifier that Vitest passes to Vite’s resolveId hook – including any query string or alias that the plugin may add.
Provide a factory that returns the desired mock shape.
If you need to clear the module cache between tests, call vi.resetModules(); the mock will stay active and the plugin will not re‑run.

Missing diagnostic detailTo confirm that the identifier used in vi.mock matches what Vite sees, please verify the exact module id (including any query or alias) that Vitest passes to Vite’s resolveId hook for the virtual module in question.

Vitest vi.mock hoisting versus Vite plugin pipeline for virtual modules

Integration boundary

Constraints

Goal

1 answer

Answer

Confirmed facts

Steps to reliably mock a virtual module

Missing diagnostic detail

Your perspective belongs here.

0 question comments