ReactのテストでVitestのvi.mockを使う方法
Vitest の vi.mock を使うと、コンポーネントが import しているモジュールを、テストの間だけモック(偽物)に差し替えられます。fetch で API を呼ぶ関数を偽物にしてサーバーなしで画面を確かめる、今日の日付を固定する、jsdom では動かない canvas のグラフ部品を外す、といった場面で使います。
この3つを順に差し替えながら、つまずきやすいエラーと、その直し方を確かめました。
検証環境は Ubuntu 24.04、Node.js 22.23.4 です。使ったのは vitest 5.1.0、jsdom 31.0.0、@testing-library/react 16.3.3、@testing-library/jest-dom 7.0.1、react / react-dom 19.3.1、typescript 7.0.2 です。Vitest の設定は environment: 'jsdom' にし、setup ファイルで @testing-library/jest-dom/vitest を読み込んでいます。__mocks__ フォルダを使う差し替え、Vitest のブラウザーモード、Jest は試していません。
API を呼ぶ関数を、ファクトリーで偽物にする
テストするのは、ユーザーの名前を API から取ってきて表示するコンポーネントです。
// src/api.ts
export type User = { id: number; name: string };
export async function fetchUser(id: number): Promise<User> {
const res = await fetch(`https://api.example.com/users/${id}`);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
return res.json();
}
// src/UserCard.tsx
import { useEffect, useState } from 'react';
import { fetchUser, type User } from './api';
export function UserCard({ id }: { id: number }) {
const [user, setUser] = useState<User | null>(null);
const [error, setError] = useState(false);
useEffect(() => {
fetchUser(id).then(setUser, () => setError(true));
}, [id]);
if (error) return <p role="alert">読み込めませんでした</p>;
if (!user) return <p>読み込み中…</p>;
return <p>こんにちは、{user.name}さん</p>;
}
テストでは、vi.mock の2つ目の引数に、差し替えたあとのモジュールを返す関数(ファクトリー)を渡します。fetchUser を vi.fn() にしておき、テストごとに vi.mocked() を通して戻り値を決めます。vi.mocked は、TypeScript に「これはモックだ」と伝えるための関数で、受け取ったものをそのまま返します。
// src/UserCard.test.tsx
import { render, screen } from '@testing-library/react';
import { expect, test, vi } from 'vitest';
import { fetchUser } from './api';
import { UserCard } from './UserCard';
vi.mock('./api', () => ({
fetchUser: vi.fn(),
}));
test('名前を表示する', async () => {
vi.mocked(fetchUser).mockResolvedValue({ id: 1, name: 'たま' });
render(<UserCard id={1} />);
expect(await screen.findByText('こんにちは、たまさん')).toBeInTheDocument();
expect(fetchUser).toHaveBeenCalledWith(1);
});
test('失敗したらエラーを表示する', async () => {
vi.mocked(fetchUser).mockRejectedValue(new Error('HTTP 500'));
render(<UserCard id={2} />);
expect(await screen.findByRole('alert')).toHaveTextContent('読み込めませんでした');
});
2つのテストはどちらも通りました。vi.mock は import の下に書いていますが、UserCard が読み込む ./api も偽物になっています。
ファクトリーで外の変数を使うと、ReferenceError になる
モックを変数に入れておき、ファクトリーの中で使いたくなることがあります。
const fetchUserMock = vi.fn();
vi.mock('./api', () => ({
fetchUser: fetchUserMock,
}));
こう書くと、テストが1つも動かないまま、ファイルごと失敗しました。
FAIL src/pitfall-outer-var.test.tsx [ src/pitfall-outer-var.test.tsx ]
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
Caused by: ReferenceError: Cannot access 'fetchUserMock' before initialization
vi.mock の説明にあるとおり、vi.mock はファイルの先頭に移され、どの import よりも先に呼ばれます。そのためファクトリーは、UserCard が ./api を読み込むときに動き、const fetchUserMock の行はまだ実行されていません。
外の変数を使いたいときは、その変数を vi.hoisted の中で作ります。vi.hoisted も先頭に移されるので、ファクトリーから使えます。
const { fetchUserMock } = vi.hoisted(() => ({
fetchUserMock: vi.fn(),
}));
vi.mock('./api', () => ({
fetchUser: fetchUserMock,
}));
test('vi.hoisted で作ったモックを使う', async () => {
fetchUserMock.mockResolvedValue({ id: 1, name: 'たま' });
render(<UserCard id={1} />);
expect(await screen.findByText('こんにちは、たまさん')).toBeInTheDocument();
expect(fetchUserMock).toHaveBeenCalledWith(1);
});
このテストは通りました。動く順を確かめるため、vi.hoisted の中、ファクトリーの中、import の下に書いた行、テストの中に console.log を入れて実行すると、vi.hoisted → ファクトリー → import の下の行 → テストの順に出力されました。

