## TL;DR

vi.mock is hoisted only at the top level of the test file; referencing outer variables inside the factory breaks it. Use the factory form at the top level and vi.hoisted() for any shared values the factory needs.

## The query

```text
vitest vi.mock() hoisting not working: how to fix
```

## Use this when

- vi.mock is silently ignored
- the real module loads despite the mock
- the factory throws on outer variables

## Not for

- vi.spyOn
- vi.stubGlobal
- manual mocks in __mocks__ directories

## Steps

1. Move the vi.mock() call to the top level of the file, before imports that use the mocked module. Expected output: the mock call sits at file top level.
2. If the factory references variables from the file scope, wrap them with vi.hoisted(). Expected output: shared values created inside vi.hoisted().
3. Prefer the factory form vi.mock('path', function () { return { mocked: true }; }) so the mock does not depend on import order. Expected output: an explicit factory returning the mock shape.
4. Check for a second vi.mock of the same path that overrides the first. Expected output: exactly one mock per module path.
5. Re-run and assert the mocked module is the one under test. Expected output: the test observes the mock, not the real module.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_P0qRKpGd7yl5CsKhIPcXaQ