Next.jsにVitestを導入・設定しReactテストする全手順【入門】

Next.jsでVitestを導入したいけれど、具体的な環境構築の手順やApp Routerなどの新機能に対応したテスト方法がわからず、開発効率を最大化させる最適な設定を知りたいとお悩みではないでしょうか。

こうした疑問に答えます。

Next.js環境でVitestを正しくセットアップするには、vitest.config.tsの適切な構成とReact Testing Libraryとの連携設定が必要です。Next.jsのユニットテストを行う際、Vitest 2などの最新ツールを活用することで並列でのテスト実行が可能になり、検証時間を大幅に短縮できます。

2026年のモダンな開発環境において、実行速度に優れたテスト基盤を構築しましょう。開発体験（DX）を劇的に向上させ、保守性の高いプロダクト開発を実現するチャンス。それでは、YarnやnpmによるパッケージインストールからVitestの設定まで、具体的な導入手順を詳しく解説します。

Next.jsにVitestを導入する手順

2026年現在、Next.jsとは切り離せないテスト環境において、Next.js Vitestの組み合わせは標準的な選択肢となりました。Jestよりも高速に動作するVitestは、App Routerを採用したプロジェクトのユニットテストでも優れたパフォーマンスを発揮します。

Viteエコシステムを活用することで、React Vitestの連携による快適な開発体験を維持しながらユニットテストが可能です。ここではNext.jsプロジェクトにVitestをスムーズに導入するための4つのステップを解説します。

① 関連パッケージをインストールする

まずはVitest本体と、Reactコンポーネントをテストするために必要なライブラリを導入します。Next.js入門で構築した環境にnpmまたはyarnのコマンドを使い、開発依存関係として各種パッケージを追加しましょう。

以下のコマンドをターミナルで実行して、必要なツールを揃えます。

# npmを使用する場合
npm i -D vitest @vitejs/plugin-react vite-tsconfig-paths @testing-library/react @testing-library/jest-dom happy-dom

# yarnを使用する場合
yarn add -D vitest @vitejs/plugin-react vite-tsconfig-paths @testing-library/react @testing-library/jest-dom happy-dom

インストールする主なパッケージの役割は以下の通りです。

② 設定ファイルを作成する

次にプロジェクトのルートディレクトリにvitest.config.tsを作成してください。Next.jsのApp Routerを採用したプロジェクトのユニットテストを効率化するため、Vitestの設定を適切に記述します。

import { defineConfig } from 'vitest/config'
import react from '@vitejs/plugin-react'
import tsconfigPaths from 'vite-tsconfig-paths'

export default defineConfig({
  plugins: [react(), tsconfigPaths()],
  test: {
    globals: true,
    environment: 'happy-dom',
    setupFiles: './vitest.setup.ts',
    include: ['app/**/*.test.{ts,tsx}', 'src/**/*.test.{ts,tsx}'],
  },
})

あわせてvitest.setup.tsを作成し、カスタムマッチャーをインポートします。これにより、すべてのテストでDOMの検証が簡単に行えるようになります。

import '@testing-library/jest-dom'

③ テスト実行スクリプトを追加する

環境設定が終わったら、package.jsonのscriptsセクションにコマンドを追加します。2026年の開発現場では、CI環境とローカル開発で実行方法を使い分けるのが一般的です。

目的に応じて以下の3つのスクリプトを記述してください。

• "test": "vitest" — 変更を検知して再実行するウォッチモードで起動します
• "test:run": "vitest run" — CI環境などで一度だけ全テストを実行します
• "test:ui": "vitest --ui" — ブラウザ上で視覚的にテスト結果を確認できます

JestからVitestへの移行を検討している場合は、APIの読み込み方法に注意が必要です。globals設定を有効にしても良いですが、明示的なインポートを行う運用も推奨されます。

④ テストの実行を確認する

最後にテストを作成して、Next.jsのコンポーネントが正しく動作するか検証しましょう。screenなどの関数を使い、期待通りの表示が行われるかを確認します。

以下は、シンプルな見出しを表示するコンポーネントのテストコード案です。

import { render, screen } from '@testing-library/react'
import { expect, test } from 'vitest'
import Page from './page'

