Vitest のモック（vi.fn, vi.spyOn, vi.mock）の使い分けについて【株式会社ライトコード】

背景

Vitest でテストを書く際、公式ドキュメントを見るとモックに関するユーティリティが多数存在し、最初はどれを使うべきか悩んでしまいます。
この記事では、テストができれば良いという状態から、テストの目的に合わせたモックユーティリティの使い分けができるような状態へのステップアップを目指します。

ゴール

vi.fn,vi.spyOn,vi.mockのそれぞれの特徴と適した用途を理解する
実際のサンプルコードを通して、実践的な使い分け方や注意点を学ぶ

環境

vitest: 3.0.8
jsdom: 26.0.0

用語の確認

ソフトウェアテストで用いる一般的なモックに関する用語の定義を確認します。

スタブ: 関数の実装をテスト用に置き換える機能
スパイ: スタブ + 関数の呼び出しや引数などを監視する機能
モック: スパイ + 自身の検証を行う機能

3 つの用語の関係性は、スタブ < スパイ < モックという包含関係になっているようです。

参考

補足：広義のモック

今回調査してわかったのは、狭義のモックと広義のモックがある、ということです。多くの場合、「モック」という言葉が指すのは「テストする際に都合の悪い処理を都合の良い処理にする」くらいの概念として語られていることが多いです。先に紹介したモックの定義を「狭義のモック」とするなら、このようなモックを「広義のモック」と言えるかと思います。
実際、Vitest の文脈において「モック」という言葉が使われるときは、広義のモックを指しているように思われます。この記事でも、モックという言葉を使用しますが、広義のモックとして捉えてください。

Vitest におけるモック

3 つのモックユーティリティ

Vitest のドキュメントを見るとモックユーティリティの数に圧倒されますが、実際にはvi.fn,vi.spyOn,vi.mockの 3 つを押さえておけば、多くのテストケースに対応できるかと思います。
また、これらは「用語の確認」で確認した、スタブ、スパイ、モックといった機能では分類されておらず、3 つとも「スパイ」の機能を持ちます。
そのため、それぞれの違いについては、モックをする対象が何なのか、に着目するとわかりやすいです。

vi.fn: モック関数を作成し、関数をモックする
vi.spyOn: オブジェクトのメソッドをモックする
vi.mock: モジュール全体をモックする

各モックユーティリティの具体的な使いどころ

vi.fn: コールバック関数をモック

vi.fnの使いどころとしては、以下のようなコールバック関数の呼び出しを確認したい場合が考えられます。

// Button.test.tsx

import { render, screen } from "@testing-library/react"

import userEvent from "@testing-library/user-event"

import { Button } from "./Button"



test("送信ボタンのクリック時に、クリックイベントに指定したコールバック関数が呼び出される", async () => {

  const user = userEvent.setup() // userEventのインスタンスを作成

  const handleClickMock = vi.fn() // vi.fnでモック関数を作成

  render(<Button onClick={handleClickMock}>送信</Button>) // 作成したモック関数をイベントハンドラとして仕込む



  await user.click(screen.getByRole("button", { name: "送信" })) // 送信ボタンのクリックを再現



  expect(handleClickMock).toHaveBeenCalled() // 呼び出しを確認

})