ReactのテストでVitestのvi.mockを使う方法

​​React​React Testing Library,TypeScript,Vitest

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 から取ってきて表示するコンポーネントです。

ts
// 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();
}
tsx
// 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 に「これはモックだ」と伝えるための関数で、受け取ったものをそのまま返します。

tsx
// 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 になる

モックを変数に入れておき、ファクトリーの中で使いたくなることがあります。

tsx
const fetchUserMock = vi.fn();

vi.mock('./api', () => ({
  fetchUser: fetchUserMock,
}));

こう書くと、テストが1つも動かないまま、ファイルごと失敗しました。

text
 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 も先頭に移されるので、ファクトリーから使えます。

tsx
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 の下の行 → テストの順に出力されました。

テストファイルに書いた順と、実際に動く順。import、vi.hoisted、vi.mock、test の順に書いても、実際には vi.hoisted の中身、import の読み込み(このとき vi.mock のファクトリーが動く)、ファイルの本文、test の中身の順に動く。ふつうの const はファイルの本文でできるので、ファクトリーからは使えない
テストファイルに書いた順と、実際に動く順

今日の日付だけを差し替え、ほかの関数は本物を使う

次は、日付を扱うモジュールのうち、今日の日付を返す today() だけを固定します。日付の書式を作る formatDate() は本物のまま使います。

ts
// 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())}です`;
}
tsx
// src/TodayBanner.tsx
import { formatDate, today } from './date';

export function TodayBanner() {
  return <p>今日は{formatDate(today())}です</p>;
}

ファクトリーで today だけを返すと、formatDate を呼んだところで失敗しました。ファクトリーの戻り値が、モジュールのすべてになるためです。

text
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 の型が付きます。

tsx
// 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() を表示する次のコンポーネントをテストすると、失敗しました。

tsx
// src/TodayLabel.tsx
import { todayLabel } from './date';

export function TodayLabel() {
  return <p>{todayLabel()}</p>;
}

画面には、検証した日(2026年11月12日)がそのまま出ていました。

text
表示: 今日は2026年11月12日です

todayLabel() は、同じ date.ts の中の today() を直接呼んでいます。vi.mock が差し替えるのは、ほかのファイルが import したときに渡す today です。Vitest のガイドにある、モジュールのモックの注意点にも、同じファイルの中での呼び出しはモックできず、ファイルを分けるか、関数を引数で渡す形に書き直すよう書かれています。

canvas を使う default export のグラフ部品を差し替える

最後は、売上の合計を出し、SalesChart という部品で棒グラフを描く Dashboard です。SalesChart は canvas に描き、default export にしています。

tsx
// 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} />;
}
tsx
// 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 を返し、テストは失敗しました。

text
Not implemented: HTMLCanvasElement's getContext() method: without installing the @napi-rs/canvas npm package
...
TypeError: Cannot read properties of null (reading 'fillRect')

そこで ./SalesChart を差し替えます。ファクトリーで { SalesChart: ... } のように名前付きで返すと、次のエラーになりました。

text
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 も確かめられます。

tsx
// 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) を呼ぶと、次のように出力されました。

text
呼び出し回数: 0
返す値: { id: 1, name: 'たま' }

呼び出しの記録は消えていますが、戻り値は1つ目のテストのままです。Vitest 5.1.0 の設定の clearMocks は既定で true で、テストの前ごとに呼び出しの記録を消します。ただし、モックの中身(戻り値や実装)はそのまま残ります。

設定で mockReset を true にすると、テストの前ごとに中身も戻ります。同じ2つのテストで、2つ目の戻り値は undefined になりました。

ts
// 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日にするファクトリーは省きます)。

tsx
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() などで決めます。

​Posted by 86