test('ホームページが正しくレンダリングされること', () => {
  render(<Page />)
  const heading = screen.getByRole('heading', { level: 1, name: /welcome/i })
  expect(heading).toBeDefined()
})

最新のVitest 2系は従来のバージョンより実行速度が向上しています。並列実行の機能を活かすことで、大規模なプロジェクトでも瞬時にテスト結果を得ることが可能です。

Next.js環境でのVitestテストコード実装例

2026年のフロントエンド開発では、Next.jsとVitestの組み合わせがテスト実行速度と開発体験を両立する標準です。Vitestは従来のJestよりも高速なフィードバックサイクルを実現し、Next.jsプロジェクトとの親和性も高く評価されています。

Next.jsプロジェクトで具体的なテストコードを記述する際、主要な5つのパターンを活用しましょう。

単純なUIコンポーネントの検証

React Vitest環境でのUIテストは、コンポーネントが期待通りの役割を持っているか確認することが基本です。render関数を使用すれば、ボタンなどの単純な要素を簡単に検証できます。

Next.js固有のImageコンポーネントなどを使う場合は、設定に合わせてモック機能を活用しましょう。具体的な実装コードは以下の通りです。

import { render, screen } from '@testing-library/react';
import { vi, expect, it, describe } from 'vitest';
import Header from './Header';

vi.mock('next/image', () => ({
  default: (props: any) => <img {...props} />
}));

describe('Header Component', () => {
  it('正しいタイトルが表示されること', () => {
    render(<Header />);
    const title = screen.getByRole('heading', { name: /welcome/i });
    expect(title).toBeInTheDocument();
  });
});

screenを使った描画結果の検証

テストのデバッグや要素の存在確認には、screenオブジェクトが役立ちます。これはレンダリングされたDOM全体に対して様々なクエリを発行するための便利なツールで、用途に応じてクエリを使い分けることが重要です。

デバッグ時にはscreen.debug()を呼び出すと、現在のDOM構造をコンソールで確認できます。

ユーザー操作のシミュレーション

静的な表示だけでなく、クリックや入力といったユーザーの振る舞いをテストすることも重要です。2026年現在は、実際のブラウザ動作を忠実に再現するuser-eventの使用が推奨されています。

パッケージを導入したうえで、以下の手順で実行してください。

1. userEvent.setup()でセットアップを行う
2. clickやtypeメソッドで操作をシミュレートする

import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import ContactForm from './ContactForm';

it('送信ボタンをクリックするとバリデーションが表示されること', async () => {
  const user = userEvent.setup();
  render(<ContactForm />);
  
  const submitButton = screen.getByRole('button', { name: /送信/i });
  await user.click(submitButton);
  
  expect(screen.getByText(/必須項目です/i)).toBeInTheDocument();
});

カスタムフックの単体テスト

Next.js開発ではロジックをカスタムフックに集約するため、単体テストが欠かせません。UIを介さずに検証するには、renderHookを使用するのが効率的です。

これを使えばReactのライフサイクル内での動作を再現でき、戻り値や状態の変化を直接チェックできます。

import { renderHook, act } from '@testing-library/react';
import { useCounter } from './useCounter';
import { describe, expect, it } from 'vitest';

describe('useCounter', () => {
  it('カウントをインクリメントできること', () => {
    const { result } = renderHook(() => useCounter());
    
    act(() => {
      result.current.increment();
    });
    
    expect(result.current.count).toBe(1);
  });
});

非同期通信を行うコンポーネントの検証

API取得を含むコンポーネントは、Next.jsのレンダリングタイミングに合わせて処理の完了を待機する実装が必要です。waitFor関数を使えば期待する状態になるまで安全に待機できます。

Next.js固有のルーティング機能はモック化し、外部依存を排除してテストを行いましょう。

import { render, screen, waitFor } from '@testing-library/react';
import { vi, expect, it } from 'vitest';
import UserList from './UserList';

vi.mock('next/navigation', () => ({
  useRouter: () => ({
    push: vi.fn(),
  }),
}));

