できない.dev

Vitest の vi.mock が効かない(巻き上げと factory のスコープ)

vi.mock はファイル先頭へ巻き上げられて import より前に実行されるため、外側スコープの変数を factory 内で参照すると失敗する。
vi.hoisted を使うか、巻き上げない vi.doMock に切り替えると解決する。

公開: 更新:

症状できない · exit 1
npx vitest run bad-hoist.test.js
…
⎯⎯⎯⎯⎯⎯ Failed Suites 1 ⎯⎯⎯⎯⎯⎯⎯
 FAIL  bad-hoist.test.js [ bad-hoist.test.js ]
Error: [vitest] There was an error when mocking a module. If you are using "vi.mock" factory, make sure there are no top level variables inside, since this call is hoisted to top of the file. Read more: https://vitest.dev/api/vi.html#vi-mock
解決後できた · exit 0
npx vitest run hoisted.test.js domock.test.js
…
 Test Files  2 passed (2)
      Tests  2 passed (2)
   Start at  01:10:38
   Duration  119ms (transform 60%, import 22%, tests 13%, worker 6%)

2026-10-01 に node:22(Node.js 22.23.3 / npm 10.9.9) で実際に打って取った出力。検証環境の詳細

要約

Vitest の vi.mock は呼び出し位置に関係なく、トランスフォーム時にファイルの先頭(すべての import より上)へ巻き上げられる。

そのため factory 関数の中でモジュールスコープの変数を参照すると、宣言前アクセスになって失敗する。

「モックしたはずなのに本物が呼ばれる」「Cannot access ... before initialization」が典型症状だ。

解決策は、factory で使う値を vi.hoisted で一緒に巻き上げるか、巻き上げない vi.doMock に切り替えることだ。

実行例

Vitest 5.0.3 で試すと、factory の中で下に書いた sendMock を参照したテストは、Cannot access 'sendMock' before initialization で読み込みの段階から失敗した。
vi.mock のパスが実際の import とずれたテストでは本物の send が呼ばれ、real: alice が返った。
vi.hoisted と vi.doMock に書き換えた 2 本はどちらも通る。

$ npx vitest run bad-hoist.test.js
 RUN  v5.0.3 /tmp/tmp.fiBhjecRrb
 
 ❯ bad-hoist.test.js (0 test)
 
⎯⎯⎯⎯⎯⎯ Failed Suites 1 ⎯⎯⎯⎯⎯⎯⎯
 
 FAIL  bad-hoist.test.js [ bad-hoist.test.js ]
Error: [vitest] There was an error when mocking a module. If you are using "vi.mock" factory, make sure there are no top level variables inside, since this call is hoisted to top of the file. Read more: https://vitest.dev/api/vi.html#vi-mock
 ❯ src/notify.js:1:1
      1| import { send } from "./mailer.js";
       | ^
      2|
      3| export function notify(user) {
 
Caused by: ReferenceError: Cannot access 'sendMock' before initialization
 ❯ bad-hoist.test.js:5:43
 
⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯[1/1]⎯
 
 Test Files  1 failed (1)
      Tests  no tests
   Start at  01:10:37
   Duration  97ms (worker 97%, environment 3%)
$ echo $?
1
$ npx vitest run bad-path.test.js
 RUN  v5.0.3 /tmp/tmp.fiBhjecRrb
 
 ❯ bad-path.test.js (1 test | 1 failed) 6ms
   × notify はモックした send を呼ぶ 5ms
 
⎯⎯⎯⎯⎯⎯⎯ Failed Tests 1 ⎯⎯⎯⎯⎯⎯⎯
 
 FAIL  bad-path.test.js > notify はモックした send を呼ぶ
AssertionError: expected 'real: alice' to be 'mocked' // Object.is equality
 
Expected: "mocked"
Received: "real: alice"
 
 ❯ bad-path.test.js:7:27
      5|
      6| test("notify はモックした send を呼ぶ", () => {
      7|   expect(notify("alice")).toBe("mocked");
       |                           ^
      8| });
      9|
 
⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯[1/1]⎯
 
 Test Files  1 failed (1)
      Tests  1 failed (1)
   Start at  01:10:37
   Duration  107ms (transform 55%, import 25%, tests 14%, worker 5%)
$ echo $?
1
$ npx vitest run hoisted.test.js domock.test.js
 RUN  v5.0.3 /tmp/tmp.fiBhjecRrb
 
 ✓ domock.test.js (1 test) 9ms
 ✓ hoisted.test.js (1 test) 3ms
 
 Test Files  2 passed (2)
      Tests  2 passed (2)
   Start at  01:10:38
   Duration  119ms (transform 60%, import 22%, tests 13%, worker 6%)
$ echo $?
0

— 2026-10-01 時点の出力

検証環境Node.js 22.23.3 / npm 10.9.9 / Python 3.11.2 / 2026-10-01 検証(ほか 1 件)
検証日
実行環境
node:22 Debian GNU/Linux 12 (bookworm)
バージョン
  • Node.js 22.23.3
  • npm 10.9.9
  • Python 3.11.2
  • Git 2.39.5

この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。

解決策

1. vi.hoisted で変数ごと巻き上げる

import { vi, test, expect } from "vitest";
 
const { sendMock } = vi.hoisted(() => ({ sendMock: vi.fn() }));
 
vi.mock("./mailer", () => ({ send: sendMock }));

vi.hoisted の戻り値は vi.mock と同じ高さへ巻き上がるので、factory から安全に参照できる。

2. 巻き上げたくないなら vi.doMock

let impl = () => "real";
vi.doMock("./config", () => ({ get: () => impl() }));
const target = await import("./target");

vi.doMock は先頭へ移動しないため、直前に定義した変数を参照できる。
ただしモック登録より前に読み込み済みのモジュールには効かない。

3. パスはテストファイルから見て同じファイルを指す

vi.mock のパスは、vi.mock を書いたテストファイルを基準に解決される。
テスト対象のモジュールが ./mailer.js を import していても、テストファイルが別のディレクトリにあれば vi.mock("./mailer.js") は別のファイルを指し、モックは効かない。
テストファイルから見た相対パス(../src/mailer.js など)か、設定済みのエイリアス(@/mailer.js など)で同じファイルを指定する。
エイリアスと相対パスが混在していても、同じファイルに解決されれば同じモジュールとして扱われる。

詳しくは公式の vi.mock / vi.hoisted(新しいタブで開く) に載っている。

よくある原因

  1. vi.mock が import より上へ移動するため、下に書いた変数を factory が参照できない。
  2. factory が import 解決時(変数宣言より前)に実行される。
  3. モックのパスが実際の import と一致していない。