今日の日付だけを差し替え、ほかの関数は本物を使う
次は、日付を扱うモジュールのうち、今日の日付を返す today() だけを固定します。日付の書式を作る formatDate() は本物のまま使います。
// src/date.ts
export function today(): Date {
return new Date();
}
export function formatDate(d: Date): string {
return `${d.getFullYear()}年${d.getMonth() + 1}月${d.getDate()}日`;
}
// 同じファイルの today() を中で呼ぶ
export function todayLabel(): string {
return `今日は${formatDate(today())}です`;
}
// src/TodayBanner.tsx
import { formatDate, today } from './date';
export function TodayBanner() {
return <p>今日は{formatDate(today())}です</p>;
}
ファクトリーで today だけを返すと、formatDate を呼んだところで失敗しました。ファクトリーの戻り値が、モジュールのすべてになるためです。
Error: [vitest] No "formatDate" export is defined on the "./date" mock. Did you forget to return it from "vi.mock"?
If you need to partially mock a module, you can use "importOriginal" helper inside:
...
エラーの案内のとおり、ファクトリーが受け取る importOriginal で本物のモジュールを読み込み、...original で展開してから today だけを上書きします。パスを import('./date') の形で渡すと、importOriginal() の戻り値に ./date の型が付きます。
// src/TodayBanner.test.tsx
import { render, screen } from '@testing-library/react';
import { expect, test, vi } from 'vitest';
import { TodayBanner } from './TodayBanner';
vi.mock(import('./date'), async (importOriginal) => {
const original = await importOriginal();
return {
...original,
today: vi.fn(() => new Date(2030, 0, 1)),
};
});
test('today() だけを差し替え、formatDate() は本物を使う', () => {
render(<TodayBanner />);
expect(screen.getByText('今日は2030年1月1日です')).toBeInTheDocument();
});
このテストは通りました。
同じファイルの中で呼ぶ関数は、差し替わらない
同じ差し替え方で、todayLabel() を表示する次のコンポーネントをテストすると、失敗しました。
// src/TodayLabel.tsx
import { todayLabel } from './date';
export function TodayLabel() {
return <p>{todayLabel()}</p>;
}
画面には、検証した日(2026年11月12日)がそのまま出ていました。
表示: 今日は2026年11月12日です
todayLabel() は、同じ date.ts の中の today() を直接呼んでいます。vi.mock が差し替えるのは、ほかのファイルが import したときに渡す today です。Vitest のガイドにある、モジュールのモックの注意点にも、同じファイルの中での呼び出しはモックできず、ファイルを分けるか、関数を引数で渡す形に書き直すよう書かれています。
canvas を使う default export のグラフ部品を差し替える
最後は、売上の合計を出し、SalesChart という部品で棒グラフを描く Dashboard です。SalesChart は canvas に描き、default export にしています。
// src/SalesChart.tsx
import { useEffect, useRef } from 'react';
// canvas に棒グラフを描く(jsdom では canvas が使えない)
export default function SalesChart({ values }: { values: number[] }) {
const ref = useRef<HTMLCanvasElement>(null);
useEffect(() => {
const ctx = ref.current!.getContext('2d')!;
values.forEach((v, i) => ctx.fillRect(i * 20, 100 - v, 16, v));
}, [values]);
return <canvas ref={ref} width={300} height={100} />;
}
// src/Dashboard.tsx
import SalesChart from './SalesChart';
export function Dashboard({ values }: { values: number[] }) {
const total = values.reduce((a, b) => a + b, 0);
return (
<section>
<h2>今週の売上</h2>
<p>合計 {total} 件</p>
<SalesChart values={values} />
</section>
);
}
本物の SalesChart のまま Dashboard を描画すると、jsdom の getContext() が null を返し、テストは失敗しました。
Not implemented: HTMLCanvasElement's getContext() method: without installing the @napi-rs/canvas npm package
...
TypeError: Cannot read properties of null (reading 'fillRect')
そこで ./SalesChart を差し替えます。ファクトリーで { SalesChart: ... } のように名前付きで返すと、次のエラーになりました。
Error: [vitest] No "default" export is defined on the "./SalesChart" mock. Did you forget to return it from "vi.mock"?
default export は、ファクトリーでは default という名前で返します。vi.mock の説明にも、default export があるモジュールでは default のキーが要ると書かれています。偽物の部品を vi.fn() で包んでおくと、渡された props も確かめられます。
// src/Dashboard.test.tsx
import { render, screen } from '@testing-library/react';
import { expect, test, vi } from 'vitest';
import { Dashboard } from './Dashboard';
import SalesChart from './SalesChart';
vi.mock('./SalesChart', () => ({
default: vi.fn(({ values }: { values: number[] }) => (
<div data-testid="sales-chart">{values.join(',')}</div>
)),
}));
test('合計を表示し、グラフに数を渡す', () => {
render(<Dashboard values={[3, 5, 2]} />);
expect(screen.getByText('合計 10 件')).toBeInTheDocument();
expect(screen.getByTestId('sales-chart')).toHaveTextContent('3,5,2');
expect(SalesChart).toHaveBeenCalledTimes(1);
expect(vi.mocked(SalesChart).mock.calls[0][0]).toEqual({ values: [3, 5, 2] });
});
このテストは通りました。
前のテストで決めた戻り値は、次のテストに残る
vi.mocked(...).mockResolvedValue() で決めた戻り値は、そのテストが終わっても消えません。1つ目のテストで「たま」を返すように決め、2つ目のテストでは何も決めずに fetchUser(2) を呼ぶと、次のように出力されました。
呼び出し回数: 0
返す値: { id: 1, name: 'たま' }
呼び出しの記録は消えていますが、戻り値は1つ目のテストのままです。Vitest 5.1.0 の設定の clearMocks は既定で true で、テストの前ごとに呼び出しの記録を消します。ただし、モックの中身(戻り値や実装)はそのまま残ります。
設定で mockReset を true にすると、テストの前ごとに中身も戻ります。同じ2つのテストで、2つ目の戻り値は undefined になりました。
// vitest.config.ts
import { defineConfig } from 'vitest/config';
export default defineConfig({
test: {
environment: 'jsdom',
setupFiles: ['./src/setup.ts'],
mockReset: true,
},
});
モック関数の mockReset() の説明によると、vi.fn(impl) のように実装を渡して作ったモックは、空の関数ではなく、その impl に戻ります。日付の例で、ファクトリーの vi.fn(() => new Date(2030, 0, 1)) を、1つ目のテストだけ mockReturnValue() で7月7日に変えました(import と、today を2030年1月1日にするファクトリーは省きます)。
test('1つ目:このテストだけ別の日にする', () => {
vi.mocked(today).mockReturnValue(new Date(2030, 6, 7));
render(<TodayBanner />);
expect(screen.getByText('今日は2030年7月7日です')).toBeInTheDocument();
});
test('2つ目:何も決めない', () => {
render(<TodayBanner />);
console.log('表示:', screen.getByRole('paragraph').textContent);
});
2つ目のテストで何も決めずに描画すると、既定の設定では「今日は2030年7月7日です」が残り、mockReset: true では「今日は2030年1月1日です」に戻りました。
どのテストでも使う既定の動きは、ファクトリーの vi.fn() に実装として渡します。テストごとに変えたい値は、そのテストの中で mockReturnValue() などで決めます。