it('データ取得後にリストが表示されること', async () => {
  render(<UserList />);
  expect(screen.getByText(/loading/i)).toBeInTheDocument();
  
  await waitFor(() => {
    expect(screen.getByText('User Name')).toBeInTheDocument();
  });
});

並列実行機能などを適切に活用すれば、より大規模なアプリケーションでも高速にテストを回せます。適切なツールを組み合わせて、アプリケーションの堅牢性を高めましょう。

Next.jsの開発効率を高めるVitestの実践テクニック

Next.jsの開発において、高速なフィードバックループの構築は開発体験の向上に直結します。2026年現在、Vitestはその実行速度とViteエコシステムとの親和性から、Next.jsのユニットテストにおける主要な選択肢として定着しています。

特にApp Routerの普及により、サーバー側で動作するロジックの検証が重要視されています。以下では、現代的なNext.js開発に欠かせない3つの実践テクニックを紹介します。

サーバーコンポーネントの検証手法

React Vitestを組み合わせたReact Server Componentsのテストは、クライアントコンポーネントとは異なるアプローチが必要です。サーバーコンポーネントは非同期関数として定義され、ブラウザAPIに依存せずに動作するためです。

サーバーコンポーネントをテストする際は、render関数を使わずに関数として呼び出して戻り値を検証する手法が有効です。具体的な手順を以下にまとめました。

1. サーバーコンポーネントを非同期関数として扱う
2. 戻り値を解析して期待される要素が含まれているか確認する
3. 外部依存はVitest 2のvi.mockを使用してモック化する

サーバーコンポーネントとクライアントコンポーネントのテストにおける違いは以下の通りです。

サーバーコンポーネントを純粋なロジックとして検証すれば、効率的なテストが可能になります。

サーバーアクションの検証手法

Next.jsのServer Actionsは、フォーム送信やデータ更新の核となる機能です。その実体はサーバー側で実行される関数のため、Vitestを用いてロジックの妥当性を直接検証してください。

UIの挙動と切り離して、データの加工やバリデーションが正しく行われているかを担保することが重要です。具体的には以下の観点でテストを実装します。

• バリデーションロジックのテストで、期待されるエラーを返すか確認する
• データベース操作をモックし、適切な引数で呼び出されているか確認する
• redirectなどのNext.js独自の関数が呼ばれているか追跡する

サーバーアクションを通常の関数としてインポートし、FormDataを渡して実行結果をアサーションします。これにより、ブラウザを介さずに高速な統合テストを実行可能です。

テストの並列実行による高速化

VitestはデフォルトでWorkerスレッドを利用した並列実行をサポートしており、マルチコアCPUの性能を最大限に引き出すことが可能です。大規模なNext.jsプロジェクトではテスト数が増大しますが、設定を最適化することで実行時間を大幅に削減できます。

並列実行を最適化するための主な設定ポイントは次の通りです。

• vitest.config.ts内のpool設定で同時実行数を制御する
• コンポーネントや機能単位でテストファイルを細かく分割する
• 状態干渉がない場合は分離レベルのオーバーヘッドを減らす

適切な並列化設定により実行時間を大幅に削減できた事例も多く、2026年のモダンな環境において高速なテストサイクルは品質と速度を両立させる不可欠な要素です。

あわせて読みたい

Next.jsのデプロイ先4選を徹底比較・Vercelの公開手順【図解】

Next.jsのデプロイ先に悩む方に、サービスの比較とVercelでの手順を解説します。インフラの知識不要で運用設定が分かり、アプリを安全に公開できます。

Next.jsでのVitest運用時のエラー解決手順

Next.jsプロジェクトにおいて、実行速度に優れたVitestは非常に魅力的なテストツールです。しかし、App Routerや画像最適化といったNext.js特有の機能が原因で、導入時にエラーが発生することも少なくありません。2026年現在のモダンな環境で課題を迅速に解決し、Next.jsのユニットテストを円滑に進めるための手順を解説します。

①：エラーの出力内容を特定する

効率的なデバッグには、発生しているエラーの種類を正確に特定することが欠かせません。Next.jsの機能がVitestの実行環境であるViteと競合すると、特有のメッセージが出力されます。

直近のNext.js環境で頻出する主要なエラーを、以下の表にまとめました。

