近年、フロントエンドやバックエンドの JavaScript / TypeScriptTypeScript [タイプスクリプト]JavaScriptに型システムを追加した言語 プロジェクトにおいて、高速なビルドツールである ViteVite [ヴィート]フランス語の「速い」が由来の、高速な開発環境を提供するフロントエンドビルドツール の普及とともに広く採用されているテストフレームワークが Vitest です。
従来の Jest は多機能で標準的なフレームワークとして長年親しまれてきましたが、TypeScript のトランスパイルや ESM(ECMAScript Modules)の設定で手こずることが少なくありませんでした。Vitest は Vite の設定やプラグインエコシステムを共有できるため、設定コストを抑えながら効率的にテストを実行できます。
本記事では、Vitest の基本的な特徴や導入手順、最小限のテストコードの書き方から、モック機能やアンチパターン対策までを実機検証の結果を交えて詳しく解説します。
Vitestとは?Jestとの主な違い
Vitest は、Vite をベースにした単体テストフレームワークです。
Jest と互換性の高い APIAPI [エーピーアイ]Application Programming Interface。異なるソフトウェア間の接続口(describe、it、expect、vi.fn() など)を備えているため、既存の Jest 利用者も比較的少ない学習コストで利用できます。ただし完全互換ではないため、Jest 固有の機能やモジュールモックの挙動などは移行時に調整が必要になる場合があります。
主な違いとメリット
Jest と Vitest の主な違いを比較表に整理しました。
| 項目 | Jest | Vitest |
|---|---|---|
| ベース設計 | 独自のテスト実行基盤 | Vite のモジュール解決・変換処理を利用 |
| 設定の共通化 | jest.config.js 等で別途管理 | vite.config.ts と設定やプラグインを共有可能 |
| TypeScript対応 | トランスパイル設定が必要になるケースがある | 標準で TypeScript を実行可能(型チェックは別途必要) |
| ESMサポート | ESM 利用には設定が必要になるケースがある | ESM を前提とした設計で、標準的な ESM 環境を扱いやすい |
| 実行速度 | プロジェクトの構成や設定によって異なる | Vite のモジュールグラフを活用し、変更に関連するテストを効率的に再実行 |
| モックAPI | jest.fn()、jest.spyOn() | vi.fn()、vi.spyOn()(互換性の高いAPI) |
Vite を採用しているプロジェクトであれば、Vitest を導入することでビルドツールとテスト基盤の設定やプラグインを共有でき、設定の二重管理を避けやすくなります。ただし、実際の導入にあたっては以下の点に注意してください。
- CommonJS との互換性: Vitest は ESM を前提に設計されていますが、CommonJS の
require()を用いたモジュール読み込みでは Vite のエイリアスや変換処理、モックが適用されないケースがあります。 - 実行速度の考え方: Vitest の Watch モードはブラウザ向け HMR そのものでテストを実行しているわけではなく、Vite のモジュールグラフをもとに影響を受けるテストを特定して再実行しています。また、実行速度はプロジェクトの規模やテスト内容、並列実行の設定によって変わるため、常に Jest より高速になるとは限りません。
- TypeScript の型チェック: Vitest は TypeScript のテストコードをトランスパイルしてそのまま実行できますが、トランスパイルと型チェックは別の処理です。通常のテスト実行だけではすべての型エラーを検出するわけではないため、CI や開発フローの中で
npx tsc --noEmitなどを別途実行することが推奨されます。
また、Node.js スクリプトを自作して自動化する基礎については Node.jsでコマンドライン引数を取得する方法 でも詳しく解説しています。

