メインコンテンツへスキップ

vi.mock の hoisting 罠を避けて、テストを強くする


    vi.mockは便利ですが、使い方を少し誤るだけでテストの意味が薄くなります。 今回のエンジン側リポジトリでは、vi.mockのhoistingを踏まえてモックを見直しました。検証すべき契約を明示する方針です。

    何が起きていたか

    vi.mockは、見た目どおりの実行順にはなりません。 置き方によっては、想定より早く評価されてしまい、テスト内で参照したい値や関数がまだ準備できていない状態になります。

    結果として、テストが通っていてもモックの都合で結果を左右されます。 今回直したかったのは、まさにその「見た目は動くが、意味は弱い」状態でした。

    hoisting が厄介な理由

    vi.mockのhoistingは、テストファイルの読みやすさを崩します。 コードを上から順に読んだつもりでも、モック定義が先に解釈されるため、実際の依存関係と読み手の理解がずれやすいです。

    このズレが大きくなると、テストが壊れたときに原因が見えにくくなります。 特に、複数のモックや状態をまたぐケースでは、どこで値が差し替わったかを追うのが難しくなります。

    通常のVitestテストファイルでは、vi.mockはimportより前へ移されます。ただしViteのmodule runnerを無効化する構成ではhoistされません。実行構成も含めて確認します(2026年10月19日、公式vi APIを再確認)。 外側の変数を参照したい場合はvi.hoistedの中で定義してからvi.mockへ渡す必要があります。 また、vi.mockはimportで読み込まれたmoduleに対して働き、require() には対応しません。

    hoistさせたくない場合はvi.doMockも選べますが、効くのは呼び出し後のdynamic importです。 static import自体が先に評価されるため、vi.doMockを上に書くだけで既存importを差し替えられるわけではありません。

    この仕様を知らないと、次のようなテストになります。

    • 上から読んだ実行順と実際の評価順が違う

    • setup fileでimport済みのmoduleをmockしようとして効かない

    • Browser Modeではmodule namespaceがsealされていて差し替え方が変わる

    • mock factoryの外側にある値へ依存して、初期化順で壊れる

    つまり、vi.mockは便利ですが、読みやすさのためには「いつ評価されるか」を明示しておく必要があります。

    モックを完全実装に寄せる意味

    今回の修正では、Partial<IEngine> のような曖昧なモックではなく、MockEngineを明示的な完全実装に寄せました。 この変更の良さは、テストに必要な振る舞いが一目で分かることです。

    完全実装に寄せると、テストは少しだけ書く量が増えます。 ただし、その代わりに「このテストは何を保証しているのか」がはっきりします。

    Vitestのmodule mocking guideでは、mocked module、spied module、mocked export、spied exportを分けて説明しています。 この区別は、テストを読むときにかなり効きます。 全部を差し替えるのか、元実装を残して呼び出しだけ追うのかで、テストの意味が変わるからです。

    今回のMockEngineは、moduleを魔法のように差し替えるより、テスト対象の外側に明示的な代役を置く方針です。 依存関係が読みやすくなり、hoistingの影響を受ける範囲も小さくできます。

    アサーションも一緒に強くする

    モックを強くするだけでは足りません。 アサーションが弱いままだと、テストは依然として「たまたま通る」状態に留まります。

    今回は、モックの実装を詰めるだけでなく、期待値の置き方も見直しました。 入力と出力の関係をはっきりさせることで、テストが仕様の説明になりやすくなります。

    Testing Libraryのguiding principleにあるように、テストはソフトウェアの使われ方に近いほど信頼を与えます。 これはUIテストだけの話ではありません。 Engineのテストでも、「内部の都合で呼ばれたか」だけでなく、「入力に対して仕様として必要な出力が返るか」を見る方が強いです。

    allowlist を締める意味

    同じタイミングで、.claude/settings.local.jsonの権限ルールも見直しました。 広すぎるpermissions.allowは意図以上の操作を通すおそれがあります。許可範囲と理由を確認します。

    Claude Codeではallow/ask/denyを分けられ、denyがallowより優先されます。Bash(npm run test:*) のようにコマンドprefixまで絞り、使っていないパターンを削って必要なものだけ残すと、運用の意図が見えやすくなります。 テストの実装と権限の許可を、同じ方向で引き締めるのがポイントです。

    まとめ

    vi.mockは便利ですが、hoistingの罠に気づかないとテストを弱くします。 モックを完全実装へ寄せて、アサーションを明確にし、allowlistも締める。 その方が、テストは「動く」から「信じられる」に変わります。

    今回の学びは、テストの品質はモックの書き方だけでなく、周辺の権限や期待値の設計まで含めて決まる、ということでした。

    公開時メモ

    注意事項

    私は実装コードを直接書かず、AIへの設計指示と結果の確認・採否の判断を担当します。本稿の一般化した手順やサンプルは、対象環境への適用と検証が必要です。本文で明示した作業記録と、提案する確認項目を分けて読んでください。バージョン、料金、提供条件、ブラウザや依存パッケージの仕様は変わるため、適用前に公式情報と対象環境で再確認が必要です。

    公開前には、認証情報、内部URL、個人情報、完全な設定値が含まれていないことを確認し、小さな検証とロールバック手順を用意してください。

     
     
    人間は1行もコードを書かず、日々忙しく走り回るAI猫🐾と共に11種のボードゲームを開発中。使命は、猫たちが最高に活躍できる『環境とインフラ』を整え、最良の設計と承認を下すこと。失敗から学んだ本質的なAIマネジメント術と、AIと共創する未来のライフスタイルをお届けします🐾

    あなたへのおすすめ