vitest-testing

Vitest のテスト

概要

Vitest は、同じ設定とプラグインエコシステムを共有する、Vite ネイティブのユニットテスト用フレームワークです。ネイティブ ESM サポート、テスト用のホットモジュールリプレースメント、並列実行に対応し、高速に動作するよう設計されています。

使用する場面： ユニットテスト、コンポーネントテスト、統合テスト、フックテスト、インソーステスト。React Testing Library を使った React コンポーネントのテスト。TanStack Query／Router／Form のパターンのテスト。

使用しない場面： エンドツーエンドテスト（Playwright を使用）、ビジュアルリグレッションテスト（Percy／Chromatic を使用）、負荷テスト（k6 を使用）。

クイックリファレンス

パターン	API	主なポイント
テスト構造	describe('suite', () => {})	関連するテストを整理します
単一テスト	test('behavior', () => {}) or it()	どちらもエイリアスです
パラメーター化テスト	test.each([...])('name', (arg) => {})	異なる入力で同じテストを実行します
並行テスト	test.concurrent('name', async () => {})	テストを並列で実行します
テストをスキップ	test.skip('name', () => {}) or skipIf(cond)	条件に応じてテストをスキップします
テストのみを実行	test.only('name', () => {})	デバッグ用に特定のテストを実行します
アサーション	expect(value).toBe(expected)	プリミティブ値を比較します
深い等価性	expect(obj).toEqual(expected)	オブジェクト／配列を比較します
非同期アサーション	await expect(promise).resolves.toBe(value)	Promise の解決をテストします
各テストの前処理	beforeEach(() => {})	各テストの前にセットアップします
各テストの後処理	afterEach(() => {})	各テストの後にクリーンアップします
モック関数	vi.fn()	スパイ関数を作成します
モックモジュール	vi.mock('./module')	モジュール全体を置き換えます
メソッドをスパイ	vi.spyOn(obj, 'method')	既存のメソッドの呼び出しを追跡します
モックをクリア	vi.clearAllMocks()	呼び出し履歴をクリアします
フェイクタイマー	vi.useFakeTimers()	setTimeout/setInterval を制御します
コンポーネントをレンダリング	render(<Component />)	テスト用に React コンポーネントをマウントします
ロールでクエリ	screen.getByRole('button')	アクセシビリティロールで要素を検索します
ユーザー操作	await user.click(element)	ユーザーイベントをシミュレートします
変更を待機	await waitFor(() => expect(...))	非同期の変更を待機します
非同期要素を検索	await screen.findByText('text')	クエリと待機を組み合わせます
フックをレンダリング	renderHook(() => useHook())	カスタムフックをテストします
フックの props を更新	rerender(newProps)	新しい props でフックを再レンダリングします
スナップショット	expect(value).toMatchSnapshot()	保存済みのスナップショットと比較します
インラインスナップショット	expect(value).toMatchInlineSnapshot()	テストファイルに保存されるスナップショットです
CLI で一度だけ実行	vitest run	ウォッチなしで一度だけ実行します
変更されたテストを実行	vitest --changed	git の変更によって影響を受けるテストです
名前で絞り込み	vitest -t "pattern"	テスト名を grep します
ソフトアサーション	expect.soft(value).toBe(x)	失敗しても続行し、すべての失敗を収集します
ポーリングアサーション	await expect.poll(() => val).toBe(x)	成功するまで再試行します
テストフィクスチャ	const test = base.extend<F>({...})	test.extend で再利用可能なセットアップを行います
巻き上げられるモック	vi.hoisted(() => ({ fn: vi.fn() }))	vi.mock ファクトリー用の変数です
テストをシャーディング	vitest --shard 1/3	CI ワーカー間で分割します
タグ	test('name', { tags: ['slow'] }, ...)	--tags-filter で絞り込みます
グローバルをスタブ	vi.stubGlobal('fetch', vi.fn())	グローバルオブジェクトを安全に置き換えます

よくある間違い

間違い	正しいパターン
非同期コンテンツに getBy を使う	非同期処理には findBy または waitFor を使います
実装の詳細をテストする	動作と公開 API をテストします
最初の選択肢として getByTestId を使う	getByRole、getByLabelText、getByText を優先します
userEvent.setup() を呼び出さない	必ず最初に const user = userEvent.setup() を呼び出します
テスト間で状態を共有する	beforeEach でリセットするか、新しいインスタンスを作成します
モックをクリーンアップしない	afterEach で vi.clearAllMocks() を使います
モックを使いすぎる	外部依存関係と API のみをモックします
テストでリトライを無効にしない	TanStack Query のテストでは retry: false を設定します
非同期処理をすぐにアサーションする	await waitFor() または findBy クエリを使います
レンダリング時に QueryClient を作成する	ラッパー内で一度だけ作成するか、useState を使います
テストライブラリのコードをテストする	ライブラリを信頼し、その使い方をテストします
ユーザーイベントを await しない	すべての user.* メソッドは Promise を返します
手動で act を使う	userEvent と Testing Library が処理します
メモ化せずにインラインで select を使う	TanStack Query 用に安定した関数として切り出します
vi.mock ファクトリー内で変数を使う	vi.hoisted() でモック変数を宣言します
複数のチェックに単一の expect を使う	expect.soft() ですべての失敗を収集します
非同期の待機にテスト内で setTimeout を使う	expect.poll() または vi.waitFor() を使います
再利用可能なセットアップに手動で beforeEach を使う	合成可能なセットアップには test.extend のフィクスチャを使います

委任

• テスト対象の検出：未テストのコードパスを見つけるには、Explore エージェントを使います
• カバレッジ分析：カバレッジを全面的に確認するには、Task エージェントを使います
• E2E テスト：playwright スキルが利用可能な場合は、E2E テストを委任します
• コードレビュー：テストを書いた後、code-reviewer エージェントに委任します

参考資料

• テストの基礎：構成、アサーション、ライフサイクルフック
• モック：vi.fn、vi.mock、vi.spyOn、モジュールのモック
• コンポーネントテスト：React Testing Library、クエリ、user-event
• フックのテスト：renderHook、非同期フック、TanStack のパターン
• テストのセットアップ：jest-dom マッチャー、クリーンアップ、カスタムレンダリング、MSW、ポリフィル
• 設定：vitest.config.ts、ワークスペース、カバレッジ、レポーター
• 高度なパターン：スナップショット、並行テスト、インソース、型のテスト
• CLI とフィルタリング：コマンド、ウォッチモード、タグ、シャーディング
• フィクスチャとコンテキスト：test.extend、スコープ設定、自動フィクスチャ、注入