Node.js(JavaScript)でコマンドライン引数を取得する
Node.jsでコマンドライン引数を取得する場合は、processオブジェクトのprocess.argvプロパティを参照します。インデックスの1つ目がnodeコマンド、2つ目がjsファイル名で、3つ目以降からコマンドライン引数を参照することができます。
確認した環境
本記事のコード例および実行結果は、以下の環境で検証しています。
| 項目 | バージョン / 詳細 |
|---|---|
| OSOS [オーエス]Operating System。基本ソフトウェア | LinuxLinux [リナックス / ライナックス]オープンソースのOSカーネル(UbuntuUbuntu [ウブントゥ]人気のLinuxディストリビューション 22.04 LTS) |
| Node.js | v18.17.1 |
| npmnpm [エヌピーエム]Node Package Manager。Node.js用のデフォルトのパッケージ管理システム | 9.6.7 |
| Vitest | v1.6.1 |
※ 本記事では Vitest v1.6.1 を使用して検証しています。Vitest はバージョンによって要求される Node.js や Vite のバージョンが異なります。なお、2026年11月時点の最新版である Vitest 5 系では Node.js 22.12.0 以上・Vite 6.4.0 以上 が要件となっており、旧バージョンの v1.x 系はサポート対象外です。新規に最新版を導入する場合は、Vitest 公式ドキュメントで最新の動作要件を確認してください。
Vitestの導入とセットアップ
まずはプロジェクトに Vitest をインストールし、テスト実行コマンドを設定します。
インストール手順
本記事の検証環境(Vitest v1.6.1)と同じ条件で動作を確認する場合は、プロジェクトルートでバージョンを指定して開発用依存関係に追加します。
npm install -D --save-exact vitest@1.6.1※ 新規プロジェクトで最新版の Vitest を導入する場合は npm install -D vitest を実行してください(前述のとおり、最新版では対応する Node.js や Vite のバージョン要件が異なります)。
package.jsonの設定
package.json の scripts フィールドに、テスト実行用のスクリプトを追加します。
{ "name": "vitest-demo", "version": "1.0.0", "type": "module", "scripts": { "test": "vitest run", "test:watch": "vitest" }, "devDependencies": { "vitest": "1.6.1" }}vitest run: すべてのテストを一度実行して終了するコマンドです。CI(継続的インテグレーション)環境などでの単発実行に適しています。vitest: 開発環境では通常 Watch モード で起動します。ファイルの変更を検知し、関連するテストを自動的に再実行します(CI 環境では環境変数CIの検知などにより単発実行の Run モードで動作します)。
設定ファイル(vitest.config.ts / vite.config.ts)
特別な設定が不要な小規模プロジェクトでは設定ファイルなしでも動作しますが、カバレッジ測定やテスト対象パス、実行環境を明示したい場合は設定ファイルを用意します。
Vite を利用しているプロジェクトでは、既存の vite.config.ts に test プロパティを追加することで、開発環境とテスト環境の設定を共有できます。独立した vitest.config.ts を作成することも可能ですが、Vitest は vitest.config.ts を優先して読み込み、その場合は既存の vite.config.ts の設定が自動的には引き継がれないため注意してください。
独立した vitest.config.ts を作成する場合の記述例は以下のとおりです。
import { defineConfig } from 'vitest/config';
export default defineConfig({ test: { globals: false, // describe や expect などの明示的インポートを推奨 environment: 'node', // ブラウザ向けテストの場合は 'jsdom' や 'happy-dom' を指定 include: ['**/*.test.{js,ts}'], },});最小動作コード:基本的なテストの書き方
シンプルな計算関数を題材に、Vitest の最小動作テストコードを作成します。
テスト対象のコード(math.js)
export function add(a, b) { if (typeof a !== 'number' || typeof b !== 'number') { throw new TypeError('引数は数値である必要があります'); } return a + b;}テストコード(math.test.js)
import { describe, it, expect } from 'vitest';import { add } from './math.js';
describe('add関数', () => { it('2つの数値を正しく加算できること', () => { expect(add(2, 3)).toBe(5); expect(add(-1, 1)).toBe(0); });
it('数値以外の引数が渡された場合にTypeErrorをスローすること', () => { expect(() => add('2', 3)).toThrow(TypeError); expect(() => add(2, '3')).toThrow('引数は数値である必要があります'); });});テスト実行と実際の出力
以下のコマンドでテストを実行します。
npx vitest runターミナルには以下のようにテスト結果が出力されます。
RUN v1.6.1 /tmp/vitest-test
✓ math.test.js (2) ✓ add関数 (2) ✓ 2つの数値を正しく加算できること ✓ 数値以外の引数が渡された場合にTypeErrorをスローすること
Test Files 1 passed (1) Tests 2 passed (2) Start at 20:01:24 Duration 630mstoBe はプリミティブ値の厳密等価性(Object.is)を検証し、toThrow は例外の送出を検証します。例外をテストする場合は、テスト対象関数を無名関数 () => ... でラップして渡す必要があります。なお、実行結果の Start at や Duration、細かな表示形式は実行環境や Vitest のバージョンによって異なります。
モックと非同期処理のテスト(vi の活用)
実務のアプリケーションでは、外部APIの呼び出しやデータベースアクセスを分離してテストするために モック が不可欠です。
Vitest では vi オブジェクトを通じて強力なモック機能が提供されます。
非同期処理の対象コード(user.js)
外部の API クライアントを受け取り、ユーザー情報を取得する関数です。
export async function fetchUserData(userId, apiClient) { if (!userId) { throw new Error('ユーザーIDが指定されていません'); } const response = await apiClient.get(`/users/${userId}`); return response.data;}vi.fn() を使ったモックテスト(user.test.js)
import { describe, it, expect, vi } from 'vitest';import { fetchUserData } from './user.js';
describe('fetchUserData', () => { it('APIクライアントから正しくユーザーデータを取得できること', async () => { // vi.fn() でモック関数を作成し、返り値を設定 const mockApiClient = { get: vi.fn().mockResolvedValue({ data: { id: 'user-1', name: '田中太郎' }, }), };
const user = await fetchUserData('user-1', mockApiClient);
// 呼び出し引数の検証 expect(mockApiClient.get).toHaveBeenCalledWith('/users/user-1'); // 呼び出し回数の検証 expect(mockApiClient.get).toHaveBeenCalledTimes(1); // 取得したオブジェクトの検証 expect(user).toEqual({ id: 'user-1', name: '田中太郎' }); });
it('ユーザーIDが未指定の場合はエラーをスローすること', async () => { const mockApiClient = { get: vi.fn() };
// 非同期エラーの検証には rejects を使用 await expect(fetchUserData('', mockApiClient)).rejects.toThrow('ユーザーIDが指定されていません'); // API呼び出しが行われていないことを検証 expect(mockApiClient.get).not.toHaveBeenCalled(); });});実行結果
npx vitest run user.test.js RUN v1.6.1 /tmp/vitest-test
✓ user.test.js (2) ✓ fetchUserData (2) ✓ APIクライアントから正しくユーザーデータを取得できること ✓ ユーザーIDが未指定の場合はエラーをスローすること
Test Files 1 passed (1) Tests 2 passed (2) Start at 20:01:34 Duration 397msオブジェクトの構造や値を深く比較する場合は toBe ではなく toEqual を使用します。非同期の例外検証には await expect(...).rejects.toThrow(...) のパターンを用います。
アンチパターン vs ベストプラクティス
Vitest を実務プロジェクトで運用する際によく見られる落とし穴と、その改善策を比較します。
1. グローバルAPIの乱用 vs 明示的インポート
- アンチパターン:
globals: trueを安易に有効にし、テスト API をグローバル変数として利用する。ファイルごとの依存関係が暗黙的になり、テストランナーの変更やリンター・TypeScript 側のグローバル型設定の調整が必要になる場合があります。 - ベストプラクティス: デフォルト設定(
globals: false)のまま、原則としてimport { describe, it, expect } from 'vitest';のように明示的にインポートする。ファイルの依存先が明確になり、追加のグローバル型設定なしでも静的解析ツール(ESLintESLint [イーエスリント]JavaScriptやTypeScriptのコードに潜むバグや不要な記述をルールに沿って検出する静的解析ツール)や型チェックと扱いやすくなります。さらに TypeScript でジェネリックな型安全テストを行う際は TypeScriptジェネリクスの使い方 も合わせて参考にしてください。
2. モック状態のリセット忘れ vs モック状態の初期化
- アンチパターン: 複数のテストケースで同一のモック関数を使い回し、前のテストの呼び出し履歴(呼び出し回数や引数)や実装が残ったまま次のアサーションを行う。テスト順序依存の不安定なテスト(Flaky Test)の原因になります。
- ベストプラクティス:
beforeEachや設定ファイルの初期化オプションを利用し、各テストの実行前にモックの状態を初期化します。呼び出し履歴だけを消去する場合はvi.clearAllMocks()、モックの実装も含めてリセットする場合はvi.resetAllMocks()を使用します。PythonPython [パイソン]汎用プログラミング言語 のテストで前処理・後処理を共通化する pytest fixtureの使い方 と同様に、各テストの独立性を保つ設計が重要です。
モックを初期化する主なメソッドと対応する設定項目には以下の違いがあります。
| メソッド(設定オプション) | 呼び出し履歴 | モックの実装 | vi.spyOn() への影響 |
|---|---|---|---|
vi.clearAllMocks()(clearMocks: true) | 消去する | 維持する | 履歴のみ消去 |
vi.resetAllMocks()(mockReset: true) | 消去する | リセットする | 履歴・実装をリセット |
vi.restoreAllMocks()(restoreMocks: true) | 通常のモックは維持(※) | 通常のモックは維持(※) | 元のメソッドへ復元 |
※ vi.restoreAllMocks() は、主に vi.spyOn() で作成したスパイを対象に、元のメソッド実装へ戻すためのメソッドです。vi.fn() で作成したモック関数の呼び出し履歴や実装をリセットする場合は、vi.clearAllMocks() または vi.resetAllMocks() を使用します。なお、vi.mock() でモック化したモジュールの登録解除や再読み込みは、これらとは別の API で管理します。
※ モックの初期化に関する設定のデフォルト値は、Vitest のバージョンによって異なる場合があります。特に Vitest 5 では clearMocks がデフォルトで true に変更されています。
import { beforeEach, vi } from 'vitest';
beforeEach(() => { vi.clearAllMocks(); // 呼び出し履歴をリセット});なお、vi.clearAllMocks() は mockReturnValue などで設定したモックの実装を維持するため、テストケースごとに戻り値を変更したい場合はテスト内で再設定するか vi.resetAllMocks() を使用してください。
3. オブジェクト比較に toBe を使ってしまう
- アンチパターン: オブジェクトや配列の同値確認に
expect(result).toBe({ id: 1 })を使用する。参照先が異なるためテストが失敗します。 - ベストプラクティス: 値の内容を比較する場合は必ず
toEqualまたはtoStrictEqualを使用します。
境界ケースとテスト設計のポイント
実務で信頼性の高いテストコードを作成するためには、正常系だけでなく以下の境界ケースを意識してテストケースを網羅します。
- 空値・未定義値(Boundary Cases):
- 関数の仕様に応じて、
null、undefined、空文字""、空配列[]などが渡されたときに期待どおりに振る舞うか
- 関数の仕様に応じて、
- 型不正・例外ケース(Type / Error Cases):
- 想定外の型(文字列やオブジェクト)が渡された際に、適切なエラーメッセージと型で例外が発生するか
- 非同期処理のタイムアウトやネットワークエラー:
- モックで
mockRejectedValue(new Error('Network Error'))を設定し、障害発生時に呼び出し元が正常にリカバリできるか
- モックで
it('API通信失敗時に適切に例外が伝播すること', async () => { const mockApiClient = { get: vi.fn().mockRejectedValue(new Error('500 Internal Server Error')), };
await expect(fetchUserData('user-1', mockApiClient)).rejects.toThrow('500 Internal Server Error');});まとめ
Vitest は Vite の設定やエコシステムを活用できるテストフレームワークです。
- 効率的なテスト実行: Vite のモジュールグラフを活用し、変更に関連するテストを効率的に再実行
- 設定の共通化:
vite.config.tsの設定やプラグインを共有でき、ESM を前提とした環境を扱いやすい - 高い互換性: Jest と互換性の高い API 設計により、学習コストを抑えて導入しやすい
- TypeScript 実行対応: 追加のトランスパイル設定なしで TypeScript テストを実行可能(型チェックは
tscなどで別途実施) - 柔軟なモック:
vi.fn()やvi.spyOn()によるテストダブル作成と、vi.clearAllMocks()等による状態管理
なお、テストコードのデバッグ時にコードを素早くコメントアウトしたい場合は VSCodeでコメントアウトするショートカットキー を覚えておくと効率的です。
ユニットテストの導入はバグの早期発見だけでなく、コードのリファクタリングを安全に行うための土台となります。まずは小さなモジュールやユーティリティ関数から Vitest を導入してみてはいかがでしょうか。
以上で本記事の解説を終わります。
よいITライフを!
人気記事
- 1
- 2
- 3
- 4
- 5
デザインも解説も非常に美しい。実際に動きのあるパーツを作りながら学べるので達成感があります。