unit-testing

単体テスト

このスキルを使うと、単体テストを作成、リファクタリング、レビュー、実行できます。単体テストとは、フレームワークの配線、データレイヤー、ブラウザーに依存せず、呼び出し元の視点から小さなエクスポート済みの契約を1つずつ検証する、高速で独立したチェックです。新しいテスト仕様を書くとき、既存のテストを強化するとき、何をアサートすべきか判断するとき、他の人の単体テストの変更を評価するときに活用してください。

ここでの規約はフレームワークに依存しません。プロジェクトが Jest、Vitest、Node の組み込みテストランナー、または類似のランナーを使っていても適用できます。例では、ほとんどのランナーに共通する用語である TypeScript の describe／it／expect を使っています。it／test、アサーションのエントリーポイント、モック関連の呼び出しは、プロジェクトのテストランナーが提供する機能に読み替えてください。

プロジェクトが特定のランナー向けの機能を提供している場合、その機能が設定ファイル、プールと分離、カバレッジプロバイダー、レポーター、ランナー独自のモック機能やフェイクタイマー API などの仕組みを担当し、このスキルは何をアサートするか、テスト仕様をどう構成するか、そもそもその動作を単体テストで扱うべきかを担当します。どのオプションや呼び出しを使うかが問題ならランナーの機能を参照し、テストで何を検証すべきかが問題ならこのスキルを参照してください。

単体テストが役立つのは、小さなエクスポート済みの契約を、すばやく、独立して、外部からの視点で検証するときです。一方、実装の詳細に過剰適合したり、信頼性の高い統合テストや E2E テストの代わりになったりすると、負担になります。そのため、この機能では、単体テストを書かない判断と、その動作をより広範なテストに振り分ける方法も扱います。

このドキュメントに記載される「MUST」、「MUST NOT」、「REQUIRED」、「SHALL」、「SHALL NOT」、「SHOULD」、「SHOULD NOT」、「RECOMMENDED」、「MAY」、「OPTIONAL」は、RFC 2119 の定義に従って解釈してください。

テストの範囲

testing-scope.md では、以下について説明しています。

• 判断図を使って、ある動作を単体テスト、統合テスト、E2E テストのどれで扱うべきかを判断する
• 純粋なヘルパーのテストを小さく保ち、ブラウザー、データレイヤー、フレームワークの動作をより広範なテストに振り分ける
• 単体テストの信頼性が統合テストや E2E テストより低くなるケースを見極める
• ネイティブなエビデンスがあると主張せずに、フレーム依存のテストダブルで関連する中間状態と完了順序を保持する
• レンダラーを利用できない場合に、代替の本番 UI やピクセルエビデンスがあると主張せずに、公開されたジオメトリや設定を検証する

テスト仕様の構成と命名

spec-structure-and-naming.md では、以下について説明しています。

• describe(...) とテストケースのブロックを追加、改名、再グループ化、レビューする
• 種類ごとに対象を命名する：呼び出し可能なものには ()、UI コンポーネントには山括弧、呼び出し可能ではない契約には接尾辞を付けない
• 明確な検証文として読めるシナリオ名を書く
• 関数名を重複させずに、繰り返し現れる条件や状況をグループ化する

動作と実装の詳細

behavior-and-implementation-details.md では、以下について説明しています。

• プライベートヘルパー、依存関係の内部実装、コールバックの仕組み、呼び出し形式に過剰適合するテストを避ける
• 呼び出し元の視点から、エクスポートされた動作にアサーションを絞る
• 実装の詳細が実際に公開契約の一部であるかを判断する
• 外部仕様やプロジェクトの公開契約で保証された正確な値と、コピーされたプライベートなリテラルを区別する

フィクスチャ、フェイク、AHA

fixtures-fakes-and-aha.md では、以下について説明しています。

• フィクスチャ、セットアップヘルパー、境界フェイク、モック、スパイ、共有定数を作成する
• テストケースごとの分かりやすさが必要な場合に、時期尚早な抽象化より重複を選ぶ
• 再利用可能なテストヘルパーを分かりやすく、用途を絞り、動作を重視したものにする

アサーション、スナップショット、副作用

assertions-snapshots-and-side-effects.mdでは、以下について説明しています。

• 値、非同期エラー、副作用、モック呼び出しに対するアサーションの選び方
• 単に何かがレンダリングされることを確認するのではなく、分岐を識別できる観測可能な出力と否定的なケースをアサートする方法
• スナップショットが適切な場面と、対象を絞り込む方法
• 偶発的な実装の詳細に依存せず、観測可能な結果を検証する方法

スキーマと型

schemas-and-types.mdでは、以下について説明しています。

• スキーマ、コーデック、デコード後のレスポンス形状、コレクション／リストのレスポンスのデコードをテストする方法
• 型のみのモジュールとコンパイル時の契約を扱う方法
• 実行時のスキーマチェックとコンパイル時の型の期待値のバランスを取る方法

レビューチェックリスト

review-checklist.mdでは、以下について説明しています。

• ユニットテストの実装に対する自己レビューまたはコードレビュー
• 構成、命名、フィクスチャ、モック、アサーション、対象範囲の確認
• 任意のカバレッジゲート：プロジェクトのカバレッジコマンド、設定されたしきい値、ignore プラグマの適切な運用
• ユニットテストでは十分な確信を持って動作をカバーできない場合に、残るリスクを報告する方法

プロジェクトのデフォルト

これらのデフォルトは意図的に簡潔にしています。例、エッジケース、レビュー基準については、リンク先のリファレンスに従ってください。「プロジェクトの慣例」とあるルールについては、既存のローカルパターンに従ってください。既存のパターンがない場合は、パターンを定めて一貫性を保ってください。

ガイドライン：

• MUST：既存のローカルパターンで別の配置が求められる場合を除き、プロジェクトで採用されているテストファイルの命名規則（*.test.ts や *.spec.ts など）に従って、ユニットテストをソースコードの隣に配置する必要があります。
• MUST：ランナーが明示的なインポートを必要とする、またはサポートしている場合は、暗黙のグローバルスコープのシンボルに依存せず、テストフレームワークの API を明示的にインポートする必要があります。
• MUST：プロジェクトで選択したテストケース関数（it または test）を一貫して使用し、同じプロジェクト内で別の表記と混在させてはいけません。
• MUST：対象を絞った失敗を調査する場合を除き、プロジェクトのユニットテストコマンド（npm run test:unit など）を使ってユニットテストを実行する必要があります。
• MUST：ユニットテストを追加または変更した後は、プロジェクトのフォーマットコマンドと Lint コマンドを実行し、プロジェクトに型チェックコマンドがある場合はそれも実行する必要があります。
• SHOULD：確信を得るために、フレームワークの実行時の配線、データレイヤー、ブラウザーの動作、レンダリング、ルーティング、またはユーザー向け UI が必要な場合は、インテグレーションテストまたは E2E テストを優先することを推奨します。