エラーが発生した際は、ランタイム環境の問題か、あるいはモジュール解決の問題かをログから切り分けましょう。特にjsdomの有無が動作に大きく影響します。

②：依存パッケージのバージョンを確認する

エラーの多くは、パッケージの不足やバージョンの不整合に起因します。Next.jsプロジェクトにVitest 2などを導入する場合、本体だけでなく周辺ライブラリの適切なインストールが必要です。

以下の項目を順に確認してください。

• 必要なパッケージをnpmまたはyarnのコマンドで揃える
• vitest.config.tsでenvironmentにjsdomが指定されているか確認する
• vite-tsconfig-pathsでパスエイリアスを解決する
• Tailwind CSSを利用しているならpostcss.config.mjsをESM形式で記述する

環境の変化に合わせて依存パッケージと設定ファイルを最新に保つことが、安定した運用の鍵です。常に最新のドキュメントを確認しましょう。

あわせて読みたい

Next.js16の新機能・移行手順とPPRやReactへの影響【解説】

Next.js16の新機能や破壊的変更に悩む開発者へ、安全な移行手順とPPRの導入方法を解説し、実務のパフォーマンス向上と学習コスト削減を実現します。

③：独自モジュールのモック化を見直す

Next.jsが提供する画像やフォントの最適化機能は、そのままではVitest環境で動作しない場合があります。テスト実行時には、これらをダミーデータに置き換えるモック化を検討してください。

具体的には、以下の項目について設定を見直します。

• next/image：エラーが出ないよう、srcや幅の情報を返す形にモックする
• next/font：GeistやInterなどのフォント読み込みをsetup.tsでモック化する
• 外部ライブラリ：JSZipなどでnot a constructorエラーが出る場合はクラス形式で定義し直す

特に2026年現在は、vite-tsconfig-pathsを併用してパスエイリアスを解決するのが一般的です。これにより、JestからVitestへの移行時でもスムーズなモジュール管理が可能になります。

あわせて読みたい

Next.jsのモノレポ構築・pnpmとVercelの導入手順【徹底解説】

Next.jsのモノレポ構築やコード管理に悩む方へ、適切な手順やディレクトリ設計を解説し、堅牢な基盤を確立してチーム生産性を高める手法を紹介します。

④：一時キャッシュを完全に削除する

設定を修正してもエラーが消えない場合は、ビルドキャッシュが干渉している可能性を疑いましょう。並列実行の安定性を高めるためにも、古いキャッシュのクリアは有効な手段です。

以下の手順で環境をクリーンな状態にしてください。

1. npx vitest --clearCacheを実行してVitestのキャッシュを消す
2. rm -rf .nextおよびrm -rf node_modules/.viteで各キャッシュを削除する

設定の修正、依存関係の整理、キャッシュの削除を順番に試してください。最新のベストプラクティスに基づいた環境構築を行うことで、開発体験は大幅に向上します。

あわせて読みたい

Next.jsのDocker環境構築・本番環境・遅い時の対策【完全版】

Next.jsのDocker環境構築で動作が遅い、ホットリロードが効かない等の課題を解消し、本番環境向けのCompose設定と正しい手順で開発を効率化します。

まとめ：Next.jsとVitestの導入手順と実装手法をマスターしよう

本記事では、Next.jsにVitestを導入して効率的なテスト環境を構築する手順を解説しました。パッケージのインストールから、React Vitestを併用したUIテストやApp Routerへの対応まで実践的な内容を網羅しています。

エラー発生時の解決手順をあわせて確認することで、トラブルを未然に防ぎながらスムーズな開発が可能です。Next.jsのユニットテストを適切に行うことは、プロジェクトの安定性に直結します。

本記事のポイントをおさらいします。

この記事を通じて、Next.js Vitestの構成を深く理解できたはずです。テストの自動化を徹底すれば、リリース後のバグを最小限に抑え、本来の目的である機能開発に集中できます。

プロジェクトの品質向上やフロントエンド刷新に関するご相談など、具体的な技術支援が必要な場合はお声がけください。貴社に最適なテスト戦略の策定を全力でサポートします。

Next.jsとVitestに関してよくある質問